test

Utilities for writing and running test suites.

Types

Type	Description
Assert	Raised when an assertion fails.
Ignore	Exception thrown to omit a test case from the report.
Skip	Exception thrown to skip a test case.
TestInfo	Read-only metadata for a discovered test.
Tagged[T]	A parametrize value carrying tags, made by tagged.

Tagged[T]

A parametrize value carrying tags, made by tagged.

Functions

assert cond …

Asserts that cond is truthy.

Parameters

Name	Type	Description
cond		Condition to test.
msg?	Str	Message to add to the failure.

Errors

Assert if the assertion fails.

assert_eq left right …

Asserts that left == right.

Parameters

Name	Type	Description
left		Actual value.
right		Expected value.
msg?	Str	Message to add to the failure.

Errors

Assert if the assertion fails.

assert_ne left right …

Asserts that left != right.

Parameters

Name	Type	Description
left		Actual value.
right		Value it must differ from.
msg?	Str	Message to add to the failure.

Errors

Assert if the assertion fails.

assert_not cond …

Asserts that cond is falsy.

Parameters

Name	Type	Description
cond		Condition to test.
msg?	Str	Message to add to the failure.

Errors

Assert if the assertion fails.

assert_throws[E] type block … -> E

Asserts that block raises an error of type, and returns the error.

Parameters

Name	Type	Description
type	Type[E]	Error type expected, or a supertype of it.
:str?	Str	Expected string form of the error.
:msg?	Str	Message to add to the failure.
block	(() -> Value)	Block to run.

Errors

Assert if the assertion fails.

assert_type[T] expected value …

Asserts that value is an instance of expected or a subtype of it.

Parameters

Name	Type	Description
expected	Type[T]	Expected type.
value		Value to test.
msg?	Str	Message to add to the failure.

Errors

Assert if the assertion fails.

fixture wrap -> ((Value) -> Value)

Defines a test fixture. wrap should be a function which accepts a block and invokes it with surrounding setup and teardown logic. wrap receives any trailing keyword parameters supplied by parametrize (or by an outer fixture) after block and should forward them to block — typically via a variadic ...rest parameter — so they reach the test function. wrap may also pass its own additional keyword parameters to block to inject values into the test.

Example

#[fixture]
def example_fixture block ...rest
  setup()
  try
    block(...rest)
  finally
    teardown()

#[test]
#[example_fixture]
def example_test()
  do_something()

ignore …

Omits the current test from the report by raising Ignore.

Parameters

Name	Type	Description
msg?	Str	Reason to record.

parametrize ...axes -> ((Value) -> Value)

Registers one or more parametrize axes on a test. Each keyword argument names an axis under which its value is passed to the decorated test function (and to any fixture that declares it). Stacks with other parametrize decorators, and composes freely with #[fixture] decorators; the cartesian product is taken over every axis registered by any application.

Because decorators apply bottom-to-top, axes accumulate in closest-to-def-first order (axes from one decorator are ordered as written); this only affects generated case names ($base_name/$axis1=$v/$axis2=$v/...), not correctness.

Parameters

Name	Type	Description
...axes	Iterable[Value]	An axis name paired with an iterable of raw values and/or tagged(value, ...tags) wrappers for that axis.

Example

#[test]
#[parametrize backend: [sqlite_conn, tagged(postgres_conn, "slow")]]
def connects :backend
  backend.ping()

parametrize func ...axes

Registers parametrize axes on a test function directly, returning the decorated test for test.

Parameters

Name	Type	Description
func		Test function, or a test already decorated with parametrize or a fixture.
...axes	Iterable[Value]	An axis name paired with an iterable of raw values and/or tagged(value, ...tags) wrappers for that axis.

run *paths … -> Int

Discovers and runs tests under the trailing file and directory paths.

The bundled dolang -m test command retains --filter glob matching against module/name. Its repeatable --tags option splits each occurrence on commas: alternatives in one occurrence are ORed, while occurrences are ANDed. Prefix a tag with ! to require its absence. Matching is exact and case-sensitive.

--tags !windows,!macos means “not Windows OR not macOS.” Use --tags !windows --tags !macos to exclude both.

Parameters

Name	Type	Description
:jobs?	Int	Maximum concurrent tests.
:module_jobs?	Int	Maximum concurrent modules.
:filter?	((TestInfo) -> Bool)	Predicate receiving a TestInfo. Defaults to accepting every test.
:timeout?	Int	Per-test and module-load timeout in seconds.
:capture?	Bool	Capture output and show it for failures.
*paths	(Str | fs.Path)	Test file or directory.

Returns

Returns zero when all selected tests pass, or one when any module or test fails.

skip …

Skips the current test by raising Skip.

Parameters

Name	Type	Description
msg?	Str	Reason to report.

tagged[T] value *values -> Tagged[T]

Attaches tags to a single parametrize value, honored only in cases that select it.

Parameters

Name	Type	Description
value	T	The parametrize value.
*values	Str	Tags to attach.

Example

#[parametrize backend: [sqlite_conn, tagged(postgres_conn, "slow")]]

tags *values

Adds tags to tests subsequently registered in the current module.

Repeated calls accumulate tags. Module tags precede tags supplied directly to test; order and duplicates are preserved.

Parameters

Name	Type	Description
*values	Str	Tag to add.

Example

tags "integration" "linux"

#[test tags: ["slow"]]
def connects()
  connect()

test … -> ((Value) -> Value)

Returns a decorator that registers a zero-argument test function.

Parameters

Name	Type	Description
:name?	Str	Reporting name. Defaults to the test function's string form.
:tags?	Iterable[Str]	Tags to attach. Order and duplicates are preserved.

Example

#[test name: "connects" tags: ["integration", "linux"]]
def connects_to_service()
  connect()

test[F] func … -> F

Registers a zero-argument test function, returning it.

Parameters

Name	Type	Description
:name?	Str	Reporting name. Defaults to str(func).
:tags?	Iterable[Str]	Tags to attach. Order and duplicates are preserved.
func	F	Test function, or a test decorated with parametrize or a fixture.