test
Authoring primitives for unit-test-style programs written in CX: assertions, fixtures, lifecycle hooks, and structured reporting. This is the vocabulary you use when writing your own test programs, and is distinct from the conformance harness used to verify the spec. Failing assertions raise an error by default, or accumulate for end-of-run reporting under [$test:configure].
test:assert
[$test:assert] -> null — Fail the test if the predicate is false; an optional label appears in the failure message.
[?lib 'cx-stdlib/test']
[$test:assert true]
null
test:assert-equal
[$test:assert-equal] -> null — Fail unless the two values are structurally equal (exact equality, including floats).
[?lib 'cx-stdlib/test']
[$test:assert-equal 42 42]
null
test:assert-not-equal
[$test:assert-not-equal] -> null — Fail if the two values are structurally equal.
[?lib 'cx-stdlib/test']
[$test:assert-not-equal 1 2]
null
test:assert-shape
[$test:assert-shape] -> null — Fail unless the value conforms to the given schema, via cx-stdlib/validate.
[?lib 'cx-stdlib/test']
[$test:assert-shape [user [id 1] [name "Alice"]] [schema [field name="id" type="int" required=true] [field name="name" type="string" required=true]]]
null
test:assert-throws
[$test:assert-throws] -> null — Fail unless invoking the thunk raises an error with the expected code.
[?lib 'cx-stdlib/test']
[$test:assert-throws [?fn () [$test:fail "boom"]] "CXER2200"]
null
test:assert-near
[$test:assert-near] -> null — Fail if the actual and expected floats differ by more than epsilon.
[?lib 'cx-stdlib/test']
[$test:assert-near 1.0001 1.0 0.001]
null
test:assert-contains
[$test:assert-contains] -> null — Fail unless the haystack contains the needle — substring, element membership, or map key.
[?lib 'cx-stdlib/test']
[$test:assert-contains "hello world" "world"]
null
test:assert-match
[$test:assert-match] -> null — Fail unless the value matches the given CX pattern.
[?lib 'cx-stdlib/test']
[$test:assert-match [user id=1] [user id=1]]
null
test:assert-snapshot
[$test:assert-snapshot] -> null — Compare the value against a recorded snapshot, raising on divergence outside update mode.
[?lib 'cx-stdlib/test']
[?let [= $recorded [$test:assert-snapshot [user id=1] snapshot-key="user-shape"]] [$test:assert-snapshot [user id=2] snapshot-key="user-shape"]]
cx-err:CXER2203
test:fail
[$test:fail] -> null — Unconditionally fail the current test with a message.
[?lib 'cx-stdlib/test']
[$test:assert-throws [?fn () [$test:fail "boom"]] "CXER2200"]
null
test:skip
[$test:skip] -> null — Mark the current test skipped with a reason, reported separately from pass and fail.
[?lib 'cx-stdlib/test']
[$test:skip "not on windows"]
cx-err:CXER2202
test:fixture
[$test:fixture] -> element — Collect the body elements into a named sequence value for use as a test fixture.
[?lib 'cx-stdlib/test']
[$count [$test:fixture "alice" [user id=1 email="alice@example.com" name="Alice"]]]
1
test:fixture-load
[$test:fixture-load] -> any — Load a fixture from a path resolved against the fixture directory or test-program location.
[?lib 'cx-stdlib/test']
[$test:fixture-load "fixtures/alice.cx"]
cx-err:CXER0271
test:before-each
[$test:before-each] -> null — Register a thunk to run before each test (or each parameterized case).
[?lib 'cx-stdlib/test']
[$test:before-each [?fn () true]]
null
test:after-each
[$test:after-each] -> null — Register a thunk to run after each test (or each parameterized case).
[?lib 'cx-stdlib/test']
[$test:after-each [?fn () true]]
null
test:before-all
[$test:before-all] -> null — Register a thunk to run once before any test in the module.
[?lib 'cx-stdlib/test']
[$test:before-all [?fn () true]]
null
test:after-all
[$test:after-all] -> null — Register a thunk to run once after all tests in the module.
[?lib 'cx-stdlib/test']
[$test:after-all [?fn () true]]
null
test:configure
[$test:configure] -> null — Set runner options — failure mode, reporter, and fixture or snapshot directories.
[?lib 'cx-stdlib/test']
[$test:configure [map on-fail="collect"]]
null