test.runner

import test.runner

test does not re-export this module, so it is reached only by importing it directly.

Collecting the tests a file declares, deciding which of them to run, and running them.

Two phases, not one

describe() and it() do not run anything. They build a tree, and run() walks it afterwards. That separation is what makes only, filtering, shuffling, bailing and an up-front test count possible at all: none of them can be decided while the file is still being read.

Declaring the first test registers an os.at_exit() handler that calls run() once the file is done, so a test file needs no closing line. An explicit run() marks the tree as run and the handler then does nothing.

Hook ordering

before_all runs once, immediately before the first test in its suite that is actually going to run, and not at all for a suite whose tests were all filtered out. after_all runs after the last one, and only if before_all ran; it runs even when before_all failed, so whatever the setup acquired before failing is still let go. before_each runs outermost first, after_each innermost first, and after_each runs even when the test failed.

Timeouts

Zuri runs synchronously, so a test runs to completion and is then timed: the timeout option is measured after the body returns. It catches a test that got too slow, not one that hangs. A hang needs a process boundary, which is what the conductor puts around each file; see test.conduct.

Functions

root()

test.runner.root() -> Suite

The tree as it stands, for a caller that wants to look at what was declared without running it.

Returns Suite

reset()

test.runner.reset()

Throws away every declaration and every snapshot store, so a second run in the same process starts from nothing.

describe()

test.runner.describe(name: string, body: function, mode: ?string) -> Suite

Opens a suite, runs body to collect what is inside it, and closes it again.

Parameters

• name (string)
• body (function)
• mode (?string) — 'normal', 'skip' or 'only'.

Returns Suite

it()

test.runner.it(name: string, body: ?function, options: ?dict, mode: ?string) -> Case

Declares one test.

Parameters

• name (string)
• body (?function) — left out, the test is a todo.
• options (?dict) — retries, failing, timeout, tags.
• mode (?string) — 'normal', 'skip', 'only' or 'todo'.

Returns Case

before_all()

test.runner.before_all(body: function)

Parameters

• body (function)

after_all()

test.runner.after_all(body: function)

Parameters

• body (function)

before_each()

test.runner.before_each(body: function)

Parameters

• body (function)

after_each()

test.runner.after_each(body: function)

Parameters

• body (function)

run()

test.runner.run(options: ?dict) -> Summary

Runs everything declared so far and reports it.

import test { * }

describe('parser', @{
  it('reads an empty document', @{
    expect(parse('')).to_equal({})
  })
})

run()

Parameters

• options (?dict) — see {test} for every option and its default.

Returns Summary