stdlib.test

Test Framework (Contract-Aware)

Generated from v0.65.7. 4 source files, 94 documented symbols.

assert.xi

fn assert(cond: Bool, msg: Str)

Fail the test unless cond is true. Complexity: O(1).

• Postcondition: cond == true

fn assert_eq[T](a: T, b: T, msg: Str)

Fail unless a equals b. Complexity: O(1) for scalars; O(len) for content types.

• Postcondition: a == b

fn assert_ne[T](a: T, b: T, msg: Str)

Fail unless a differs from b. Complexity: O(1) for scalars; O(len) for content types.

• Postcondition: a != b

fn assert_lt[T](a: T, b: T, msg: Str)

Fail unless a is less than b. Complexity: O(1).

• Postcondition: a < b

fn assert_le[T](a: T, b: T, msg: Str)

Fail unless a is less than or equal to b. Complexity: O(1).

• Postcondition: a <= b

fn assert_gt[T](a: T, b: T, msg: Str)

Fail unless a is greater than b. Complexity: O(1).

• Postcondition: a > b

fn assert_ge[T](a: T, b: T, msg: Str)

Fail unless a is greater than or equal to b. Complexity: O(1).

• Postcondition: a >= b

fn assert_true(cond: Bool, msg: Str)

Fail unless cond is true. Complexity: O(1).

• Postcondition: cond == true

fn assert_false(cond: Bool, msg: Str)

Fail unless cond is false. Complexity: O(1).

• Postcondition: cond == false

fn assert_near(a: Float64, b: Float64, eps: Float64, msg: Str)

Fail unless a and b are within eps of each other. Complexity: O(1).

• Postcondition: a - b <= eps && b - a <= eps

fn assert_contains(haystack: Str, needle: Str, msg: Str)

Fail unless haystack contains needle. Complexity: O(len(haystack) * len(needle)).

• Postcondition: string.str_contains(haystack, needle)

fn assert_matches(s: Str, pattern: Str, msg: Str)

Fail unless s matches the regex pattern (search semantics, via xiom.regex.engine). Complexity: O(len(s) * len(pattern)) worst case.

• Postcondition: engine.regex_is_match(pattern, s)

fn assert_ok[T](r: Result[T, Str], msg: Str) -> T

Fail on Err and return the Ok value. Complexity: O(1).

• Postcondition: r.is_ok

fn assert_err[T](r: Result[T, Str], msg: Str)

Fail unless r is an Err. Complexity: O(1).

• Postcondition: !r.is_ok

fn assert_some[T](o: Option[T], msg: Str) -> T

Fail on None and return the value. Complexity: O(1).

• Postcondition: o.is_some

fn assert_none[T](o: Option[T], msg: Str)

Fail unless o is None. Complexity: O(1).

• Postcondition: !o.is_some

fn assert_panics(f: fn() -> Unit, msg: Str)

Fail unless calling f panics. Panics terminate the process in this build, so a panic cannot be observed: f is invoked and, if it returns normally, this assertion panics with msg. Complexity: O(cost of f).

• Precondition: true

fn assert_throws(f: fn() -> Unit, msg: Str)

Fail unless calling f raises an error. Same observable behaviour as assert_panics in this build (no unwind support). Complexity: O(cost of f).

• Precondition: true

fn assert_empty[T](v: &Vec[T], msg: Str)

Fail unless v has no elements. Complexity: O(1).

• Postcondition: v.len() == 0

fn assert_len[T](v: &Vec[T], n: Int, msg: Str)

Fail unless v has exactly n elements. Complexity: O(1).

• Postcondition: v.len() == n

---

---

---

assertions.xi

type Assertions

Non-aborting assertion collector. passed counts the checks that held; kinds/messages/expected/actual hold one record per failure, in call order.

Field	Type
passed	Int
kinds	Vec[Str]
messages	Vec[Str]
expected	Vec[Str]
actual	Vec[Str]

fn assertions_new() -> Assertions

Create an empty collector.

• Postcondition: result.passed == 0

fn check_eq_int(a: &mut Assertions, expected: Int, actual: Int, message: Str)

Pass when expected == actual; otherwise record an "eq_int" failure.

• Postcondition: a.passed >= 0

fn check_eq_str(a: &mut Assertions, expected: Str, actual: Str, message: Str)

Pass when expected == actual; otherwise record an "eq_str" failure.

• Postcondition: a.passed >= 0

