suaveplan/openspec/archive/2026-04-19-enterprise-testing-dom/tasks.md

Archived 2026-04-19: package shipped under universal/dev/testing-dom. Spec drift was rectified by openspec/changes/testing-dom-spec-conformance/ (2026-04-26), which folded **Verified by:** lines into the canonical spec, pinned the dual-runner conditional-exports shape, and corrected the path reference in the coverage requirement.

1. Catalogs and package skeleton

• 1.1 Extend root package.json catalogs.testing (or new catalogs.dom-testing) with @testing-library/react, @testing-library/jest-dom, @testing-library/user-event, @testing-library/dom, @vitejs/plugin-react. Pin versions via Bun overrides where stability matters.
• 1.2 Create packages/universal/testing-dom/ skeleton: package.json (version 0.1.0, dual-runner conditional exports, runtime deps = vitest+happy-dom+testing-library+@opentelemetry/api+zod+tslib, devDep on @suaveplan/testing), tsconfig.lib.json, vite.config.ts, vitest.config.ts, README.md.
• 1.3 Verify bunx turbo ls --filter=@suaveplan/testing-dom... (runtime closure) contains zero @suaveplan/* packages.

2. Migrate from staging

• 2.1 Move packages/universal/testing-dom-staging/runner/ into packages/universal/testing-dom/src/runner/. Update internal imports.
• 2.2 Move packages/universal/testing-dom-staging/config/ into packages/universal/testing-dom/src/config/.
• 2.3 Move packages/universal/testing-dom-staging/polyfills.ts into packages/universal/testing-dom/src/setup/polyfills.ts.
• 2.4 Update createTestConfig's polyfill setupFile path to @suaveplan/testing-dom/polyfills.
• 2.5 Delete packages/universal/testing-dom-staging/ after migration.

3. Local error hierarchy

• 3.1 Implement src/errors/testing-dom-error.ts with TestingDomError base + RenderError, MatcherError, ConfigError, AbortedError subclasses.
• 3.2 Implement src/errors/codes.ts enumerating TESTING_DOM.<DOMAIN>.<REASON> constants.
• 3.3 Update migrated createTestConfig to throw ConfigError instead of the old ConfigError from @suaveplan/testing.
• 3.4 Co-locate tests + .md for the error module.

4. Render helpers

• 4.1 Implement src/render/render-component.ts with renderComponent(ui, options?) — wraps @testing-library/react's render, returns RenderResult extended with userEvent.
• 4.2 Auto-register cleanup via vitest's afterEach (per-test-file, not global to avoid leak between unrelated suites).
• 4.3 Throws RenderError("TESTING_DOM.RENDER.SETUP_FAILED") on render-time exceptions.
• 4.4 Co-locate tests + .md + .schemas.ts.

5. Query aliases

• 5.1 Implement src/queries/queries.ts re-exporting screen, within, and accessibility-first aliases (byRole, byLabelText, byText, byPlaceholderText, findRole, queryRole, etc.).
• 5.2 Document the testid-as-fallback policy in the module's .md.

6. User events

• 6.1 Implement src/user/setup-user.ts: setupUser(options?) returning a UserEvent instance with happy-dom-friendly defaults (pointerEventsCheck: 0).
• 6.2 If vi.isFakeTimers() returns true at setup time, wire advanceTimers: vi.advanceTimersByTime automatically.
• 6.3 Co-locate tests + .md.

7. jest-dom matchers

• 7.1 Implement src/matchers/matchers.ts — side-effecting import that calls expect.extend(...) with the jest-dom matcher set.
• 7.2 Re-export under subpath @suaveplan/testing-dom/matchers.
• 7.3 Smoke test: import the matchers module, render a node, assert toBeInTheDocument.

8. OTEL instrumentation (gated)

• 8.1 Implement src/observability/instrumented.ts — counters/histograms gated behind process.env.TESTING_DOM_OTEL_ENABLED === "1". No-op otherwise.
• 8.2 Wrap renderComponent and setupUser with the gated instrumentation.

9. Tests + cross-cutting guards

• 9.1 Co-located unit tests for every public module in src/.
• 9.2 tests/dep-graph.test.ts — assert no @suaveplan/* runtime deps.
• 9.3 tests/no-disallowed.test.ts — any / ts-ignore / TODO etc. grep guard.
• 9.4 tests/tree-shake.test.ts — verify subpaths don't drag unrelated modules.
• 9.5 tests/properties.test.ts — fast-check property tests for any pure helpers (matcher predicates, query name normalization).
• 9.6 Coverage ≥ 95% on every dimension (statements, branches, functions, lines).

10. Docs and examples

• 10.1 Every implementation file has a sibling .md with simple + advanced examples (≥ 200 words).
• 10.2 Root README.md covers install, quick usage (vitest config, basic component test), error code index, OTEL toggle.
• 10.3 examples/basic-component.tsx and examples/with-providers.tsx runnable scripts.

11. Pre-publish gate

• 11.1 bunx turbo lint typecheck test --filter=@suaveplan/testing-dom green.
• 11.2 bunx turbo test:coverage --filter=@suaveplan/testing-dom ≥ 95% on every dimension.
• 11.3 openspec validate enterprise-testing-dom --type change passes.

12. Publish (USER APPROVAL REQUIRED)

• 12.1 Surface the audit (test count, coverage, lint clean) and STOP.
• 12.2 On approval: bun scripts/publish.ts --package @suaveplan/testing-dom.
• 12.3 Archive change to openspec/archive/<yyyy-mm-dd>-enterprise-testing-dom/.