busted/index.html at gh-pages · hishamhm/busted

944 lines (791 loc) · 35.4 KB
<!doctype html>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="chrome=1">
    <title>busted : Elegant Lua unit testing, by Olivine-Labs</title>
    <link href='http://fonts.googleapis.com/css?family=Open+Sans:400italic,700italic,400,700' rel='stylesheet' type='text/css'>
    <link rel="stylesheet" href="css/solarized-light.css">
    <link rel="stylesheet" href="css/bootstrap.min.css">
    <link rel="stylesheet" href="css/styles.css">
    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
    <!--[if lt IE 9]>
    <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
  <body data-spy="scroll" data-target=".sidebar">
    <div class="container">
      <header class="hero-unit">
        <h1 class="remove-bottom">busted</h1>
        <h2>Elegant Lua unit testing.</h2>
      </header>
    <div class="navbar navbar-fixed-top">
      <div class="container">
        <a class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </a>
        <a class="navbar-brand" href="http://olivinelabs.com/busted">Busted</a>
        <div class="nav-collapse collapse">
          <nav>
            <ul class="nav navbar-nav">
              <li><a href="https://github.com/Olivine-Labs/busted"><span class="icon icon-folder-open icon-white"></span> View On <strong>GitHub</strong> @ <small>Olivine-Labs/busted</small></a></li>
              <li><a href="https://github.com/Olivine-Labs/busted/zipball/master"><span class="icon icon-download-alt icon-white"></span> <strong>ZIP File</strong></a></li>
              <li><a href="https://github.com/Olivine-Labs/busted/tarball/master"><span class="icon icon-download-alt icon-white"></span> <strong>TAR Ball</strong></a></li>
              <li><a href="#usage"><strong>Install:</strong> luarocks install busted</a></li>
            </ul>
          </nav>
        </div>
      </div>
    <div class="container">
      <div class="row">
        <div class="col col-lg-3 sidebar">
          <ul class="nav nav-list sidenav">
            <li><a href="#overview"><i class="icon-chevron-right"></i>Overview</a></li>
            <li><a href="#usage"><i class="icon-chevron-right"></i>Usage</a></li>
            <li><a href="#defining-tests"><i class="icon-chevron-right"></i>Defining Tests</a></li>
            <li><a href="#asserts"><i class="icon-chevron-right"></i>Asserts</a></li>
            <li><a href="#spies-mocks-stubs"><i class="icon-chevron-right"></i>Spies, Stubs & Mocks</a></li>
            <li><a href="#async-tests"><i class="icon-chevron-right"></i>Async Tests</a></li>
            <li><a href="#private"><i class="icon-chevron-right"></i>Private</a></li>
            <li><a href="#output-types"><i class="icon-chevron-right"></i>Output Types</a></li>
            <li><a href="#moonscript"><i class="icon-chevron-right"></i>Moonscript</a></li>
            <li><a href="#language-packs"><i class="icon-chevron-right"></i>i18n</a></li>
            <li><a href="#contributing"><i class="icon-chevron-right"></i>Contributing</a></li>
            <li>
                <h4>Status</h4>
                <p>Version: <strong>1.11.0</strong></p>
                  <a href="http://travis-ci.org/#!/Olivine-Labs/busted/builds"><img src="https://github-camo.global.ssl.fastly.net/5c9ddc5d7b57bc68f2b2c26d8a7ad81366aa80db/68747470733a2f2f7365637572652e7472617669732d63692e6f72672f4f6c6976696e652d4c6162732f6275737465642e706e67" alt="travis-ci status" data-canonical-src="https://secure.travis-ci.org/Olivine-Labs/busted.png" style="max-width:100%;"></a>
              </a>
            </li>
          </ul>
        </div>
        <div class="col col-lg-9">
          <section id="overview">
            <h2>What's <em>busted</em>, precious?</h2>
              busted is a unit testing framework with a focus on being
              <strong>easy to use</strong>. busted works with 
              <strong>lua &gt;= 5.1</strong>, <strong>moonscript</strong>,
              and <strong>LuaJIT &gt;= 2.0.0 </strong>
            </p>
              busted test specs read naturally without being too verbose. You can
              even chain asserts and negations, such as <code data-language="lua">assert.not.equals</code>.
              Nest blocks of tests with contextual descriptions using <code data-language="lua">describe</code>, and
              add tags to blocks so you can run arbitrary groups of tests.
            </p>
              An extensible assert library allows you to extend and craft your
              own assert functions specific to your case with method chaining.
              A modular output library lets you add on your own output format,
              along with the default pretty and plain terminal output, JSON
              with and without streaming, and TAP-compatible output that allows
              you to run busted specs within most CI servers. You can even
              register phrases for internationaliation with custom or built-in
              <a href="#language-packs">language packs</a>.
            </p>