fn check_eq_bool(a: &mut Assertions, expected: Bool, actual: Bool, message: Str)

Pass when expected == actual; otherwise record an "eq_bool" failure.

• Postcondition: a.passed >= 0

fn check_true(a: &mut Assertions, condition: Bool, message: Str)

Pass when the condition holds; otherwise record an "is_true" failure.

• Postcondition: a.passed >= 0

fn check_false(a: &mut Assertions, condition: Bool, message: Str)

Pass when the condition is false; otherwise record an "is_false" failure.

• Postcondition: a.passed >= 0

fn check_ge_int(a: &mut Assertions, actual: Int, floor: Int, message: Str)

Pass when actual >= floor; otherwise record a "ge_int" failure.

• Postcondition: a.passed >= 0

fn check_ok[T, E](a: &mut Assertions, r: Result[T, E], message: Str)

Pass when the Result is Ok; otherwise record an "is_ok" failure. The payloads are never inspected (payload-read free).

• Postcondition: a.passed >= 0

fn check_err[T, E](a: &mut Assertions, r: Result[T, E], message: Str)

Pass when the Result is Err; otherwise record an "is_err" failure.

• Postcondition: a.passed >= 0

fn check_some[T](a: &mut Assertions, o: Option[T], message: Str)

Pass when the Option is Some; otherwise record an "is_some" failure.

• Postcondition: a.passed >= 0

fn check_none[T](a: &mut Assertions, o: Option[T], message: Str)

Pass when the Option is None; otherwise record an "is_none" failure.

• Postcondition: a.passed >= 0

fn check_fail(a: &mut Assertions, message: Str)

Always record a failure with the given message ("fail" kind) -- for branches that should be unreachable in a conformance run.

• Postcondition: a.passed >= 0

fn assertions_passed(a: &Assertions) -> Int

Number of checks that held.

• Postcondition: result >= 0
• Postcondition: result == a.passed

fn assertions_failed(a: &Assertions) -> Int

Number of recorded failures (== record count).

• Postcondition: result >= 0
• Postcondition: result == a.kinds.len()

fn assertions_total(a: &Assertions) -> Int

Total number of checks run (passed + failed).

• Postcondition: result >= 0

fn assertions_has_failures(a: &Assertions) -> Bool

True when at least one failure was recorded.

• Postcondition: a.kinds.len() == 0 => result == false
• Postcondition: a.kinds.len() > 0 => result == true

fn assertion_kind(a: &Assertions, i: Int) -> Str

Kind of failure record i ("" when out of range).

• Postcondition: i < 0 || i >= a.kinds.len() => result == ""

fn assertion_message(a: &Assertions, i: Int) -> Str

Caller message of failure record i ("" when out of range).

• Postcondition: i < 0 || i >= a.kinds.len() => result == ""

fn assertion_expected(a: &Assertions, i: Int) -> Str

Expected rendering of failure record i ("" when out of range).

• Postcondition: i < 0 || i >= a.kinds.len() => result == ""

fn assertion_actual(a: &Assertions, i: Int) -> Str

Actual rendering of failure record i ("" when out of range).

• Postcondition: i < 0 || i >= a.kinds.len() => result == ""

fn assertions_summary(a: &Assertions) -> Str

One-line summary: "assertions: N passed, M failed".

• Postcondition: result.len() >= 12

fn assertions_report(a: &Assertions) -> Str

Multi-line report: the summary line, then one line per failure ("FAIL [kind] message -- expected: X, actual: Y").

• Postcondition: result.len() >= assertions_summary(a).len()
• Postcondition: (a.kinds.len() == 0) => (result == assertions_summary(a))

fn assertions_to_json(a: &Assertions) -> Str

Structured JSON document: {"passed":N,"failed":M,"failures":[{"kind":..,"message":.., "expected":..,"actual":..}, ...]}.

• Postcondition: result.len() >= 30

---

---

---

harness.xi

type Harness

A test runner holding registered tests by name.

Field	Type
names	Vec[Str]
tests	Vec[fn() -> Result[Unit, Str]]
skipped	Vec[Str]

type TestReport

The result of a run: passed, failed and skipped counts plus total run time.

Field	Type
passed	Int
failed	Int
skipped	Int
duration_ms	Int

Derives: Clone

type GlobalTests

Process-wide registered test names (fixed 8-slot registry; see header).

Field	Type
names	Vec[Str]
n	Int

