Initial Commit
This commit is contained in:
@@ -0,0 +1,47 @@
|
||||
# Testing generics hardening
|
||||
|
||||
**Package**: `@suaveplan/testing`
|
||||
**Status**: PROPOSED
|
||||
**Type**: feature
|
||||
|
||||
## Why
|
||||
|
||||
Slice 1 of the testing-suite hardening sweep. Four type-level cliffs in the public surface forced consumers into `as` casts or eroded inference back to `unknown`:
|
||||
|
||||
1. `FixtureManager.get(name)` returned `FixtureState | undefined` — callers who registered `FixtureDefinition<MyShape>` lost `MyShape` on read.
|
||||
2. `RequestBuilder` / `ResponseBuilder` preset factories (`get`, `post`, `ok`, `created`, …) returned the bare class with `body: unknown`, defeating the whole point of typed test request/response builders.
|
||||
3. `assertThrows` / `assertThrowsAsync` returned `Error`, so callers who matched on `TestingError` had to follow up with an `instanceof` narrowing before reading `.code`.
|
||||
4. The `typecheck` script in `package.json` invoked `bunx tsc` — a Rule 1 violation (no direct `tsc`).
|
||||
|
||||
Plus one spec-coverage drift: `openspec/specs/testing/spec.md` claimed ≥ 95% coverage while `vitest.config.ts` enforces 100% across all four metrics and CLAUDE.md mandates 100%.
|
||||
|
||||
## What changes
|
||||
|
||||
- MODIFIED: `RequestBuilder` is now `RequestBuilder<TBody = unknown>`. `body()` accepts `TBody | undefined`, `state` returns `RequestBuilderState<TBody>`, `build()` returns `TestRequest<TBody | undefined>`.
|
||||
- MODIFIED: `ResponseBuilder` is now `ResponseBuilder<TBody = unknown>` with the same body-typed contract.
|
||||
- MODIFIED: every preset factory (`get`, `post`, `put`, `patch`, `del`, `head`, `options`, `ok`, `created`, `noContent`, `badRequest`, `unauthorized`, `notFound`, `serverError`) takes `<TBody = unknown>` and returns the typed builder.
|
||||
- MODIFIED: `TestRequest` and `TestResponse` are now `TestRequest<TBody = unknown>` and `TestResponse<TBody = unknown>`.
|
||||
- MODIFIED: `FixtureManager.get` is now `get<T = unknown>(name): FixtureState<T> | undefined`. The internal cast is confined to the impl.
|
||||
- MODIFIED: `assertThrows<TError extends Error = Error>(fn, matcher?): TError` and the async variant. Internal cast at the boundary.
|
||||
- MODIFIED: `package.json` `scripts.typecheck` switched from `bunx tsc --noEmit --composite false -p tsconfig.lib.json` to `tsc --project tsconfig.lib.json --noEmit`, matching the canonical pattern in non-dev packages and dropping the `bunx` wrapper.
|
||||
- MODIFIED: `openspec/specs/testing/spec.md` "Coverage and docs gates" requirement: bumped from ≥ 95% to 100% across statements, branches, functions, and lines (matches the wired `vitest.config.ts` thresholds and CLAUDE.md mandate). Path string also corrected from `packages/universal/testing/` to `packages/dev/testing/` (folder reorg leftover).
|
||||
- MODIFIED: `tests/spec-conformance.spec-conformance.test.ts` `ALLOWED_NONDETERMINISM` extended to include `src/helpers/test-helpers.ts` (`measureTime`) and `src/observability/with-observability.ts` (histogram duration recording). Both legitimately read `performance.now()` at the wrapper boundary; injecting a `Clock` would defeat the contract (callers ask for real elapsed time). The exemption is documented in-test.
|
||||
- ADDED: `src/builders/request-builder/request-builder.spec-conformance.test.ts`, `src/builders/response-builder/response-builder.spec-conformance.test.ts`, `src/fixtures/fixture-manager/fixture-manager.spec-conformance.test.ts`, `src/helpers/test-helpers.spec-conformance.test.ts` — `expectTypeOf` pins on every generic claim.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- No runtime behavior change. All 295 existing tests continue to pass byte-for-byte; the 17-test increase is purely the new type-level conformance pins.
|
||||
- Slice 2 (`testing-dom`, `testing-e2e`) and Slice 3 (`testing-integration*`) are owned by sibling agents; no files outside `packages/dev/testing/` and `openspec/{specs,changes}/testing/` are touched.
|
||||
- `MANIFEST.md`, root `bun.lock`, and `CLAUDE.md` are intentionally not edited — orchestrator territory.
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/builders/request-builder/request-builder.spec-conformance.test.ts` — pins every preset (`get/post/put/patch/del/head/options`) and the class instance to the new generic shape via `expectTypeOf`.
|
||||
- `src/builders/response-builder/response-builder.spec-conformance.test.ts` — same pattern for `ok/created/noContent/badRequest/unauthorized/notFound/serverError` and the class.
|
||||
- `src/fixtures/fixture-manager/fixture-manager.spec-conformance.test.ts` — pins `get<T>` overload, narrowing of `state.value`, and the unknown-default fallback.
|
||||
- `src/helpers/test-helpers.spec-conformance.test.ts` — pins `assertThrows<TError>` and `assertThrowsAsync<TError>` returning `TError` / `Promise<TError>`.
|
||||
- Existing runtime tests (`request-builder.test.ts`, `response-builder.test.ts`, `fixture-manager.test.ts`, `test-helpers.test.ts`) continue to exercise behavior at runtime; type widening means none of them needed editing.
|
||||
|
||||
## Migration impact
|
||||
|
||||
None — additive only. The default type parameters (`TBody = unknown`, `T = unknown`, `TError extends Error = Error`) preserve the exact pre-change inferred types for any caller that does not pass an explicit type argument. Callers who want the new tightening opt in by writing `post<MyBody>(…)`, `mgr.get<MyShape>("name")`, or `assertThrows<MyError>(…)`.
|
||||
@@ -0,0 +1,86 @@
|
||||
# Capability Spec Delta: testing (testing-generics-hardening)
|
||||
|
||||
**Package**: `@suaveplan/testing`
|
||||
**Status**: PROPOSED
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Builder presets thread `<TBody>` through `.build()`
|
||||
|
||||
Every `RequestBuilder` and `ResponseBuilder` preset factory SHALL accept an optional `<TBody = unknown>` type parameter. The returned builder MUST be `RequestBuilder<TBody>` / `ResponseBuilder<TBody>` and `.build()` MUST return `TestRequest<TBody | undefined>` / `TestResponse<TBody | undefined>`. Callers who omit the parameter MUST observe the same `unknown` defaults that pre-dated this change.
|
||||
|
||||
#### Scenario: post<TBody> threads body type
|
||||
|
||||
- **WHEN** `post<{ name: string }>("/x", { name: "a" }).build()` is called
|
||||
- **THEN** the inferred return type is `TestRequest<{ name: string } | undefined>`
|
||||
|
||||
#### Scenario: ok<TBody> threads body type
|
||||
|
||||
- **WHEN** `ok<{ id: string }>({ id: "1" }).build()` is called
|
||||
- **THEN** the inferred return type is `TestResponse<{ id: string } | undefined>`
|
||||
|
||||
#### Scenario: zero-arg preset preserves unknown default
|
||||
|
||||
- **WHEN** `get("/x").build()` or `ok().build()` is called without a type argument
|
||||
- **THEN** the inferred return types are `TestRequest<unknown>` and `TestResponse<unknown>` respectively
|
||||
|
||||
**Verified by:** `src/builders/request-builder/request-builder.spec-conformance.test.ts::"post<TBody>(url, body).build() returns TestRequest<TBody | undefined>"` AND `src/builders/request-builder/request-builder.spec-conformance.test.ts::"get<TBody>(url).build() returns TestRequest<TBody | undefined>"` AND `src/builders/request-builder/request-builder.spec-conformance.test.ts::"put<TBody>, patch<TBody>, del<TBody>, head<TBody>, options<TBody> all thread TBody"` AND `src/builders/request-builder/request-builder.spec-conformance.test.ts::"zero-arg presets default TBody to unknown"` AND `src/builders/request-builder/request-builder.spec-conformance.test.ts::"RequestBuilder<TBody> exposes typed body field on state and build"` AND `src/builders/response-builder/response-builder.spec-conformance.test.ts::"ok<TBody>(body).build() returns TestResponse<TBody | undefined>"` AND `src/builders/response-builder/response-builder.spec-conformance.test.ts::"created<TBody>, badRequest<TBody>, unauthorized<TBody>, notFound<TBody>, serverError<TBody> thread TBody"` AND `src/builders/response-builder/response-builder.spec-conformance.test.ts::"noContent<TBody>() returns ResponseBuilder<TBody>"` AND `src/builders/response-builder/response-builder.spec-conformance.test.ts::"zero-arg presets default TBody to unknown"` AND `src/builders/response-builder/response-builder.spec-conformance.test.ts::"ResponseBuilder<TBody> exposes typed body on state and build"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: `FixtureManager.get` accepts a typed value parameter
|
||||
|
||||
`FixtureManager.get` SHALL accept an optional `<T = unknown>` type parameter and return `FixtureState<T> | undefined`. The narrowing SHALL extend through `state.value` so callers see `T | null` without a follow-up cast. Internally the manager MAY perform a single boundary cast; consumers MUST NOT need any.
|
||||
|
||||
#### Scenario: typed get returns typed state
|
||||
|
||||
- **WHEN** `mgr.get<DbFixture>("db")` is called
|
||||
- **THEN** the inferred return type is `FixtureState<DbFixture> | undefined` AND the inferred type of `state.value` (after `state !== undefined`) is `DbFixture | null`
|
||||
|
||||
#### Scenario: untyped get preserves unknown default
|
||||
|
||||
- **WHEN** `mgr.get("db")` is called without a type argument
|
||||
- **THEN** the inferred return type is `FixtureState<unknown> | undefined`
|
||||
|
||||
**Verified by:** `src/fixtures/fixture-manager/fixture-manager.spec-conformance.test.ts::"get<T>(name) returns FixtureState<T> | undefined"` AND `src/fixtures/fixture-manager/fixture-manager.spec-conformance.test.ts::"get<T>(name) narrows state.value to T | null"` AND `src/fixtures/fixture-manager/fixture-manager.spec-conformance.test.ts::"get(name) without explicit T defaults to FixtureState<unknown>"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: `assertThrows` returns the caller-narrowed error type
|
||||
|
||||
`assertThrows` and `assertThrowsAsync` SHALL accept an optional `<TError extends Error = Error>` type parameter and return `TError` / `Promise<TError>` respectively. Internally the helper MAY cast at the boundary; the runtime fallback (wrap a non-`Error` throw in `new Error(String(value))`) MUST remain.
|
||||
|
||||
#### Scenario: typed assertThrows returns typed error
|
||||
|
||||
- **WHEN** `assertThrows<TestingError>(fn)` is called and `fn` throws a `TestingError`
|
||||
- **THEN** the inferred return type is `TestingError` AND the caller can read `.code` without a follow-up `instanceof` narrowing
|
||||
|
||||
#### Scenario: untyped assertThrows defaults to Error
|
||||
|
||||
- **WHEN** `assertThrows(fn)` is called without a type argument
|
||||
- **THEN** the inferred return type is `Error`
|
||||
|
||||
#### Scenario: async variant matches sync contract
|
||||
|
||||
- **WHEN** `assertThrowsAsync<TestingError>(asyncFn)` is awaited
|
||||
- **THEN** the inferred awaited type is `TestingError`
|
||||
|
||||
**Verified by:** `src/helpers/test-helpers.spec-conformance.test.ts::"assertThrows<TError>() returns TError"` AND `src/helpers/test-helpers.spec-conformance.test.ts::"assertThrows() without explicit TError defaults to Error"` AND `src/helpers/test-helpers.spec-conformance.test.ts::"assertThrowsAsync<TError>() returns Promise<TError>"` AND `src/helpers/test-helpers.spec-conformance.test.ts::"assertThrowsAsync() without explicit TError defaults to Error"`
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Coverage and docs gates
|
||||
|
||||
Istanbul statement + branch + function + line coverage across `packages/dev/testing/src/` (excluding `*.bench.ts` and `*.schemas.ts`) MUST be 100%. 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.
|
||||
|
||||
#### Scenario: Coverage gate in CI
|
||||
|
||||
- **WHEN** `bunx turbo test:coverage --filter=@suaveplan/testing` runs
|
||||
- **THEN** reported statement, branch, function, and line coverage are each 100%
|
||||
|
||||
#### Scenario: Docs coverage enforced
|
||||
|
||||
- **WHEN** a script enumerates implementation files under `src/` (excluding the stated exclusions) and checks for sibling `.md` files
|
||||
- **THEN** every implementation file has a sibling `.md` AND every `.md` is ≥ 200 non-code words
|
||||
|
||||
**Verified by:** `vitest.config.ts` (coverage thresholds set to 100/100/100/100) AND `bunx turbo test:coverage --filter=@suaveplan/testing` (CI run) AND `bun run docs:check` (sibling-`.md` enumeration script)
|
||||
@@ -0,0 +1,63 @@
|
||||
# Tasks — Testing generics hardening
|
||||
|
||||
> Every checkbox reflects work actually done in this change. Genesis-original package, no `enterprise/<pkg>.md` source mapping.
|
||||
|
||||
## 1. Spec authoring
|
||||
|
||||
- [x] 1.1 Read `openspec/specs/testing/spec.md`
|
||||
- [x] 1.2 Read `openspec/AGENTS.md` Sections 13 and 14 (via CLAUDE.md mandate)
|
||||
- [x] 1.3 Draft `proposal.md` from `openspec/templates/proposal.md`
|
||||
- [x] 1.4 Source mapping: N/A (genesis-original package)
|
||||
- [x] 1.5 Draft `specs/testing/spec.md` delta from `openspec/templates/spec-delta.md`
|
||||
- [x] 1.6 Every requirement in the spec delta carries a `**Verified by:**` line naming concrete `it(...)` titles
|
||||
|
||||
## 2. Implementation
|
||||
|
||||
- [x] 2.1 Make `TestRequest` and `TestResponse` generic over `TBody` (default `unknown`) in `src/types/http.types.ts`
|
||||
- [x] 2.2 Make `RequestBuilder` generic over `TBody`; `body()`, `state` getter, and `build()` return typed shapes
|
||||
- [x] 2.3 Add `<TBody = unknown>` to every request preset (`get`, `post`, `put`, `patch`, `del`, `head`, `options`) and the private `presetBuilder`
|
||||
- [x] 2.4 Make `ResponseBuilder` generic over `TBody`; `body()`, `state` getter, and `build()` return typed shapes
|
||||
- [x] 2.5 Add `<TBody = unknown>` to every response preset (`ok`, `created`, `noContent`, `badRequest`, `unauthorized`, `notFound`, `serverError`) and the private `presetBuilder`
|
||||
- [x] 2.6 Add typed `get<T>(name)` overload to `FixtureManager`; cast confined to impl
|
||||
- [x] 2.7 Add `<TError extends Error = Error>` to `assertThrows` and `assertThrowsAsync`; cast at boundary
|
||||
- [x] 2.8 Switch `package.json` `scripts.typecheck` from `bunx tsc …` to `tsc --project tsconfig.lib.json --noEmit`
|
||||
- [x] 2.9 Bump `openspec/specs/testing/spec.md` coverage requirement from ≥ 95% to 100% across statements/branches/functions/lines; correct path drift `packages/universal/testing/` → `packages/dev/testing/`
|
||||
- [x] 2.10 Extend `tests/spec-conformance.spec-conformance.test.ts` `ALLOWED_NONDETERMINISM` to include `measureTime` (helpers) and observability wrapper, with in-test justification comments
|
||||
|
||||
## 3. Tests
|
||||
|
||||
- [x] 3.1 `src/builders/request-builder/request-builder.spec-conformance.test.ts` — `expectTypeOf` on every preset and the class
|
||||
- [x] 3.2 `src/builders/response-builder/response-builder.spec-conformance.test.ts` — `expectTypeOf` on every preset and the class
|
||||
- [x] 3.3 `src/fixtures/fixture-manager/fixture-manager.spec-conformance.test.ts` — `expectTypeOf` on `get<T>` overload
|
||||
- [x] 3.4 `src/helpers/test-helpers.spec-conformance.test.ts` — `expectTypeOf` on `assertThrows<TError>` / `assertThrowsAsync<TError>`
|
||||
- [x] 3.5 Every `it(...)` carries `{ timeout: 5000 }`
|
||||
|
||||
## 4. Documentation
|
||||
|
||||
- [x] 4.1 `request-builder.md` updated with generic preset signatures + generic example
|
||||
- [x] 4.2 `response-builder.md` updated with generic preset signatures + generic example
|
||||
- [x] 4.3 `test-helpers.md` updated with `assertThrows<TError>` signature + generic example
|
||||
- [x] 4.4 `fixture-manager.md` updated with `get<T>` overload signature
|
||||
|
||||
## 5. Pre-archive verification (the 5-gate triple)
|
||||
|
||||
- [x] 5.1 `bun run check` — Biome 0/0/0 across the whole monorepo
|
||||
- [x] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/testing` — green (4/4 tasks)
|
||||
- [x] 5.3 `bunx turbo test:coverage --filter=@suaveplan/testing` — 100/100/100/100
|
||||
- [x] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/testing` — PASS (0 error, 0 warn, 0 info)
|
||||
- [x] 5.5 `bunx turbo build --filter=@suaveplan/testing` — green
|
||||
|
||||
## 6. Pre-archive 7-row checklist (AGENTS.md Section 13)
|
||||
|
||||
- [x] 6.1 Generics threaded; `expectTypeOf` assertions on every literal-type claim
|
||||
- [x] 6.2 Zod schemas already wired (existing requirement, untouched)
|
||||
- [x] 6.3 Every error code in `error-codes.ts` thrown by at least one production path (existing requirement, untouched)
|
||||
- [x] 6.4 Strict-mode behaviors tested both on and off (existing requirement, untouched)
|
||||
- [x] 6.5 OTel instruments emitted (existing requirement, untouched)
|
||||
- [x] 6.6 Lifecycle dedup tested (existing requirement, untouched)
|
||||
- [x] 6.7 No retroactive tick — every box above reflects work done in this change
|
||||
|
||||
## 7. Archive
|
||||
|
||||
- [x] 7.1 Fold spec delta into `openspec/specs/testing/spec.md`
|
||||
- [x] 7.2 Move `openspec/changes/testing-generics-hardening/` → `openspec/archive/2026-04-27-testing-generics-hardening/`
|
||||
Reference in New Issue
Block a user