Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-test FR-001
Tests that run unchanged under bun test and node --test (commons 0001-testFR-001): registration on node:test, assertions on node:assert/strict, with short plain names (assert, assertEquals, assertStringIncludes, ...). proves names the requirements a test proves, as erga's kernel test.ts does, and keeps them for a report. Kept out of ./mod.ts, so that importing the runtime never loads a test runner.
Every test registered here is recorded by this module's own code, not by a runner's reporter (commons 0008-test-evidenceFR-001 to FR-004): its id (the SHA-256 of its file and name), file, name, requirements, risk (the option risk, not-high by default), start and end, outcome (pass, fail, skip, todo or cancelled), a skip's or todo's reason, a failure's message, expected and actual values (redacted and cut to 4096 characters) and attempt (IFC_TEST_ATTEMPT, 1 by default), as a test span and a log record whose parent is the run's span from TRACEPARENT, on a resource that is the installation record. Where IFC_TEST_RECORD names a file, each test's records are appended to it as OTLP JSON lines as it starts and as it ends, and a test that has not ended when the process exits is appended as cancelled; otherwise they are kept in memory (recorded) and given to each listener (onTestRecord). The file of a test is the file that called test or proves, from the call's stack, relative to the working folder, or the option file. A test's outcome is never changed by its recording: a failure is still thrown to the runner.
A test's body is given a context t whose t.step(name, fn) runs a step as a subtest of node:test (TestContext.test), awaited, and records it in the test's evidence (commons 0001-testFR-002): a test step span, a child of the test's span (or of the step it is in), as it ends, and the test's steps, which its test span names in ifc.test.steps. A step that fails fails its test with the step's error, on every runner, so that the test's record says why.
only runs a test alone among the tests of its file (FR-060). Each runner is given node:test's only, and this module also skips the other tests of the file itself, so that "the one marked only runs alone" holds on each runner, and each of the others is recorded as skip with the reason ONLY_REASON:
node --test --test-only runs only the tests marked only, of itself;
node --test without --test-only (Node 26 then says "'only' and 'runOnly' require the --test-only command-line option") and bun test (Bun's node:test ignores only) run every test: the others then skip themselves, and a runner shows them as passed (Bun) or skipped (Node);
bun test --only runs no test of node:test at all, only or not, as its node:test never marks one: give bun test no --only. The others of the file are those registered before the first test marked only that have not started, and every one registered after it; bun test loads every file in one process, so the mark is kept for each file, never for the process.
What a test's body, or a step's, is given (FR-060): its name; step, which runs a step as a subtest of node:test, awaited, and records it in the test's evidence (a step that fails rejects with its error, so that the test fails with it); and skip, which marks the test or the step skipped, with the reason, when its body returns (the body itself returns: skip does not stop it).
How long a test may run when it names no timeout: five minutes. Bun's own default of 5 seconds ends a test that starts real programs on a slow runner (Windows above all) for the wrong reason; five minutes is above any limit a consumer's runner sets (its own tools pass up to a few minutes), so it never shortens one, and a test that hangs still ends.
typeTestOptions= {
readonlyskip?:boolean|string;
readonlytodo?:boolean|string;
readonlyonly?:boolean;
readonlytimeout?:number;
readonlyrisk?:Risk;
/** The quality characteristic the test proves, in the words of ISO/IEC 25010, recorded as `ifc.test.characteristic` (0021-ifqs FR-012). */readonlycharacteristic?:string;
readonlyfile?:string;
};
How to run a test: skip it or mark it todo (with the reason as a string; neither runs its body), run it alone among the tests of its file (only), give it a timeout in milliseconds (a test that does not end by then is cancelled), its risk (not-high by default), or the file it is recorded under.
A listener given each test as it ends, beside recorded and IFC_TEST_RECORD: where an OpenTelemetry pipeline is installed, it hands testCaseSpan and testCaseLog of the event to its processors (0008-test-evidenceFR-004). Returns the function that removes it.
The value, narrowed to NonNullable, or a failure as assertExists fails where it is null or undefined (FR-065), so that a test reads the(map.get(key)).name where an assertion would need a statement of its own.
Fails unless the two numbers are within tolerance of each other (1e-7 by default), as @std/assert's assertAlmostEquals (FR-060): the same value (Object.is, so NaN is close to NaN and an infinity to itself) passes, else |expected - actual| must not exceed the tolerance.