std.test

Test programs iterate supplied values with the ordinary for statement. The same statement applies to integers, booleans, strings, and other iterable element types.

std.test does not export forAllInt or forAllBool. Assertions inside a for body retain the same assertion behavior as a direct call.

assertNe(actual, expected) returns unit when ordinary value equality says the operands differ. It performs no string conversion before comparison.

The operands must have a common comparable type under the ordinary equality rules. Known noncomparable values produce TPZ5007 during checking. A comparison fault propagates with its own diagnostic.

assertContains(text, needle) returns unit when the exact needle occurs as a contiguous substring. Matching is case sensitive and preserves Unicode spelling. An empty needle succeeds even when the text is empty.

Arguments are evaluated once from left to right before testing the condition. Successful calls have no further side effects and print nothing.

A false assertion raises TPZ4007 at the assertion call. It returns no value and stops the current test before the next statement. Earlier argument side effects remain visible. Test runner handling of later test cases follows the test execution contract.

The inequality failure message uses the ordinary rendering of the shared value in this form.

```text assertNe failed: both values are {value} ```

The containment failure message includes the original text and needle in this form.

```text assertContains failed: {text} does not contain {needle} ```

These assertions add test failure reporting to ordinary equality and string containment. They do not define a separate comparison relation.

assertOk accepts a Result<T, E>. It returns the T payload of Ok(value). An Err(error) raises TPZ4007.

assertErr accepts a Result<T, E>. It returns the E payload of Err(error). An Ok(value) raises TPZ4007.

The returned payload is unchanged. No conversion, recursive unwrapping, or equality comparison occurs. A nested Err inside an outer Ok still satisfies assertOk.

The argument is evaluated once before its outer constructor is inspected. Success prints nothing. Failure reports the assertion call and stops the current test without running its next statement. Earlier effects remain visible.

The failure messages identify the unexpected constructor and its ordinarily rendered payload.

```text assertOk failed: got Err({error}) assertErr failed: got Ok({value}) ```

These helpers express a test expectation. Match the Result in ordinary code when either constructor is part of normal control flow.

assertSome accepts an Option<T> and returns the T payload of Some(value). Passing None() raises TPZ4007.

assertNone accepts an Option<T> and returns unit for None(). Passing Some(value) raises TPZ4007.

Presence depends on the outer constructor. Some(None()), Some(false), and Some(0) are present values. assertSome returns their payloads unchanged.

Each argument is evaluated once. A successful assertion prints nothing and performs no additional effects. Failure reports the assertion call and stops the current test before its next statement.

The failure messages identify the unexpected constructor. A present payload uses ordinary value rendering.

```text assertSome failed: got None assertNone failed: got Some({value}) ```

Use a match to handle absence as normal program behavior. These assertions report a failed test when the chosen presence expectation is false.

assertGolden(path, actual) accepts two strings. Read the existing file as UTF-8 and compare the entire decoded text with actual. UTF-8 validity and text preservation follow UTF-8 decoding. Equal text returns unit without printing.

Resolve the path using the same host path and read permission rules as filesystem text reads. For an ordinary installed CLI program, a relative path starts at the process working directory. The source file directory does not replace that directory.

Comparison preserves every scalar and line ending. CRLF and LF differ. A final newline, a byte order mark, Unicode spelling, and an empty file remain significant. Invalid UTF-8 is a read failure.

Evaluate the path expression and then the actual expression, once each, before reading the file. Open and read the expected text once. Release any opened resource before returning or reporting a read or comparison failure.

The assertion needs read access. It never creates a missing golden file, replaces its contents, or enables an update mode. Write a chosen expected result explicitly through the filesystem API.

Missing files, directories that cannot be read as text, permission denial, and invalid UTF-8 raise TPZ4007 at the assertion call. File failures identify the path and whether opening or reading failed. The host detail explains the cause and may vary by platform.

The file failure messages have these forms.

```text assertGolden failed: could not open {path}: {detail} assertGolden failed: could not read {path}: {detail} ```

Unequal text raises TPZ4007 and stops the current test before its next statement. The message has this form.

```text assertGolden failed: {path} did not match actual output ```

Earlier argument effects remain visible after failure. Reading does not promise a snapshot across concurrent host writes. Keep the expected file unchanged while the assertion reads it.