IF Commons GitHub

test

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-test FR-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-evidence FR-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-test FR-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.
import { assertEquals, proves } from "./test.ts";
proves(["0001-test FR-001"], "one and one", () => assertEquals(1 + 1, 2));
proves(["0008-test-evidence FR-001"], "a high-risk test", () => assertEquals(2 * 2, 4), { risk: "high" });

Source: commons/test/src/test.ts

24 of 31 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

StepContexttypeno test imports it
type StepContext = {
  readonly name: string;
  readonly step: (name: string, fn: StepFn) => Promise<void>;
  readonly skip: (reason?: string) => void;
};

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).

StepFntypeno test imports it
type StepFn = (t: StepContext) => void | Promise<void>;

A step's body, given its own context for the steps within it.

TestFntypeno test imports it
type TestFn = (t: StepContext) => void | Promise<void>;

A test's body; it may take the context t for its steps.

DEFAULT_TIMEOUT_MSconstno test imports it
const DEFAULT_TIMEOUT_MS: 300000

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.

TestOptionstypeno test imports it
type TestOptions = {
  readonly skip?: boolean | string;
  readonly todo?: boolean | string;
  readonly only?: boolean;
  readonly timeout?: number;
  readonly risk?: Risk;
  /** The quality characteristic the test proves, in the words of ISO/IEC 25010, recorded as `ifc.test.characteristic` (0021-ifqs FR-012). */
  readonly characteristic?: string;
  readonly file?: 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.

ONLY_REASONconst
const ONLY_REASON: "another test of this file is marked only"

The reason a test is recorded as skipped where another test of its file is marked only (FR-060).

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

Requirementtypeno test imports it
type Requirement = string;

A requirement cited by its specification and number: 0001-test FR-001, or another repository's erga 241-typescript-first FR-015.

proofsconst
const proofs: { readonly test: string; readonly requirements: readonly string[]; }[]

The requirements each test proves, in the order the tests were registered, for a report.

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

reviewsconst
const reviews: { readonly requirement: string; readonly reason: string; }[]

The requirements declared as proven by review rather than a test, with the reason.

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

recordedconst
const recorded: TestCase[]

Every test of this process as it was recorded, in the order they ended (skipped and todo tests as they were registered) (FR-004).

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

TestRecordEventtypeno test imports it
type TestRecordEvent = { readonly test: TestCase; readonly resource: Resource; readonly context: TestContext };

What a listener is given for each test that ends: the case, and the resource and context its signals carry.

onTestRecordfunction
function onTestRecord(listener: (e: TestRecordEvent) => void): () => void

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-evidence FR-004). Returns the function that removes it.

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

testfunction
function test(name: string, fn: TestFn, options?: TestOptions): void

A test registered with the runtime's runner, and recorded (0008-test-evidence FR-001).

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

provesfunction
function proves(requirements: readonly [string, ...string[]], name: string, fn: TestFn, options?: TestOptions): void

A test that proves one or more requirements, named for them: 0001-test FR-001: <name>.

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

reviewedfunction
function reviewed(requirement: string, reason: string): void

A requirement proven by review rather than by a test, with the reason; recorded as an ifc.test.review log record (0008-test-evidence FR-006).

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

assertfunction
function assert(value: unknown, message?: string | undefined): asserts value

Fails unless value is truthy; narrows its type.

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

assertEqualsfunction
function assertEquals<T>(actual: T, expected: T, message?: string | undefined): void

Fails unless the two are deeply and strictly equal (the same types, prototypes and values).

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

assertNotEqualsfunction
function assertNotEquals<T>(actual: T, expected: T, message?: string | undefined): void

Fails where the two are deeply and strictly equal.

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

assertStrictEqualsfunction
function assertStrictEquals<T>(actual: T, expected: T, message?: string | undefined): void

Fails unless the two are the same value (Object.is).

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

assertExistsfunction
function assertExists<T>(value: T, message?: string | undefined): asserts value is NonNullable<T>

Fails unless the value is neither null nor undefined; narrows its type.

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

thefunction
function the<T>(value: T, message?: string | undefined): NonNullable<T>

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.

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

assertInstanceOffunction
function assertInstanceOf<T>(value: unknown, Class: abstract new (...args: never[]) => T, message?: string | undefined): asserts value is T

Fails unless the value is an instance of the class; narrows its type.

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

assertStringIncludesfunction
function assertStringIncludes(actual: string, expected: string, message?: string | undefined): void

Fails unless the text includes the part.

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

assertNotStrictEqualsfunction
function assertNotStrictEquals<T>(actual: T, expected: T, message?: string | undefined): void

Fails unless the two are different values (Object.is), as @std/assert's assertNotStrictEquals (FR-060).

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

assertAlmostEqualsfunction
function assertAlmostEquals(actual: number, expected: number, tolerance?: number, message?: string | undefined): void

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.

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

assertNotMatchfunction
function assertNotMatch(actual: string, pattern: RegExp, message?: string | undefined): void

Fails where the text matches the pattern, as @std/assert's assertNotMatch (FR-060).

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

assertMatchfunction
function assertMatch(actual: string, pattern: RegExp, message?: string | undefined): void

Fails unless the text matches the pattern.

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

assertArrayIncludesfunction
function assertArrayIncludes<T>(actual: readonly T[], expected: readonly T[], message?: string | undefined): void

Fails unless every expected element is deeply equal to some element of the array.

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

assertThrowsfunction
function assertThrows<E extends Error = Error>(fn: () => unknown, Class?: (abstract new (...args: never[]) => E) | undefined, includes?: string | undefined): E

The error a function throws; fails where it throws none, or one not of Class, or one whose message does not include includes.

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

assertRejectsfunction
function assertRejects<E extends Error = Error>(fn: () => PromiseLike<unknown>, Class?: (abstract new (...args: never[]) => E) | undefined, includes?: string | undefined): Promise<E>

The error a promise rejects with; fails where it fulfils, or rejects with one not of Class, or whose message does not include includes.

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

failfunction
function fail(message: string): never

Fails, with the message.

Imported by 15 tests of the run (12 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.