Initial Commit

openspec/archive/2026-04-29-testing-spec-conformance/specs/testing/spec.md

@@ -0,0 +1,27 @@
+# Spec delta — testing-spec-conformance
+
+## MODIFIED Requirements
+
+### Requirement: Public types validated via Zod
+
+Every public function's input and output types SHALL be modeled by a Zod schema exported from a sibling `<module>.schemas.ts` file under a stable namespace (e.g. `RequestBuilderSchemas.input`). Schemas MUST NOT be imported by functional entry points; consumers opt in by importing `*.schemas.ts` directly. **The body field on `TestRequest`, `TestResponse`, `RequestBuilderState`, and `ResponseBuilderState` SHALL be expressed via a `<TBody = unknown>` generic so consumers can pin the body type at the call site without resorting to assertions.**
+
+**Verified by:** `tests/spec-conformance.spec-conformance.test.ts::"TESTING-TYPES — generic body threading on builders > RequestBuilder<TBody> exposes TBody on state.body and build().body"`, `tests/spec-conformance.spec-conformance.test.ts::"TESTING-TYPES — generic body threading on builders > ResponseBuilder<TBody> exposes TBody on state.body and build().body"`, `tests/spec-conformance.spec-conformance.test.ts::"TESTING-TYPES — generic body threading on builders > default generic falls back to unknown for zero-config callers"`
+
+### Requirement: Deterministic clock and RNG via dependency injection
+
+Every public function that reads time, randomness, or iterates SHALL accept an optional `{ clock?: Clock; rng?: Rng; signal?: AbortSignal }` options parameter. Zero-config callers MUST get behaviorally stable defaults: `defaultClock` (backed by `Date.now` / `performance.now`), `cryptoRng` (backed by `crypto.getRandomValues`), and no abort. **`measureTime` and `withObservability` MUST honour an injected `clock` rather than reading `Date.now()` / `performance.now()` directly; the only files in `src/` permitted to read those globals are `context/context.ts`, `clock/fake-clock/fake-clock.ts`, and `storage/memory-store/memory-store.ts`.**
+
+**Verified by:** `tests/spec-conformance.spec-conformance.test.ts::"TESTING-DETERMINISM — no module-scope wall-clock / RNG > Math.random / Date.now / performance.now appear only in allow-listed files"`
+
+### Requirement: Coverage and docs gates
+
+Istanbul statement + branch coverage across `packages/dev/testing/src/` (excluding `*.bench.ts` and `*.schemas.ts`) MUST be ≥ 95%. Every implementation file (`*.ts` other than `*.test.ts`, `*.bench.ts`, `*.schemas.ts`, inner-dir `*.types.ts`, barrel `index.ts`) MUST have a sibling `.md` file of ≥ 200 words (excluding code fences) with a simple and an advanced usage example.
+
+**Verified by:** Repo-level pre-publish gate.
+
+### Requirement: No disallowed constructs in `src/`
+
+Files under `packages/dev/testing/src/` MUST NOT contain the `any` keyword, `@ts-ignore`, `@ts-expect-error`, `TODO`, `FIXME`, `@deprecated`, `it.skip`, `describe.skip`, `test.skip`, `.only`, or any mock/stub of runtime behaviour intended for production code paths.
+
+**Verified by:** `tests/no-disallowed.test.ts::"src/ contains no disallowed constructs"`