@intellectual-frontiers/test 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/test.ts ADDED
@@ -0,0 +1,713 @@
1
+ // Spec: 0001-test FR-001
2
+ /**
3
+ * Tests that run unchanged under `bun test` and `node --test` (commons 0005-typescript-runtime FR-013): registration on
4
+ * `node:test`, assertions on `node:assert/strict`, with short plain names (`assert`, `assertEquals`, `assertStringIncludes`, ...). `proves` names the
5
+ * 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
6
+ * runtime never loads a test runner.
7
+ *
8
+ * 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
9
+ * 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
10
+ * end, outcome (`pass`, `fail`, `skip`, `todo` or `cancelled`), a skip's or todo's reason, a failure's message, expected and actual values
11
+ * (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
12
+ * the run's span from `TRACEPARENT`, on a resource that is the installation record. Where `IFC_TEST_RECORD` names a file, each test's
13
+ * 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
14
+ * appended as `cancelled`; otherwise they are kept in memory (`recorded`) and given to each listener (`onTestRecord`). The file of a test
15
+ * 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
16
+ * outcome is never changed by its recording: a failure is still thrown to the runner.
17
+ *
18
+ * 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
19
+ * records it in the test's evidence (commons 0005-typescript-runtime FR-060): a `test step` span, a child of the test's span (or of the
20
+ * 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
21
+ * with the step's error, on every runner, so that the test's record says why.
22
+ *
23
+ * `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
24
+ * 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
25
+ * as `skip` with the reason `ONLY_REASON`:
26
+ * - `node --test --test-only` runs only the tests marked `only`, of itself;
27
+ * - `node --test` without `--test-only` (Node 26 then says "'only' and 'runOnly' require the --test-only command-line option") and
28
+ * `bun test` (Bun's `node:test` ignores `only`) run every test: the others then skip themselves, and a runner shows them as passed
29
+ * (Bun) or skipped (Node);
30
+ * - `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`.
31
+ * The others of the file are those registered before the first test marked `only` that have not started, and every one registered after
32
+ * it; `bun test` loads every file in one process, so the mark is kept for each file, never for the process.
33
+ *
34
+ * @example
35
+ * ```ts
36
+ * import { assertEquals, proves } from "./test.ts";
37
+ * proves(["0005-typescript-runtime FR-013"], "one and one", () => assertEquals(1 + 1, 2));
38
+ * proves(["0008-test-evidence FR-001"], "a high-risk test", () => assertEquals(2 * 2, 4), { risk: "high" });
39
+ * ```
40
+ *
41
+ * @module
42
+ */
43
+ import nodeAssert from "node:assert/strict";
44
+ import { createHash } from "node:crypto";
45
+ import { appendFileSync, realpathSync } from "node:fs";
46
+ import { isAbsolute, relative, resolve } from "node:path";
47
+ import process from "node:process";
48
+ import { test as nodeTest, type TestContext as NodeTestContext } from "node:test";
49
+ import { fileURLToPath } from "node:url";
50
+ import { inspect } from "node:util";
51
+ import {
52
+ extractContext,
53
+ redactText,
54
+ type Resource,
55
+ type SpanId,
56
+ spanIdFrom,
57
+ type TraceId,
58
+ traceIdFrom,
59
+ } from "@intellectual-frontiers/telemetry/otel";
60
+ import {
61
+ cut,
62
+ installationFromEnv,
63
+ installationResource,
64
+ recordLine,
65
+ recordPath,
66
+ type Review,
67
+ type Risk,
68
+ type StepOutcome,
69
+ type TestCase,
70
+ type TestContext,
71
+ type TestStep,
72
+ testStepSpan,
73
+ TEST_SCOPE,
74
+ testCaseLog,
75
+ testCaseSpan,
76
+ testStartLog,
77
+ reviewLog,
78
+ warningLog,
79
+ } from "./record.ts";
80
+ import { installed } from "@intellectual-frontiers/telemetry/host/otel";
81
+ import { build, runtimeName, runtimeVersion } from "@intellectual-frontiers/system/proc";
82
+
83
+ /**
84
+ * 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
85
+ * 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
86
+ * the test or the step skipped, with the reason, when its body returns (the body itself returns: `skip` does not stop it).
87
+ */
88
+ export type StepContext = {
89
+ readonly name: string;
90
+ readonly step: (name: string, fn: StepFn) => Promise<void>;
91
+ readonly skip: (reason?: string) => void;
92
+ };
93
+
94
+ /** A step's body, given its own context for the steps within it. */
95
+ export type StepFn = (t: StepContext) => void | Promise<void>;
96
+
97
+ /** A test's body; it may take the context `t` for its steps. */
98
+ export type TestFn = (t: StepContext) => void | Promise<void>;
99
+
100
+ /**
101
+ * 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
102
+ * 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.
103
+ */
104
+ export const DEFAULT_TIMEOUT_MS = 300_000;
105
+
106
+ /**
107
+ * 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
108
+ * its file (`only`), give it a `timeout` in milliseconds (a test that does not end by then is `cancelled`), its `risk` (`not-high` by
109
+ * default), or the `file` it is recorded under.
110
+ */
111
+ export type TestOptions = {
112
+ readonly skip?: boolean | string;
113
+ readonly todo?: boolean | string;
114
+ readonly only?: boolean;
115
+ readonly timeout?: number;
116
+ readonly risk?: Risk;
117
+ /** The quality characteristic the test proves, in the words of ISO/IEC 25010, recorded as `ifc.test.characteristic` (0021-ifqs FR-012). */
118
+ readonly characteristic?: string;
119
+ readonly file?: string;
120
+ };
121
+
122
+ /** The reason a test is recorded as skipped where another test of its file is marked `only` (FR-060). */
123
+ export const ONLY_REASON = "another test of this file is marked only";
124
+
125
+ /** A requirement cited by its specification and number: `0005-typescript-runtime FR-013`, or another repository's `erga 241-typescript-first FR-015`. */
126
+ export type Requirement = string;
127
+
128
+ /** The requirements each test proves, in the order the tests were registered, for a report. */
129
+ export const proofs: { readonly test: string; readonly requirements: readonly Requirement[] }[] = [];
130
+
131
+ /** The requirements declared as proven by review rather than a test, with the reason. */
132
+ export const reviews: { readonly requirement: Requirement; readonly reason: string }[] = [];
133
+
134
+ /** Every test of this process as it was recorded, in the order they ended (skipped and todo tests as they were registered) (FR-004). */
135
+ export const recorded: TestCase[] = [];
136
+
137
+ /** What a listener is given for each test that ends: the case, and the resource and context its signals carry. */
138
+ export type TestRecordEvent = { readonly test: TestCase; readonly resource: Resource; readonly context: TestContext };
139
+
140
+ const listeners: ((e: TestRecordEvent) => void)[] = [];
141
+
142
+ /**
143
+ * A listener given each test as it ends, beside `recorded` and `IFC_TEST_RECORD`: where an OpenTelemetry pipeline is installed, it hands
144
+ * `testCaseSpan` and `testCaseLog` of the event to its processors (0008-test-evidence FR-004). Returns the function that removes it.
145
+ */
146
+ export function onTestRecord(listener: (e: TestRecordEvent) => void): () => void {
147
+ listeners.push(listener);
148
+ return () => {
149
+ const i = listeners.indexOf(listener);
150
+ if (i >= 0) listeners.splice(i, 1);
151
+ };
152
+ }
153
+
154
+ // ---------------------------------------------------------------------------------------------------------------------------- the process's record
155
+
156
+ type Session = {
157
+ readonly traceId: TraceId;
158
+ readonly parentSpanId?: SpanId;
159
+ readonly resource: Resource;
160
+ readonly file: string | undefined;
161
+ readonly attempt: number;
162
+ };
163
+
164
+ let session: Session | undefined;
165
+
166
+ function randomBytes(n: number): Uint8Array {
167
+ const b = new Uint8Array(n);
168
+ crypto.getRandomValues(b);
169
+ return b;
170
+ }
171
+
172
+ function newSpanId(): SpanId {
173
+ for (;;) {
174
+ const s = spanIdFrom(randomBytes(8));
175
+ if (s.kind === "ok") return s.value;
176
+ }
177
+ }
178
+
179
+ function newTraceId(): TraceId {
180
+ for (;;) {
181
+ const t = traceIdFrom(randomBytes(16));
182
+ if (t.kind === "ok") return t.value;
183
+ }
184
+ }
185
+
186
+ function nowNanos(): bigint {
187
+ return BigInt(Math.round((performance.timeOrigin + performance.now()) * 1000)) * 1000n;
188
+ }
189
+
190
+ function append(line: string): void {
191
+ const file = current().file;
192
+ if (file === undefined) return;
193
+ try {
194
+ appendFileSync(file, `${line}\n`);
195
+ } catch {
196
+ // A record that cannot be written never changes the test's outcome; the run sees the test as missing.
197
+ }
198
+ }
199
+
200
+ function current(): Session {
201
+ if (session !== undefined) return session;
202
+ const env = process.env;
203
+ const parent = extractContext(env["TRACEPARENT"], env["TRACESTATE"]);
204
+ const { installation, warnings } = installationFromEnv(
205
+ { runtime: runtimeName(), runtimeVersion: runtimeVersion(), os: build.os, arch: build.arch },
206
+ env,
207
+ );
208
+ const attempt = Number(env["IFC_TEST_ATTEMPT"] ?? "1");
209
+ const file = env["IFC_TEST_RECORD"]?.trim();
210
+ session = {
211
+ traceId: parent?.traceId ?? newTraceId(),
212
+ ...(parent === undefined ? {} : { parentSpanId: parent.spanId }),
213
+ resource: installationResource(installation),
214
+ file: file === undefined || file === "" ? undefined : file,
215
+ attempt: Number.isSafeInteger(attempt) && attempt >= 1 ? attempt : 1,
216
+ };
217
+ if (warnings.length > 0) append(recordLine(session.resource, { records: warnings.map((w) => warningLog(w, nowNanos())) }));
218
+ return session;
219
+ }
220
+
221
+ function contextFor(spanId: SpanId): TestContext {
222
+ const s = current();
223
+ return { traceId: s.traceId, spanId, ...(s.parentSpanId === undefined ? {} : { parentSpanId: s.parentSpanId }) };
224
+ }
225
+
226
+ function emit(test: TestCase, spanId: SpanId): void {
227
+ const s = current();
228
+ const context = contextFor(spanId);
229
+ recorded.push(test);
230
+ if (s.file !== undefined) {
231
+ append(recordLine(s.resource, { spans: [testCaseSpan(test, context)] }));
232
+ append(recordLine(s.resource, { records: [testCaseLog(test, context)] }));
233
+ } else {
234
+ // Without IFC_TEST_RECORD, the test goes to the installed pipeline, if any (0008-test-evidence FR-004).
235
+ const pipeline = installed();
236
+ if (pipeline !== undefined) {
237
+ const source = { resource: s.resource, scope: TEST_SCOPE };
238
+ pipeline.emit({ kind: "span", span: testCaseSpan(test, context) }, source);
239
+ pipeline.emit({ kind: "log", record: testCaseLog(test, context) }, source);
240
+ }
241
+ }
242
+ for (const l of listeners) {
243
+ try {
244
+ l({ test, resource: s.resource, context });
245
+ } catch {
246
+ // A listener's failure never changes a test's outcome.
247
+ }
248
+ }
249
+ }
250
+
251
+ function emitStep(step: TestStep, test: Pick<TestCase, "id" | "file" | "name">, spanId: SpanId, parentSpanId: SpanId): void {
252
+ const s = current();
253
+ const span = testStepSpan(step, test, { traceId: s.traceId, spanId, parentSpanId });
254
+ if (s.file !== undefined) append(recordLine(s.resource, { spans: [span] }));
255
+ else installed()?.emit({ kind: "span", span }, { resource: s.resource, scope: TEST_SCOPE });
256
+ }
257
+
258
+ type Running = { readonly base: Omit<TestCase, "end" | "outcome">; readonly spanId: SpanId };
259
+
260
+ const running = new Map<SpanId, Running>();
261
+ let exitHooked = false;
262
+
263
+ function onExit(): void {
264
+ for (const [spanId, r] of [...running.entries()]) {
265
+ running.delete(spanId);
266
+ emit({ ...r.base, end: nowNanos(), outcome: "cancelled", reason: "the process exited before the test ended" }, spanId);
267
+ }
268
+ }
269
+
270
+ function hookExit(): void {
271
+ if (exitHooked) return;
272
+ exitHooked = true;
273
+ process.on("exit", onExit);
274
+ }
275
+
276
+ // ---------------------------------------------------------------------------------------------------------------------------- the test's file
277
+
278
+ const reals = new Map<string, string>();
279
+ const SELF = normalise(import.meta.url);
280
+
281
+ function normalise(location: string): string {
282
+ let path = location;
283
+ if (path.startsWith("file:")) {
284
+ try {
285
+ path = fileURLToPath(path);
286
+ } catch {
287
+ return path;
288
+ }
289
+ }
290
+ return real(isAbsolute(path) ? path : resolve(path));
291
+ }
292
+
293
+ /** A path with its links resolved (macOS's `/var` is `/private/var`, and a stack may name either), or as given where it does not resolve. */
294
+ function real(path: string): string {
295
+ const known = reals.get(path);
296
+ if (known !== undefined) return known;
297
+ let r = path;
298
+ try {
299
+ r = realpathSync(path);
300
+ } catch {
301
+ // A path that is not there (an eval's) is kept as it is.
302
+ }
303
+ reals.set(path, r);
304
+ return r;
305
+ }
306
+
307
+ const FRAME = /(?:\(|at\s+)((?:file:\/\/)?[^()\s]+?):\d+:\d+\)?\s*$/;
308
+
309
+ /** The file of the code that called into this module, relative to the working folder with `/`, from the call's stack. */
310
+ function callerFile(): string {
311
+ const stack = new Error("where").stack ?? "";
312
+ for (const line of stack.split("\n").slice(1)) {
313
+ const m = FRAME.exec(line.trim());
314
+ const location = m?.[1];
315
+ if (location === undefined || location.startsWith("node:") || location.startsWith("ext:")) continue;
316
+ const path = normalise(location);
317
+ if (path === SELF) continue;
318
+ return recordPath(relative(real(process.cwd()), path));
319
+ }
320
+ return "unknown";
321
+ }
322
+
323
+ // ---------------------------------------------------------------------------------------------------------------------------- recording
324
+
325
+ function testIdOf(file: string, name: string): string {
326
+ return createHash("sha256").update(`${file}\0${name}`).digest("hex");
327
+ }
328
+
329
+ function shown(value: unknown): string {
330
+ return cut(
331
+ redactText(typeof value === "string" ? value : inspect(value, { depth: 6, sorted: true, breakLength: 100, maxStringLength: 8192 })),
332
+ );
333
+ }
334
+
335
+ function failure(e: unknown): Pick<TestCase, "message" | "expected" | "actual"> {
336
+ const message = cut(redactText(e instanceof Error ? e.message : String(e)));
337
+ const assertion =
338
+ e instanceof Error &&
339
+ (e.name === "AssertionError" || ("code" in e && e.code === "ERR_ASSERTION")) &&
340
+ "operator" in e &&
341
+ e.operator !== "fail" &&
342
+ e.operator !== undefined;
343
+ if (!assertion || !("expected" in e) || !("actual" in e)) return { message };
344
+ return { message, expected: shown(e.expected), actual: shown(e.actual) };
345
+ }
346
+
347
+ class TimedOut extends Error {
348
+ /** How long the test was given. */
349
+ readonly ms: number;
350
+ constructor(ms: number) {
351
+ super(`the test did not end within ${ms} ms`);
352
+ this.name = "TimedOut";
353
+ this.ms = ms;
354
+ }
355
+ }
356
+
357
+ async function within(fn: () => void | Promise<void>, ms: number | undefined): Promise<void> {
358
+ if (ms === undefined) {
359
+ await fn();
360
+ return;
361
+ }
362
+ let timer: ReturnType<typeof setTimeout> | undefined;
363
+ try {
364
+ await Promise.race([
365
+ Promise.resolve().then(fn),
366
+ new Promise<never>((_, reject) => {
367
+ timer = setTimeout(() => reject(new TimedOut(ms)), ms);
368
+ }),
369
+ ]);
370
+ } finally {
371
+ if (timer !== undefined) clearTimeout(timer);
372
+ }
373
+ }
374
+
375
+ /**
376
+ * The context of a test or a step (FR-060): each step is a subtest of `node:test` on `node`, the runner's context, and is recorded in
377
+ * `into` and as a span whose parent is `parent` (the test's span or the enclosing step's), as it ends.
378
+ */
379
+ function stepContext(
380
+ name: string,
381
+ node: NodeTestContext,
382
+ test: Pick<TestCase, "id" | "file" | "name">,
383
+ testSpanId: SpanId,
384
+ parent: SpanId,
385
+ into: TestStep[],
386
+ skipped: (reason: string | undefined) => void,
387
+ ): StepContext {
388
+ const step = async (stepName: string, fn: StepFn): Promise<void> => {
389
+ if (!running.has(testSpanId))
390
+ throw new Error(`the step ${JSON.stringify(stepName)} ran after its test ${JSON.stringify(test.name)} ended`);
391
+ const spanId = newSpanId();
392
+ const start = nowNanos();
393
+ const inner: TestStep[] = [];
394
+ let ran = false;
395
+ let skippedHere = false;
396
+ let thrown: { readonly error: unknown } | undefined;
397
+ await node.test(stepName, async (sub: NodeTestContext) => {
398
+ ran = true;
399
+ try {
400
+ await fn(
401
+ stepContext(stepName, sub, test, testSpanId, spanId, inner, () => {
402
+ skippedHere = true;
403
+ }),
404
+ );
405
+ } catch (e) {
406
+ thrown = { error: e };
407
+ throw e;
408
+ }
409
+ });
410
+ const outcome: StepOutcome = thrown !== undefined ? "fail" : ran && !skippedHere ? "pass" : "skip";
411
+ const recordedStep: TestStep = {
412
+ name: stepName,
413
+ start,
414
+ end: nowNanos(),
415
+ outcome,
416
+ ...(thrown === undefined ? {} : { message: failure(thrown.error).message }),
417
+ ...(inner.length === 0 ? {} : { steps: inner }),
418
+ };
419
+ into.push(recordedStep);
420
+ emitStep(recordedStep, test, spanId, parent);
421
+ if (thrown !== undefined) throw thrown.error;
422
+ };
423
+ const skip = (reason?: string): void => {
424
+ skipped(reason);
425
+ if (typeof node.skip === "function") node.skip(reason);
426
+ };
427
+ return { name, step, skip };
428
+ }
429
+
430
+ async function runCase(
431
+ base: Omit<TestCase, "start" | "end" | "outcome" | "attempt">,
432
+ fn: TestFn,
433
+ timeout: number | undefined,
434
+ node: NodeTestContext,
435
+ ): Promise<void> {
436
+ hookExit();
437
+ const spanId = newSpanId();
438
+ const started = { ...base, start: nowNanos(), attempt: current().attempt };
439
+ running.set(spanId, { base: started, spanId });
440
+ if (current().file !== undefined) append(recordLine(current().resource, { records: [testStartLog(started, contextFor(spanId))] }));
441
+ const steps: TestStep[] = [];
442
+ const withSteps = (): { readonly steps?: readonly TestStep[] } => (steps.length === 0 ? {} : { steps: [...steps] });
443
+ let skipped: { readonly reason: string | undefined } | undefined;
444
+ const context = stepContext(base.name, node, base, spanId, spanId, steps, (reason) => {
445
+ skipped = { reason: reason === undefined ? undefined : reasonOf(reason) };
446
+ });
447
+ try {
448
+ await within(() => fn(context), timeout);
449
+ } catch (e) {
450
+ if (running.delete(spanId)) {
451
+ emit(
452
+ e instanceof TimedOut
453
+ ? { ...started, end: nowNanos(), outcome: "cancelled", reason: e.message, ...withSteps() }
454
+ : { ...started, end: nowNanos(), outcome: "fail", ...failure(e), ...withSteps() },
455
+ spanId,
456
+ );
457
+ }
458
+ throw e;
459
+ }
460
+ if (!running.delete(spanId)) return;
461
+ const reason = skipped?.reason;
462
+ emit(
463
+ skipped === undefined
464
+ ? { ...started, end: nowNanos(), outcome: "pass", ...withSteps() }
465
+ : { ...started, end: nowNanos(), outcome: "skip", ...(reason === undefined ? {} : { reason }), ...withSteps() },
466
+ spanId,
467
+ );
468
+ }
469
+
470
+ function reasonOf(v: boolean | string): string | undefined {
471
+ return typeof v === "string" && v.trim() !== "" ? cut(redactText(v)) : undefined;
472
+ }
473
+
474
+ /** A test of a file waiting to run, until a test of the file is marked `only` and it is skipped. */
475
+ type Waiting = { started: boolean; skipped: boolean; readonly skip: () => void };
476
+
477
+ /** For each file, whether a test of it is marked `only`, and its tests that have not started (FR-060). */
478
+ const onlyOf = new Map<string, { marked: boolean; readonly waiting: Set<Waiting> }>();
479
+
480
+ function onlyState(file: string): { marked: boolean; readonly waiting: Set<Waiting> } {
481
+ const known = onlyOf.get(file);
482
+ if (known !== undefined) return known;
483
+ const state = { marked: false, waiting: new Set<Waiting>() };
484
+ onlyOf.set(file, state);
485
+ return state;
486
+ }
487
+
488
+ function register(name: string, requirements: readonly Requirement[], fn: TestFn, options: TestOptions, file: string): void {
489
+ const base = {
490
+ id: testIdOf(file, name),
491
+ file,
492
+ name,
493
+ requirements: [...requirements],
494
+ risk: options.risk ?? "not-high",
495
+ ...(options.characteristic === undefined ? {} : { characteristic: options.characteristic }),
496
+ };
497
+ const notRun = (outcome: "skip" | "todo", v: boolean | string): void => {
498
+ const at = nowNanos();
499
+ const reason = reasonOf(v);
500
+ emit({ ...base, start: at, end: at, outcome, attempt: current().attempt, ...(reason === undefined ? {} : { reason }) }, newSpanId());
501
+ };
502
+ if (options.todo !== undefined && options.todo !== false) {
503
+ notRun("todo", options.todo);
504
+ void nodeTest(name, { todo: options.todo }, () => undefined);
505
+ return;
506
+ }
507
+ if (options.skip !== undefined && options.skip !== false) {
508
+ notRun("skip", options.skip);
509
+ void nodeTest(name, { skip: options.skip }, () => undefined);
510
+ return;
511
+ }
512
+ const state = onlyState(file);
513
+ const only = options.only === true;
514
+ if (only && !state.marked) {
515
+ state.marked = true;
516
+ for (const w of state.waiting) {
517
+ if (w.started) continue;
518
+ w.skipped = true;
519
+ w.skip();
520
+ }
521
+ state.waiting.clear();
522
+ } else if (!only && state.marked) {
523
+ notRun("skip", ONLY_REASON);
524
+ void nodeTest(name, { skip: ONLY_REASON }, () => undefined);
525
+ return;
526
+ }
527
+ // a test that starts real programs (git, openssl) is slow on a CI runner, Windows above all, and Bun's runner ends a test at 5 seconds unless it is told otherwise
528
+ const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
529
+ const waiting: Waiting | undefined = only ? undefined : { started: false, skipped: false, skip: () => notRun("skip", ONLY_REASON) };
530
+ if (waiting !== undefined) state.waiting.add(waiting);
531
+ const body = (t: NodeTestContext): Promise<void> => {
532
+ if (waiting !== undefined) {
533
+ state.waiting.delete(waiting);
534
+ if (waiting.skipped) {
535
+ // Recorded as skipped when the test marked only was registered; the runner is told where it can be.
536
+ if (typeof t.skip === "function") t.skip(ONLY_REASON);
537
+ return Promise.resolve();
538
+ }
539
+ waiting.started = true;
540
+ }
541
+ return runCase(base, fn, timeout, t);
542
+ };
543
+ void nodeTest(name, { timeout, ...(only ? { only: true } : {}) }, body);
544
+ }
545
+
546
+ /** A test registered with the runtime's runner, and recorded (0008-test-evidence FR-001). */
547
+ export function test(name: string, fn: TestFn, options: TestOptions = {}): void {
548
+ register(name, [], fn, options, options.file === undefined ? callerFile() : recordPath(options.file));
549
+ }
550
+
551
+ /** A test that proves one or more requirements, named for them: `0005-typescript-runtime FR-013: <name>`. */
552
+ export function proves(requirements: readonly [Requirement, ...Requirement[]], name: string, fn: TestFn, options: TestOptions = {}): void {
553
+ const full = `${requirements.join(", ")}: ${name}`;
554
+ proofs.push({ test: full, requirements });
555
+ register(full, requirements, fn, options, options.file === undefined ? callerFile() : recordPath(options.file));
556
+ }
557
+
558
+ /** 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). */
559
+ export function reviewed(requirement: Requirement, reason: string): void {
560
+ reviews.push({ requirement, reason });
561
+ const r: Review = { requirement, reason };
562
+ const s = current();
563
+ const record = reviewLog(r, nowNanos(), s.traceId);
564
+ if (s.file !== undefined) append(recordLine(s.resource, { records: [record] }));
565
+ else installed()?.emit({ kind: "log", record }, { resource: s.resource, scope: TEST_SCOPE });
566
+ }
567
+
568
+ /** Fails unless `value` is truthy; narrows its type. */
569
+ export function assert(value: unknown, message?: string): asserts value {
570
+ if (message === undefined) nodeAssert.ok(value);
571
+ else nodeAssert.ok(value, message);
572
+ }
573
+
574
+ /** Fails unless the two are deeply and strictly equal (the same types, prototypes and values). */
575
+ export function assertEquals<T>(actual: T, expected: T, message?: string): void {
576
+ if (message === undefined) nodeAssert.deepStrictEqual(actual, expected);
577
+ else nodeAssert.deepStrictEqual(actual, expected, message);
578
+ }
579
+
580
+ /** Fails where the two are deeply and strictly equal. */
581
+ export function assertNotEquals<T>(actual: T, expected: T, message?: string): void {
582
+ if (message === undefined) nodeAssert.notDeepStrictEqual(actual, expected);
583
+ else nodeAssert.notDeepStrictEqual(actual, expected, message);
584
+ }
585
+
586
+ /** Fails unless the two are the same value (`Object.is`). */
587
+ export function assertStrictEquals<T>(actual: T, expected: T, message?: string): void {
588
+ if (message === undefined) nodeAssert.strictEqual(actual, expected);
589
+ else nodeAssert.strictEqual(actual, expected, message);
590
+ }
591
+
592
+ /** Fails unless the value is neither `null` nor `undefined`; narrows its type. */
593
+ export function assertExists<T>(value: T, message?: string): asserts value is NonNullable<T> {
594
+ nodeAssert.ok(value !== null && value !== undefined, message ?? "expected a value, found null or undefined");
595
+ }
596
+
597
+ /**
598
+ * The value, narrowed to `NonNullable`, or a failure as {@link assertExists} fails where it is `null` or `undefined` (FR-065), so that a
599
+ * test reads `the(map.get(key)).name` where an assertion would need a statement of its own.
600
+ */
601
+ export function the<T>(value: T, message?: string): NonNullable<T> {
602
+ assertExists(value, message);
603
+ return value;
604
+ }
605
+
606
+ /** Fails unless the value is an instance of the class; narrows its type. */
607
+ export function assertInstanceOf<T>(value: unknown, Class: abstract new (...args: never[]) => T, message?: string): asserts value is T {
608
+ nodeAssert.ok(value instanceof Class, message ?? `expected an instance of ${Class.name}`);
609
+ }
610
+
611
+ /** Fails unless the text includes the part. */
612
+ export function assertStringIncludes(actual: string, expected: string, message?: string): void {
613
+ nodeAssert.ok(actual.includes(expected), message ?? `expected ${JSON.stringify(actual)} to include ${JSON.stringify(expected)}`);
614
+ }
615
+
616
+ /** Fails unless the two are different values (`Object.is`), as `@std/assert`'s `assertNotStrictEquals` (FR-060). */
617
+ export function assertNotStrictEquals<T>(actual: T, expected: T, message?: string): void {
618
+ if (message === undefined) nodeAssert.notStrictEqual(actual, expected);
619
+ else nodeAssert.notStrictEqual(actual, expected, message);
620
+ }
621
+
622
+ /**
623
+ * Fails unless the two numbers are within `tolerance` of each other (`1e-7` by default), as `@std/assert`'s `assertAlmostEquals`
624
+ * (FR-060): the same value (`Object.is`, so `NaN` is close to `NaN` and an infinity to itself) passes, else `|expected - actual|` must not
625
+ * exceed the tolerance.
626
+ */
627
+ export function assertAlmostEquals(actual: number, expected: number, tolerance = 1e-7, message?: string): void {
628
+ if (Object.is(actual, expected)) return;
629
+ const delta = Math.abs(expected - actual);
630
+ if (delta <= tolerance) return;
631
+ const f = (n: number): string => (Number.isInteger(n) ? String(n) : n.toExponential());
632
+ throw new nodeAssert.AssertionError({
633
+ message: `Expected actual: "${f(actual)}" to be close to "${f(expected)}": delta "${f(delta)}" is greater than "${f(tolerance)}"${
634
+ message === undefined ? "." : `: ${message}`
635
+ }`,
636
+ actual,
637
+ expected,
638
+ operator: "assertAlmostEquals",
639
+ });
640
+ }
641
+
642
+ /** Fails where the text matches the pattern, as `@std/assert`'s `assertNotMatch` (FR-060). */
643
+ export function assertNotMatch(actual: string, pattern: RegExp, message?: string): void {
644
+ if (message === undefined) nodeAssert.doesNotMatch(actual, pattern);
645
+ else nodeAssert.doesNotMatch(actual, pattern, message);
646
+ }
647
+
648
+ /** Fails unless the text matches the pattern. */
649
+ export function assertMatch(actual: string, pattern: RegExp, message?: string): void {
650
+ if (message === undefined) nodeAssert.match(actual, pattern);
651
+ else nodeAssert.match(actual, pattern, message);
652
+ }
653
+
654
+ /** Fails unless every expected element is deeply equal to some element of the array. */
655
+ export function assertArrayIncludes<T>(actual: readonly T[], expected: readonly T[], message?: string): void {
656
+ const missing = expected.filter((e) => !actual.some((a) => isDeepStrictEqual(a, e)));
657
+ nodeAssert.ok(missing.length === 0, message ?? `expected the array to include ${JSON.stringify(missing)}`);
658
+ }
659
+
660
+ function isDeepStrictEqual(a: unknown, b: unknown): boolean {
661
+ try {
662
+ nodeAssert.deepStrictEqual(a, b);
663
+ return true;
664
+ } catch {
665
+ return false;
666
+ }
667
+ }
668
+
669
+ /** The error a function throws; fails where it throws none, or one not of `Class`, or one whose message does not include `includes`. */
670
+ export function assertThrows<E extends Error = Error>(
671
+ fn: () => unknown,
672
+ Class?: abstract new (...args: never[]) => E,
673
+ includes?: string,
674
+ ): E {
675
+ try {
676
+ fn();
677
+ } catch (e) {
678
+ checkThrown(e, Class, includes);
679
+ return e as E;
680
+ }
681
+ throw new nodeAssert.AssertionError({ message: "expected the function to throw" });
682
+ }
683
+
684
+ /** The error a promise rejects with; fails where it fulfils, or rejects with one not of `Class`, or whose message does not include `includes`. */
685
+ export async function assertRejects<E extends Error = Error>(
686
+ fn: () => PromiseLike<unknown>,
687
+ Class?: abstract new (...args: never[]) => E,
688
+ includes?: string,
689
+ ): Promise<E> {
690
+ try {
691
+ await fn();
692
+ } catch (e) {
693
+ checkThrown(e, Class, includes);
694
+ return e as E;
695
+ }
696
+ throw new nodeAssert.AssertionError({ message: "expected the promise to reject" });
697
+ }
698
+
699
+ function checkThrown(e: unknown, Class: (abstract new (...args: never[]) => Error) | undefined, includes: string | undefined): void {
700
+ if (Class !== undefined && !(e instanceof Class)) {
701
+ throw new nodeAssert.AssertionError({
702
+ message: `expected ${Class.name}, got ${e instanceof Error ? e.name : String(e)}: ${String(e)}`,
703
+ });
704
+ }
705
+ if (includes !== undefined && !(e instanceof Error && e.message.includes(includes))) {
706
+ throw new nodeAssert.AssertionError({ message: `expected the error to include ${JSON.stringify(includes)}, got ${String(e)}` });
707
+ }
708
+ }
709
+
710
+ /** Fails, with the message. */
711
+ export function fail(message: string): never {
712
+ throw new nodeAssert.AssertionError({ message });
713
+ }