<pre><code data-language="lua">describe("Busted unit testing framework", function()
  describe("should be awesome", function()
    it("should be easy to use", function()
      assert.truthy("Yup.")
    it("should have lots of features", function()
      -- deep check comparisons!
      assert.are.same({ table = "great"}, { table = "great" })
      -- or check by reference!
      assert.are_not.equal({ table = "great"}, { table = "great"})
      assert.truthy("this is a string") -- truthy: not false or nil
      assert.True(1 == 1)
      assert.is_true(1 == 1)
      assert.falsy(nil)
      assert.has_error(function() error("Wat") end, "Wat")
    it("should provide some shortcuts to common functions", function()
      assert.are.unique({{ thing = 1 }, { thing = 2 }, { thing = 3 }})
    it("should have mocks and spies for functional tests", function()
      local thing = require("thing_module")
      spy.on(thing, "greet")
      thing.greet("Hi!")
      assert.spy(thing.greet).was.called()
      assert.spy(thing.greet).was.called_with("Hi!")
</code></pre>
<pre><code>busted test.lua</code></pre>
            <div class="thumbnail">
              <img src="img/run.png" />
            </div>
          </section>
          <section class="division" id="usage">
            <h2>Usage</h2>
            <h4>Installation</h4>
              Install busted through Luarocks. Depending on your environment,
              you can <code>apt-get luarocks</code>, <code>brew install
              luarocks</code>, or otherwise get it from
              <a href="http://luarocks.org">luarocks.org</a>. The latest
              busted release will always be available on
              <a href="http://rocks.moonscript.org/">Moonrocks</a>,
              but is also uploaded frequently to luarocks. Optionally follow
              the instructions on <a href="http://rocks.moonscript.org/">Moonrocks</a>, and then run
              <code>luarocks install busted</code> to install the library and
              CLI.
            </p>
              You can also install the latest or a branch by cloning the
              <a href="https://github.com/Olivine-Labs/busted">busted
              repository</a>, and running <code>luarocks make</code> from the
              directory.
            </p>
            <h4>CLI: Running Busted</h4>
<pre><code>Usage: busted [OPTIONS]  [ROOT]
  ROOT                  test script file/folder. Folders will be
                        traversed for any file that matches the
                        --pattern option. (optional, default: spec)
  --version             prints the program's version and exits
  -o, --output=LIBRARY  output library to load (default: utf_terminal)
  -d, --cwd=cwd         path to current working directory (default: ./)
  -p, --pattern=pattern only run test files matching the Lua pattern
                        (default: _spec)
  -t, --tags=tags       only run tests with these #tags
  --exclude-tags=tags   do not run tests with these #tags, takes
                        precedence over --tags
  -m, --lpath=path      optional path to be prefixed to the Lua module
                        search path (default:
                        ./src/?.lua;./src/?/?.lua;./src/?/init.lua)
  --cpath=path          optional path to be prefixed to the Lua C module
                        search path (default:
                        ./csrc/?.so;./csrc/?/?.so;)
  -r, --run=run         config to run from .busted file
  --lang=LANG           language for error messages (default: en)
  -c, --coverage        do code coverage analysis (requires 'LuaCov' to
                        be installed)
  -v, --verbose         verbose output of errors
  -s, --enable-sound    executes 'say' command if available
  --suppress-pending    suppress 'pending' test output
  --defer-print         defer print to when test suite is complete
</code></pre>
            <h4>Predefined Busted Tasks</h4>
              Busted 1.6 added a concept of "tasks", or predefined busted
              configuration options. You can create a <code>.busted</code> file in the root,
              which is automatically loaded if it exists. Default options are
              run if no task is specified. You can add any argument available
              in the CLI (listed above), using the long name. (Use
              <code>verbose = true</code>, not <code>v = true</code>.) Any arguments you specify will
              override those set in the task. An example <code>.busted</code> file might 
              look like:
            </p>
<pre><code data-language="lua">return {
  default = {
    verbose = true
  apiUnit = {
    tags = "api",
    ROOT = "spec/unit"
    verbose = true
}</code></pre>
              This allows you to run <code>busted --run=apiUnit</code>, which
              will run the equivalent of
              <code>busted --tags=api --verbose spec/unit</code>. If you only
              run <code>busted</code>, it will run the equivalent of
              <code>busted --verbose</code>.
            </p>
          </section>
          <section class="division" id="defining-tests">
            <h2>Defining Tests</h2>
              Set up your tests using <code>describe</code> and <code>it</code>
              blocks. These take a description (to be used for output) and
              a callback (which either defines more blocks or contains the
              tests themselves. Describe blocks can have more decribe blocks
              nested. You can also use the functions <code>before_each</code>
              and <code>after_each</code> to define functions that should be
              run before any nested tests, and <code>setup</code> and <code>teardown</code>
              for functions that should be run before and after the <code>describe</code> block.
            </p>
              You can also use the <code>pending</code>
              method to leave a placerholder for a test you plan on writing
              later.
            </p>
              Tag your tests with #hashtags to run specific tests. When you
              run busted from the command line, add the <code>-t</code> flag to run a
              given tag. Seperate tags by commas to run more than one tag.
            </p>
            <h4 id="describe">Describe: Context blocks</h4>
              Describe takes a title and a callback, and can be nested. You can
              also use <code>context</code> as an alias if you like.
            </p>
<pre><code data-language="lua">describe("a test", function()
  -- tests go here
describe("a nested block", function()
  describe("can have many describes", function()
    -- tests
  -- more tests pertaining to the top level
</code></pre>
          <h4 id="describe">Describe: Tagging Tests</h4>
          <p>
            Tag tests using #tags, and run using the <code>-t</code> flag to only run that
            test.
          </p>
<pre><code data-language="lua">describe("a test #tag", function()
  -- tests go here
describe("a nested block #another", function()
  describe("can have many describes", function()
    -- tests
  -- more tests pertaining to the top level
</code></pre>
          <pre><code>busted ./test.lua -t="tag"</code></pre>
          <p>This runs the first group of tests, but not the second.</p>
          <pre><code>busted ./test.lua -t="tag,another"</code></pre>
          <p>This runs both groups.</p>
          <p>You can also exclude tests that use tags with
            the <code>--exclude-tags</code> flag.  This can be useful,
            for example, if tests using a certain tag take a long time
            to run and you want busted to skip them.  This would run
            all tests except the second group in the example above.</p>
          <pre><code>busted ./test.lua --exclude-tags="another"</code></pre>
          <p>If you use <code>-t, --tags</code> and <code>--exclude-tags</code>
            together then <code>--exclude-tags</code> always takes precedence.</p>
<pre><code data-language="lua">describe("a test with two tags #one #two", function ()
</code></pre>
          <pre>><code>busted ./test.lua --tags="one" --exclude-tags="two"</code></pre>
          <p>Both tags refer to the same test but busted will not run it since
            <code>--exclude-tags</code> takes precedence.</p>
          <pre><code>busted ./test.lua --tags="one" --exclude-tags="one"</code></pre>
          <p>It is ok for different tags to refer to the same tests, but using the
            exact same tag name with <code>--tags</code> and <code>--exclude-tags</code>
            at the same time is an error.</p>
          <h4 id="it">It: Defining tests</h4>
          <p>
            An <code>it</code> block takes a title and a callback. Tests fail if an
            uncaptured error is thrown (assert functions throw errors for
            failed tests).
          </p>
<pre><code data-language="lua">describe("busted", function()
  it("has tests", function()
    local obj1 = { test = "yes" }
    local obj2 = { test = "yes" }
    assert.same(obj1, obj2)
</code></pre>
          <h4 id="before-each">Before Each &amp; After Each; Setup &amp; Teardown</h4>
          <p>
            <code>before_each</code> runs before each child test, and
            <code>after_each</code> (you guessed it) runs after. <code>setup</code>
            runs first in a <code>describe</code> block, and <code>teardown</code>
            runs last in a <code>describe</code> block.
          </p>
<pre><code data-language="lua">describe("busted", function()
  local obj1, obj2
  local util
  setup(function()
    util = require("util")
  teardown(function()
    util = nil
  before_each(function()
    obj1 = { test = "yes" }
    obj2 = { test = "yes" }
  it("sets up vars with the before_each", function()
    obj2 = { test = "no" }
    assert.are_not.same(obj1, obj2)
  it("sets up vars with the before_each", function()
    -- obj2 is reset thanks to the before_each
    assert.same(obj1, obj2)
  describe("nested", function()
    it("also runs the before_each here", function()
      -- if this describe also had a before_each, it would run
      -- both, starting with the parents'. You can go n-deep.
</code></pre>
          <p>
            <code>finally</code> is also available as a lighter alternative
            that avoids setting upvalues.
          </p>
          <pre><code data-language="lua">it('checks file contents',function()
  local f = io.popen('stupid_process')
  -- ensure that once test has finished f:close() is called
  -- independent of test outcome
  finally(function() f:close() end)
  it('does a thing', function()
    -- do things with f
</code></pre>
          <h4 id="pending">Pending</h4>
          <p>
            Pending functions are placeholders for tests you plan to write
            (or fix) later.
          </p>
<pre><code data-language="lua">describe("busted pending tests", function()
  pending("I should finish this test later")
</code></pre>
        </section>
        <section class="division" id="asserts">
          <h2>Asserts</h2>
          <p>
            Asserts are the core of busted- they're what you use to actually
            write your tests. Asserts in busted work by chaining a mod value
            by using <code>is</code> or <code>is_not</code>, followed by the assert you wish to use.
            It's easy to extend busted and add your own asserts by building an
            assert with a commmon signature and <a href="#assert-extend">registering it</a>.
          </p>
          <p>
            Busted uses the <a href="https://github.com/Olivine-Labs/luassert">luassert library</a> to 
            provide the assertions. Note that some of the assertion/modifiers are Lua keywords (
            <code>true</code>, <code>false</code>, <code>nil</code>, <code>function</code>, and <code>
            not</code>) and they cannot be used using '.' chaining because that results in compilation 
            errors. Instead chain using '_' (underscore) or use one or more capitals in the reserved 
            word, whatever your coding style prefers.
          </p>
          <h4 id="assert-is">Is &amp; Is Not</h4>
          <p>
            <code>is</code> and <code>is_not</code> flips the expected value 
            of the assertion; if <code>is_not</code> is used, the assertion 
            fails if it doesn't throw an error. <code>are</code>, 
            <code>are_not</code>, <code>has_no</code>, <code>was</code>,
            and, <code>was_not</code> are aliased as well 
            to appease your grammar sensibilities. <code>is</code>
            and its aliases are always optional.
          </p>
<pre><code data-language="lua">describe("some assertions", function()
  it("tests positive assertions", function()
    assert.is_true(true)  -- Lua keyword chained with _
    assert.True(true)     -- Lua keyword using a capital
    assert.are.equal(1, 1)
    assert.has.errors(function() error("this should fail") end)
  it("tests negative assertions", function()
    assert.is_not_true(false)
    assert.are_not.equals(1, "1")
    assert.has_no.errors(function() end)
</code></pre>
          <h4 id="assert-equals">Equals</h4>
          <p>
            Equals takes 1-n arguments and checks if they are the
            <em>same instance</em>. This is equivalent to calling object1 == object2.
          </p>
<pre><code data-language="lua">describe("some asserts", function()
  it("checks if they're equals", function()
    local expected = 1
    local obj = expected
    assert.are.equals(expected, obj)
</code></pre>
          <h4 id="assert-same">Same</h4>
          <p>
            Same takes 1-n arguments and checks if they are they are similar
            by doing a deep compare.
          </p>
<pre><code data-language="lua">describe("some asserts", function()
  it("checks if they're the same", function()
    local expected = { name = "Jack" }
    local obj = { name = "Jack" }
    assert.are.same(expected, obj)
</code></pre>
          <h4 id="assert-true">True &amp; Truthy; False &amp; Falsy</h4>
          <p>
            <code>true</code> evaluates if the value is the boolean <code>true</code>; <code>truthy</code> checks
            if it's non-false and non-nil (as if you passed it into a boolean
            expression in Lua. <code>false</code> and <code>falsy</code> are the opposite;
            <code>false</code> checks for the boolean <code>false</code>, <code>falsy</code> checks for false or nil.
          </p>
<pre><code data-language="lua">describe("some asserts", function()
  it("checks true", function()
    assert.is_true(true)
    assert.is.not_true("Yes")
    assert.is.truthy("Yes")
  it("checks false", function()
    assert.is_false(false)
    assert.is.not_false(nil)
    assert.is.falsy(nil)
</code></pre>
          <h4 id="assert-error">Error</h4>
          <p>
            Makes sure an error exception is fired that you expect.
          </p>
<pre><code data-language="lua">describe("some asserts", function()
  it("should throw an error", function()
    assert.has_error(function() error("Yup,  it errored") end)
    assert.has_no.errors(function() end)
  it("should throw the error we expect", function()
    local errfn = function()
      error("DB CONN ERROR")
    assert.has_error(errfn, "DB CONN ERROR")
</code></pre>
          <h4 id="assert-extend">Extending Your Own Assertions</h4>
          <p>
            Add in your own assertions to reuse commonly written code. You
            can register error message keys for both positive (<code>is</code>
            and negative (<code>is_not</code>) cases for multilingual
            compatibility as well ("en" by default.)
          </p>
<pre><code data-language="lua">local s = require("say")
local function has_property(state, arguments)
  local has_key = false
  if not type(arguments[1]) == "table" or #arguments ~= 2 then
    return false
  for key, value in pairs(arguments[1]) do
    if key == arguments[2] then
      has_key = true
  # state.mod holds true or false, which is true normally, or false if we
  # are negating the assertion by using is_not or one of its aliases.
  return state.mod == has_key
s:set("assertion.has_property.positive", "Expected property %s in:\n%s")
s:set("assertion.has_property.negative", "Expected property %s to not be in:\n%s")
assert:register("assertion", "has_property", has_property, "assertion.has_property.positive", "assertion.has_property.negative")
describe("my table", function()
  it("has a name property", function()
    assert.has_property({ name = "Jack" }, "name")
</code></pre>
        </section>
        <section class="division" id="spies-mocks-stubs">
          <h2>Spies, Stubs, &amp; Mocks</h2>
          <p>
            Spies are essentially wrappers around functions that keep track
            of data about how the function was called, and by default calls
            the function. Stubs are the same as spies, except they return
            immediately without calling the function. <code>mock(table, stub)</code>
            returns a table whose functions have been wrapped in spies or
            stubs.
          </p>
          <h4 id="spies">Spies</h4>
          <p>
            Spies contain two methods: <code>on</code> and <code>new</code>.
            <code>spy.on(table, method_name)</code> does an in-place
            replacement of a table's method, and when the original method is
            called, it registers what it was called with and then calls the
            original function.
          </p>
<pre><code data-language="lua">describe("spies", function()
  it("registers a new spy as a callback", function()
    local s = spy.new(function() end)
    s(1, 2, 3)
    s(4, 5, 6)
    assert.spy(s).was.called()
    assert.spy(s).was.called(2) -- twice!
    assert.spy(s).was.called_with(1, 2, 3) -- checks the history
  it("replaces an original function", function()
    local t = {
      greet = function(msg) print(msg) end
    local s = spy.on(t, "greet")
    t.greet("Hey!") -- prints 'Hey!'
    assert.spy(t.greet).was_called_with("Hey!")
    t.greet:revert()  -- reverts the stub
    t.greet("Hello!") -- prints 'Hello!', will not pass through the spy
    assert.spy(s).was_not_called_with("Hello!")
</code></pre>
          <h4 id="stubs">Stubs</h4>
          <p>
            Stubs act similarly to spies, except they do not call 
            the function they replace. This is useful for testing things
            like data layers.
          </p>
<pre><code data-language="lua">describe("stubs", function()
  it("replaces an original function", function()
    local t = {
      greet = function(msg) print(msg) end
    stub(t, "greet")
    t.greet("Hey!") -- DOES NOT print 'Hey!'
    assert.stub(t.greet).was.called_with("Hey!")
    t.greet:revert()  -- reverts the stub
    t.greet("Hey!") -- DOES print 'Hey!'
</code></pre>
          <h4 id="mocks">Mocks</h4>
          <p>
            Mocks are tables whose functions have been wrapped in spies,
            or optionally stubs. This is useful for checking execution
            chains. Wrapping is recursive, so wrapping functions in 
            sub-tables as well.
          </p>
<pre><code data-language="lua">describe("mocks", function()
  it("replaces a table with spies", function()
    local t = {
      thing = function(msg) print(msg) end
    local m = mock(t) -- mocks the table with spies, so it will print
    m.thing("Coffee")
    assert.spy(m.thing).was.called_with("Coffee")
  it("replaces a table with stubs", function()
    local t = {
      thing = function(msg) print(msg) end
    local m = mock(t, true) -- mocks the table with stubs, so it will not print
    m.thing("Coffee")
    assert.stub(m.thing).was.called_with("Coffee")
</code></pre>
        </section>
        <section class="division" id="async-tests">
          <h2>Async Tests</h2>
          <p>
            Sometimes you need to write tests that work with asynchronous calls
            such as when dealing with HTTP requests, threads, or database
            calls.
          </p>
<pre><code data-language="lua">-- you will need libev to run the following example which uses 'ev'
local ev = require'ev'
-- `asynchronous_call` is function to act as our asynchronous, time-taking test. In
-- reality, you'll call out to your asynchronous code instead.
local asynchronous_call = function(on_timeout)
  ev.Timer.new(function()
    on_timeout()
  end,0.01):start(ev.Loop.default)
-- specify the loop framework ('copas' or 'ev')
setloop('ev')
describe('Some async stuff', function()
  -- The callbacks for `setup`, `teardown`, `before_each`, `after_each` and `it` all
  -- get a "done" parameter. This parameter is a callback function that must be called
  -- to report the test as succesful.
  it('make some async test',function(done)  -- `done` callback provided by busted
    -- The asynchroneous callback itself must be wrapped in `async`, this will notify busted
    -- in case of a failure. If it fails outside the callback the test will hang forever
    -- (timeouts have not been implemented yet).
    asynchronous_call(async(function()      -- wrap in `async` to catch any errors
      assert.is_true(true)                  -- an error inside `async` will be reported as a failure
      done()                                -- calling `done` will be reported as success
</code></pre>
        </section>
        <section class="division" id="private">
          <h2>Private</h2>
          <p>
            Before Busted executes any tests it will define a global <code>_TEST</code> that
            can be used to expose private elements only in case of testing.
          </p>
<pre><code data-language="lua">-- a new module with private elements to be tested
local mymodule = {}
local private_element = {"this", "is", "private"}
function mymodule:display()
  print(string.concat(private_element, " "))
-- export locals for test
if _TEST then
  -- setup test alias for private elements using a modified name
  mymodule._private_element = private_element
return mymodule
</code></pre>
          <p>
          In the test specs it can be tested;
          </p>
<pre><code data-language="lua">local mymodule = require("mymodule")
describe("Going to test a private element", function()
  it("tests the length of the table", function()
    assert.is.equal(#mymodule._private_element, 3)
</code></pre>
        </section>
        <section class="division" id="output-types">
          <h2>Output Types</h2>
          <p>
            Busted supports several output types by default, and it's easy to
            extend busted to include your own output types.
          </p>
          <h4 id="output-utf_terminal">UTF and Coloring: Pretty Terminal Output with utf_terminal</h4>
          <p>Uses ansicolors and utf to display a concise but informative output.</p>
          <img src="img/run.png" />
          <h4 id="output-plain_terminal">Clean output with plain_terminal</h4>
          <p>Uses safe characters and no coloring.</p>
          <img src="img/plain.png" />
          <h4 id="output-json">JSON for integration with json output</h4>
          <p>Useful for streaming or loading all results at once with the --defer-print flag.</p>
          <img src="img/json.png" />
          <h4 id="output-json">TAP for use with CI systems</h4>
          <p><a href="http://en.wikipedia.org/wiki/Test_Anything_Protocol">TAP</a> is an agnostic protocol used by most automated testing suites.</p>
          <img src="img/tap.png" />
          <h4>Registering Your Own Output Type</h4>
          <p>
            If you pass the <code>-o</code> flag a path instead of a name (such as in <code>busted spec -o thing.lua</code>, it will look 
            in that path to load the output file. Check out the 
            <a href="https://github.com/Olivine-Labs/busted/tree/master/src/output" targt="_blank">existing output files</a>
            for examples. It should have a signature like:
          </p>
<pre><code data-language="lua">
-- custom_output.lua
local output = function()
    header = function(context_tree)
      -- return if you want to write something specific at the top of the output
    footer = function(context_tree)
      --  return if you want to write something specific at the bottom of the output
    formatted_status = function(statuses, options, ms)
      -- displays at the end of the test. options contains options passed
      -- into the busted CLI, and ms is the ms spent running the tests.
      -- statuses is a list of test statuses after being run. You usually
      -- only return if options.defer_print.
    currently_executing = function(test_status, options)
      -- Fired off if options.defer_print is not true. You probably want to
      -- io.write() a status and then io.flush() to write it to output.
return output
</code></pre>
        </section>
        <section class="division" id="moonscript">
          <h2>Moonscript</h2>
          <p>
            <a href="http://moonscript.org" target="_blank">Moonscript</a> is
            a dynamic scripting language that compiles to Lua. Busted supports
            Moonscript natively without any additional compilation steps, and
            will redirect line numbers to show the proper line numbers for
            failing tests.
          </p>
<pre><code data-language="moonscript">#source: moonscript_spec.moon
describe "moonscript tests", ->
  it "runs", ->
    assert.are.equal true, true
  it "fails", ->
    assert.error(-> assert.are.equal false, true)
describe "async moonscript tests", ->
  it "runs async tests", async, (done) ->
    some_asynchronous_call(guard ->
      assert.is_true true
      done()
</code></pre>
        </section>
        <section class="division" id="language-packs">
          <h2>I18n</h2>
          <p>
            Busted supports English (en), Arabic (ar), French (fr), Dutch (nl),
            Russian (ru), German (de), Japanese (ja), Chinese (zh), and Ukranian (ua) by default.
            Check out the <a href="https://github.com/Olivine-Labs/busted/tree/master/src/languages" targt="_blank">existing language packs</a>
            and send in a pull request.
          </p>
          <h4 id="adding-language"></h4>
          <p>
            Busted supports adding in new languages easily. Pass a <code>--lang</code>
            parameter to choose one of the built-in languages, or a path
            to a lua file to run containing your own language. Don't forget
            to submit languages in pull requests as you make them!
            Check out the <a href="https://github.com/Olivine-Labs/busted/tree/master/src/languages" targt="_blank">existing language packs</a>
            to see a template for what you should replace. Copy any of the
            existing files. It uses the <a href="https://github.com/Olivine-Labs/say">say</a>
            string key/value store for registration.
          </p>
          <p>
            Examples: <code>busted spec --lang=ar</code> or
            <code>busted spec --lang=se.lua</code>
          </p>
        </section>
        <section class="division" id="contributing">
          <h2>Contributing</h2>
          <p>
            You can help! It's as easy as submitting a <a href="https://github.com/Olivine-Labs/busted/issues">suggestion or issue</a>,
            or <a href="https://github.com/Olivine-Labs/busted">check out the code for yourself</a>
            and submit your changes in a pull request. We could especially use help with
            translations - check out the src/languages folder in <a href="https://github.com/Olivine-Labs/busted/tree/master/src/languages">busted</a>
            and <a href="https://github.com/Olivine-Labs/luassert/tree/master/src/languages">luassert</a>
            to see if you can help.
          </p>
          <h4>Contributors</h4>
          <ul>
            <li><a href="https://github.com/DorianGray">DorianGray</a></li>
            <li><a href="https://github.com/ajacksified">ajacksified</a></li>
            <li><a href="https://github.com/Tieske">Tieske</a></li>
            <li><a href="https://github.com/a-b">a-b</a></li>
            <li><a href="https://github.com/Yonaba">Yonaba</a></li>
            <li><a href="https://github.com/nilnor">nilnor</a></li>
            <li><a href="https://github.com/kikito">kikito</a></li>
            <li><a href="https://github.com/faulkner">faulkner</a></li>
            <li><a href="https://github.com/Eloff">Eloff</a></li>
            <li><a href="https://github.com/lipp">lipp</a></li>
            <li><a href="https://github.com/leafo">leafo</a></li>
            <li><a href="https://github.com/ejmr">emjr</a></li>
            <li>bokko</li>
          </ul>
          <p>And many thanks to the libraries that help make busted possible!</p>
        </section>
      </div>
      <div class="row">
        <footer class="span12 division">
          <p><strong><a href="https://github.com/Olivine-Labs/busted">busted</a></strong> is bravely maintained by <a href="https://github.com/Olivine-Labs">Olivine Labs</a>.</p>
          <p><small><a href="https://raw.github.com/Olivine-Labs/busted/master/LICENSE">MIT Licensed</a>. &copy; 2013 Olivine Labs, LLC. Documentation hosted on GitHub Pages.</small></p>
        </footer>
      </div>
    <script src="js/jquery-1.9.1.min.js"></script>
    <script src="js/rainbow.min.js"></script>
    <script src="js/generic.js"></script>
    <script src="js/lua.js"></script>
    <script src="js/bootstrap.min.js"></script>
    <script>
      $(function(){
        $('.sidenav').affix({ offset: { top: 200, bottom: 100 } })
      var _gaq=[['_setAccount','UA-22050912-1'],['_trackPageview']]; 
      (function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];g.async=1;
      g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
      s.parentNode.insertBefore(g,s)}(document,'script'));
    </script>
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

index.html

Latest commit

History

index.html

File metadata and controls