fn test_harness_new() -> Harness

Create an empty test runner. Complexity: O(1).

• Postcondition: result.names.len() == 0 && result.tests.len() == 0 && result.skipped.len() == 0

fn harness_add_test(h: &mut Harness, name: Str, f: fn() -> Result[Unit, Str])

Register a named test. Complexity: O(1) amortized.

• Postcondition: h.names.len() == h.names.len()@pre + 1 && h.tests.len() == h.tests.len()@pre + 1

fn harness_run(h: &Harness) -> TestReport

Run all tests sequentially, respecting skipped names. Complexity: O(tests).

• Postcondition: result.passed + result.failed + result.skipped == h.tests.len()

fn harness_run_filtered(h: &Harness, filter: Str) -> TestReport

Run only tests whose name matches filter (substring, case-sensitive). Complexity: O(tests).

• Postcondition: result.passed + result.failed + result.skipped <= h.tests.len()

fn harness_parallel(h: &Harness, workers: Int) -> TestReport

Run tests with up to workers threads. This single-threaded build runs them sequentially (documented). Complexity: O(tests).

• Postcondition: result.passed + result.failed + result.skipped == h.tests.len()

fn harness_skip(h: &mut Harness, name: Str)

Mark a named test as skipped. Complexity: O(skipped).

• Postcondition: h.skipped.len() >= 1

fn harness_benchmark(h: &mut Harness, name: Str, f: fn() -> Unit, iterations: Int) -> Int

Time f over iterations calls and register the result under name. Returns the total elapsed time in milliseconds. Complexity: O(iterations * cost of f).

• Postcondition: h.names.len() == h.names.len()@pre + 1 && h.tests.len() == h.tests.len()@pre + 1

fn report_passed(r: &TestReport) -> Int

The number of passed tests. Complexity: O(1).

• Postcondition: result == r.passed

fn report_failed(r: &TestReport) -> Int

The number of failed tests. Complexity: O(1).

• Postcondition: result == r.failed

fn report_skipped(r: &TestReport) -> Int

The number of skipped tests. Complexity: O(1).

• Postcondition: result == r.skipped

fn report_duration_ms(r: &TestReport) -> Int

The total run time in milliseconds. Complexity: O(1).

• Postcondition: result == r.duration_ms

fn report_print(r: &TestReport)

Print a human-readable summary. Complexity: O(1).

• Precondition: true

fn report_json(r: &TestReport) -> Str

The report serialized as JSON. Complexity: O(1).

• Postcondition: result.len() >= 47

fn test_main() -> Int

Run all registered global tests and return the exit code. LIMITED: the registered tests cannot be executed in this build (module-scope function pointers are read-only after initialization), so this returns 0 when at least one test has been registered and 1 otherwise. Complexity: O(1).

• Postcondition: result == 0 || result == 1

fn test_register(name: Str, f: fn() -> Result[Unit, Str]) -> Bool

Register a test in the global harness. Returns true when the test was recorded, false when the 8-slot registry is full. LIMITED: only the test name is recorded -- the function pointer cannot be retained in this build (see header). Complexity: O(1).

• Precondition: true

---

---

---

test.xi

type TestResult

Test result with contract details

Field	Type
passed	Bool
name	Str
message	Str
contract_failures	Vec[ContractFailure]
duration_ms	Int

Derives: Clone

type ContractFailure

Recorded contract failure inside a test.

Field	Type
clause	Str
expression	Str
values	Str
location	Str

Derives: Clone

fn assert(condition: Bool, name: Str) -> TestResult

Pass when condition holds, else fail with name.

• Precondition: name.len() > 0

fn assert_eq[T](expected: T, actual: T, name: Str) -> TestResult

Pass when the values are equal, else fail with name.

• Precondition: name.len() > 0

fn assert_ne[T](expected: T, actual: T, name: Str) -> TestResult

Pass when the values differ.

• Postcondition: result.passed == (expected != actual)

fn assert_lt[T](left: T, right: T, name: Str) -> TestResult

Pass when left < right.

• Postcondition: result.passed == (left < right)

fn assert_gt[T](left: T, right: T, name: Str) -> TestResult

Pass when left > right.

• Postcondition: result.passed == (left > right)

fn assert_contains(haystack: Str, needle: Str, name: Str) -> TestResult

Pass when haystack contains needle.

• Postcondition: result.passed == string.str_contains(haystack, needle)

