`test.result`

import test.result

test lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled test.result.* needs import test.result.

The shapes a test run is made of: the tree the declarations build, and what running it produced.

Every reporter is handed these objects and nothing else, so a custom reporter has the same view of a run that the built-in ones do. See test.reporter for what a reporter does with them.

Constants

`PENDING`

test.result.PENDING = 'pending'

A test was declared and not yet run.

`PASSED`

test.result.PASSED = 'passed'

It ran and every assertion held.

`FAILED`

test.result.FAILED = 'failed'

It ran and something did not hold.

`SKIPPED`

test.result.SKIPPED = 'skipped'

It was not run: skip, a filter, or another test’s only.

`TODO`

test.result.TODO = 'todo'

It was declared with no body, as a note to write it later.

`FLAKY`

test.result.FLAKY = 'flaky'

It failed, was retried, and then passed.

Classes

`Failure`

class test.Failure

One thing that went wrong.

A test can carry more than one: a failing body and then a failing after_each are two separate answers to “what went wrong”, and collapsing them loses the one that explains the other.

Fields

Field	Type	Description
`kind`		Where it came from: `'assertion'` for a matcher, `'error'` for anything else raised by the test body,…
`message`		The one-line summary.
`matcher`		The matcher that failed, for an assertion.
`expected`		What was expected, when that is a meaningful thing to show.
`received`		What was received.
`has_values`		Whether `expected` and `received` are worth printing.
`details`		Pre-rendered lines to print under the message.
`stacktrace`		The raw stack trace, innermost first.

Constructor

test.Failure(kind, message)

`Failure.origin()`

test.Failure.origin()

Where the failure happened, in the code under test.

Returns — source.Frame: nil when the trace holds nothing outside the test module.

`Case`

class test.Case

One declared test, and what became of it.

Fields

Field	Type	Description
`name`		The name given to `it()`.
`owner`		The suite it was declared in.
`file`		The file it was declared in.
`mode`		How it was declared: `'normal'`, `'skip'`, `'only'` or `'todo'`.
`body`		The body, or `nil` for a todo.
`options`		Its options, as given to `it()`.
`status`		What became of it: one of the status constants.
`failures`		Everything that went wrong.
`duration`		How long the last attempt took, in milliseconds.
`attempts`		How many times the body ran, counting retries.
`output`		What it printed, when output was being captured.
`skip_reason`		Why it was skipped, when something other than `skip` decided.

Constructor

test.Case(name, owner, file, mode, body, options)

`Case.depth()`

test.Case.depth()

How deeply nested the test is. @returns int

`Case.suite_path()`

test.Case.suite_path()

The enclosing suite names, outermost first. @returns list

`Case.full_name()`

test.Case.full_name() -> string

The test’s full name, suite path included.

Returns string

`Case.is_slow()`

test.Case.is_slow(threshold: number)

Whether it ran longer than threshold milliseconds. @param number threshold @returns bool

`Case.tags()`

test.Case.tags()

The tags it was declared with. @returns list

`Suite`

class test.Suite

A describe() block: its tests, its nested suites, and its hooks.

Fields

Field	Type	Description
`name`		The name given to `describe()`, or `''` for the implicit root.
`owner`		The enclosing suite, or `nil` for the root.
`file`		The file it was declared in.
`mode`		How it was declared: `'normal'`, `'skip'` or `'only'`.
`children`		Its tests and nested suites, in declaration order.
`before_all`		Hooks registered inside it.
`after_all`
`before_each`
`after_each`
`failures`		Anything that went wrong in a hook belonging to this suite.

Constructor

test.Suite(name, owner, file, mode)

`Suite.hooks_for()`

test.Suite.hooks_for(kind: string) -> list

The hooks of one kind registered on this suite, in the order they were registered.

Parameters

kind (string) — 'before_all', 'after_all', 'before_each' or 'after_each'.

Returns list

`Suite.depth()`

test.Suite.depth()

How deeply nested the suite is; the root is 0. @returns int

`Suite.path()`

test.Suite.path() -> list

This suite’s name preceded by its ancestors’, skipping the unnamed root.

Returns list

`Suite.cases()`

test.Suite.cases() -> list

Every test in this suite and everything under it, in declaration order.

Returns list

`Suite.suites()`

test.Suite.suites() -> list

Every suite under this one, itself included.

Returns list

`Summary`

class test.Summary

What a whole run came to.

Fields

Field	Type	Description
`suites`		Suites that contained at least one test that ran.
`passed`
`failed`
`skipped`
`todo`
`flaky`		Tests that passed only after a retry.
`failures`		Every test that failed, for the report at the end.
`slow`		Tests that ran slower than the slow threshold.
`duration`		Total wall time, in milliseconds.
`seed`		The seed the order was shuffled with, or `nil` when it was not.
`snapshots`		What happened to snapshots, from `test.snapshot`.
`bailed`		Whether the run stopped early because `bail` was reached.