suaveplan/openspec/archive/2026-04-27-testing-dom-runner-and-matchers-hardening/tasks.md

Tasks — testing-dom: runner generics + matchers ambient + async-span hardening

1. Spec authoring

• 1.1 Read openspec/specs/testing-dom/spec.md end-to-end
• 1.2 Read openspec/AGENTS.md Sections 13 and 14
• 1.3 Draft proposal.md
• 1.4 Draft specs/testing-dom/spec.md delta
• 1.5 Every requirement in the delta carries a **Verified by:** line naming concrete it(...) titles

2. Implementation

• 2.1 Add RunnerMock<TArgs, TReturn> to src/runner/mocks.ts (vitest path) and src/runner/bun-test.ts (bun-test path)
• 2.2 Have fn<TArgs,TReturn>() return RunnerMock<TArgs,TReturn> on both paths
• 2.3 Add SpyHandle to bun-test path; re-export from runner/vitest.ts, runner/index.ts, package barrel
• 2.4 Add import type {} from "@testing-library/jest-dom" to src/matchers/matchers.ts
• 2.5 Replace hard vitest import in src/user/setup-user.ts with runner-adapter import
• 2.6 Add async-aware span lifecycle in src/observability/instrumented.ts (Promise detection + .then/.catch cleanup)
• 2.7 Update spec coverage gate to 100% and fix package path reference

3. Tests

• 3.1 src/runner/runner.spec-conformance.test.ts — runner generics pinned via expectTypeOf on both paths
• 3.2 src/matchers/matchers.spec-conformance.test.tsx — ambient augmentation pinned via expectTypeOf(expect(el).toBeInTheDocument).toBeFunction()
• 3.3 src/user/setup-user.test.ts — added source-level pin against vitest hard-import
• 3.4 src/observability/instrumented.test.ts — added 3 async-span tests (resolve, reject, reject-non-Error)
• 3.5 Every it(...) carries { timeout: 5000 }

4. Documentation

• 4.1 Sibling .md updated for bun-test.md, mocks.md, matchers.md, setup-user.md, instrumented.md

5. Pre-archive verification (the 5-gate triple)

• 5.1 bun run check — Biome 0/0/0
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/testing-dom — green
• 5.3 bunx turbo test:coverage --filter=@suaveplan/testing-dom — 100/100/100/100
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/testing-dom — exit 0
• 5.5 bunx turbo build --filter=@suaveplan/testing-dom — green

6. Pre-archive 7-row checklist

• 6.1 Generics threaded; expectTypeOf assertions on every literal-type claim
• 6.2 No new boundary inputs added — existing Zod surface unchanged
• 6.3 No new error codes
• 6.4 Strict-mode N/A here
• 6.5 OTel span lifetime now asserted via observable elapsed time
• 6.6 N/A — no lifecycle dedup claim
• 6.7 No retroactive tick — every box reflects work in this change

7. Archive

• 7.1 Fold spec delta into openspec/specs/testing-dom/spec.md
• 7.2 Move folder → openspec/archive/2026-04-27-testing-dom-runner-and-matchers-hardening/