test.context

import test.context

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

What is true right now, while one particular test is running.

The assertion side and the runner side both need this, and neither should have to import the other, so it lives on its own. Nothing in here is interesting to a test author; the API a test uses is test.assertions() and test.has_assertions(), both of which are thin wrappers over what is below.

The state is a single module-level value because a Zuri program has one call stack and runs one test at a time. There is nothing to key it by.

Functions

begin()

test.context.begin(name: string, suite_path: list, file: string) -> Frame

Opens a frame for a test about to run. Called by the runner, once per attempt.

Parameters

• name (string)
• suite_path (list)
• file (string)

Returns Frame

end()

test.context.end()

Closes the current frame and returns it, so the runner can read the final assertion count off it.

Returns — Frame: nil when no test was open.

current()

test.context.current() -> Frame

The frame for the test currently running, or nil outside one.

Returns Frame

active()

test.context.active() -> bool

Whether a test is running right now.

Matchers use this to tell a real assertion failure, which the runner will catch and report, from one raised in a suite body or at the top level of a file, where there is nothing to attribute it to.

Returns bool

record_assertion()

test.context.record_assertion()

Counts one matcher against the current test. Every matcher calls this, whether it passes or fails.

assertion_count()

test.context.assertion_count()

How many matchers have run in the current test.

Returns — int: 0 outside a test.

expect_assertions()

test.context.expect_assertions(count: int)

Declares that the current test makes exactly count assertions.

Parameters

• count (int)

Raises TestSetupError outside a test, where there is nothing to hold to the promise.

expect_some_assertions()

test.context.expect_some_assertions()

Declares that the current test makes at least one assertion.

Raises TestSetupError outside a test.

check()

test.context.check(frame)

Checks a finished test’s assertion promises against what it actually did.

Parameters

• frame (Frame)

Returns — string: what went wrong, or nil when nothing did.

snapshot_key()

test.context.snapshot_key(name: ?string) -> string

Claims the next snapshot key for the current test.

A named snapshot keeps its name. An unnamed one is numbered in the order it was taken, so reordering the snapshots inside one test is a change the snapshot file will notice.

Parameters

• name (?string)

Returns string

Raises TestSetupError outside a test.

Classes

Frame

class test.context.Frame

The test the runner currently has open, as far as anything outside the runner needs to know about it.

Fields

Constructor

test.context.Frame(name, suite_path, file)

Frame.full_name()

test.context.Frame.full_name() -> string

The test’s full name, suite path included, as it appears in a report and in a snapshot file.

Returns string