vercel-labs--zerolang/docs/articles/modules/testing.md

When To Use std.testing

In Zerolang, use std.testing inside test blocks for output checks and small boolean assertion helpers.

Runnable today:

API	Return	Notes
std.testing.isTrue(value)	Bool	Passes through a Bool for readable expect statements.
std.testing.isFalse(value)	Bool	Returns true when the value is false.
std.testing.equalBool(actual, expected)	Bool	Compares booleans explicitly.
std.testing.equalUsize(actual, expected)	Bool	Compares usize values explicitly.
std.testing.equalU32(actual, expected)	Bool	Compares u32 values explicitly.
std.testing.equalI32(actual, expected)	Bool	Compares i32 values explicitly.
std.testing.equalBytes(actual, expected)	Bool	Compares byte spans by value.
std.testing.containsBytes(actual, needle)	Bool	Checks whether a byte span contains a byte substring.
std.testing.startsWith(actual, prefix)	Bool	Checks a byte prefix.
std.testing.endsWith(actual, suffix)	Bool	Checks a byte suffix.
std.testing.notEqualBytes(actual, expected)	Bool	Checks byte-span inequality.
std.testing.diffIndexBytes(actual, expected)	Maybe<usize>	Returns the first differing byte index, or null when spans are equal.
std.testing.jsonFieldEquals(actual, key, expected)	Bool	Compares a raw top-level JSON field value.
std.testing.jsonPathEquals(actual, path, expected)	Bool	Compares a raw dotted JSON path value.
std.testing.caseName(buffer, suite, index)	Maybe<Span<u8>>	Writes a stable table-case name like suite[3] into caller storage.

Metadata labels:

• effects: none for scalar comparisons; memory for byte-span/case-name checks; parse for JSON checks
• allocation behavior: no allocation
• target support: target-neutral
• error behavior: infallible
• ownership notes: no ownership transfer
• example: examples/std-testing-log.graph

Example

test "testing helpers support direct test blocks" {
    let diff: Maybe<usize> = std.testing.diffIndexBytes("zero", "zeta")
    expect std.testing.equalU32(42_u32, 42_u32)
    expect std.testing.equalBytes("zero", "zero")
    expect std.testing.containsBytes("zerolang", "lang")
    expect diff.has && diff.value == 2
    expect std.testing.jsonPathEquals("{\"user\":{\"name\":\"zero\"}}", "user.name", "\"zero\"")
}

Design Notes

std.testing helpers return Bool; they do not register tests, hide failures, allocate output, or produce process I/O. Use them inside ordinary expect statements so the compiler and zero test keep one visible test model.

The byte helpers are byte-span predicates. They are suitable for output checks, protocol fixtures, and small examples where a full parser would be more complex than the assertion.

JSON helpers compare raw JSON values, so string expectations include their JSON quotes, such as "\"zero\"".