fn assert_ok[T, E](result: Result[T, E], name: Str) -> TestResult

Pass when the Result is Ok.

• Postcondition: result.name == name

fn assert_err[T, E](result: Result[T, E], name: Str) -> TestResult

Pass when the Result is Err.

• Postcondition: result.name == name

fn assert_some[T](option: Option[T], name: Str) -> TestResult

Pass when the Option is Some.

• Postcondition: result.passed == option.is_some

fn assert_none[T](option: Option[T], name: Str) -> TestResult

Pass when the Option is None.

• Postcondition: result.passed == (!option.is_some)

fn assert_contract[T](value: T, predicate: fn(&T) -> Bool, name: Str) -> TestResult

Pass when predicate holds for the value.

• Postcondition: result.passed == (result.contract_failures.len() == 0)

fn run(test: fn() -> TestResult) -> Int

Run one test and print the result; returns the exit code (0 = pass).

• Postcondition: result == 0 || result == 1

fn run_all(tests: Vec[fn() -> TestResult]) -> Int

Run every test and print a summary; returns the exit code.

• Postcondition: result >= 0 && result <= tests.len()

fn run_filtered(tests: Vec[fn() -> TestResult], filter: Str) -> Int

Run tests whose name contains filter; returns the exit code.

• Postcondition: result >= 0 && result <= tests.len()

fn format_results(results: Vec[TestResult]) -> Str

Human-readable summary of the results.

• Postcondition: result.len() >= 37

fn format_results_json(results: Vec[TestResult]) -> Str

JSON summary of the results.

• Postcondition: result.len() >= 2

fn bench(name: Str, f: fn() -> Unit) -> TestResult

Time f once and report it as a benchmark result.

• Postcondition: result.passed == true

fn assert_false(cond: Bool, name: Str) -> TestResult

Asserts that cond is false. Complexity: O(1). Pure in test context.

• Postcondition: result.passed == (!cond)

fn assert_eq_int(expected: Int, actual: Int, name: Str) -> TestResult

Asserts that two Int values are equal. Complexity: O(1). Pure in test context.

• Postcondition: result.passed == (expected == actual)

fn assert_ne_int(expected: Int, actual: Int, name: Str) -> TestResult

Asserts that two Int values are not equal. Complexity: O(1).

• Postcondition: result.passed == (expected != actual)

fn assert_gt_int(left: Int, right: Int, name: Str) -> TestResult

Asserts that left is strictly greater than right. Complexity: O(1).

• Postcondition: result.passed == (left > right)

fn assert_lt_int(left: Int, right: Int, name: Str) -> TestResult

Asserts that left is strictly less than right. Complexity: O(1).

• Postcondition: result.passed == (left < right)

fn assert_ge_int(left: Int, right: Int, name: Str) -> TestResult

Asserts that left is greater than or equal to right. Complexity: O(1).

• Postcondition: result.passed == (left >= right)

fn assert_le_int(left: Int, right: Int, name: Str) -> TestResult

Asserts that left is less than or equal to right. Complexity: O(1).

• Postcondition: result.passed == (left <= right)

fn assert_in_range(value: Int, lo: Int, hi: Int, name: Str) -> TestResult

Asserts that value is within the inclusive range [lo, hi]. Complexity: O(1).

• Postcondition: result.passed == (value >= lo && value <= hi)

fn test_count_failures(results: Vec[TestResult]) -> Int

Counts the number of failing test results in the vector. Complexity: O(n). Consumes the vector.

• Postcondition: result >= 0 && result <= results.len()

fn test_pass_count(results: Vec[TestResult]) -> Int

Counts the number of passing test results in the vector. Complexity: O(n). Consumes the vector.

• Postcondition: result >= 0 && result <= results.len()

fn test_fail_count(results: Vec[TestResult]) -> Int

Counts the number of failing test results. Alias for test_count_failures. Complexity: O(n). Consumes the vector.

• Postcondition: result >= 0 && result <= results.len()

fn test_summary(results: Vec[TestResult]) -> Str

Returns a one-line summary string: "P passed, F failed, T total". Complexity: O(n). Consumes the vector.

• Postcondition: result.len() >= 17

fn test_report(results: Vec[TestResult]) -> Str

Generates a multi-line test report using xiom.string.str_concat. Includes per-test results followed by a summary footer. Complexity: O(n). Consumes the vector.

• Postcondition: result.len() >= 34

---

---