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

ADDED Requirements

Requirement: Layer 0 dep-graph isolation

The @suaveplan/testing-dom dependencies and peerDependencies MUST NOT contain any @suaveplan/* workspace package. devDependencies MAY include @suaveplan/testing (utilities) for the package's own tests, but the production runtime closure MUST NOT contain it.

Scenario: Runtime dep-graph guard

• WHEN bunx turbo ls --filter=@suaveplan/testing-dom... is run (forward closure of runtime deps)
• THEN no @suaveplan/* package appears

Scenario: devDep allowance

• WHEN package.json is parsed
• THEN dependencies and peerDependencies are free of @suaveplan/* AND devDependencies may contain @suaveplan/testing (this dep is not visible to consumers)

Requirement: Dual-runner conditional exports preserved

The package exports["."] SHALL route the vitest condition and the default condition to the vitest barrel and the bun condition to the bun-test barrel. The exports MUST expose describe, it, test, expect, vi, beforeAll, beforeEach, afterAll, afterEach, fn, spy, stub, mock, fakeClock, restoreMocks, restoreTimers under both conditions.

Scenario: Vitest consumer

• WHEN a consumer running under vitest imports { describe, it, expect, vi } from @suaveplan/testing-dom
• THEN the symbols come from vitest

Scenario: bun-test consumer

• WHEN a consumer running under bun test imports the same names
• THEN the symbols come from bun:test

Requirement: createTestConfig() produces WSL2-safe configs

The factory SHALL emit a vitest config with pool: "forks", setupFiles: ["@suaveplan/testing-dom/polyfills"], fileParallelism: false when environment === "happy-dom", and dynamically-loaded @vitejs/plugin-react if that optional peer is installed. When the caller's runner is bun:test, the factory SHALL return a BunTestConfig instead.

Scenario: Happy-dom config

• WHEN createTestConfig({ environment: "happy-dom" }) is awaited and @vitejs/plugin-react is present
• THEN the returned config includes the React plugin, has pool === "forks", fileParallelism === false, and setupFiles includes the polyfills path

Scenario: Missing React peer doesn't break non-React consumers

• WHEN createTestConfig({ environment: "happy-dom" }) is awaited and the React peer is NOT installed
• THEN the factory returns the vitest config without the plugin, no error thrown

Requirement: Polyfills are side-effect-only

The @suaveplan/testing-dom/polyfills subpath MUST resolve to a side-effecting module that installs globalThis.crypto (when missing), globalThis.TextEncoder, and globalThis.TextDecoder. The module MUST export nothing.

Scenario: Idempotent polyfill install

• WHEN import "@suaveplan/testing-dom/polyfills" runs twice in the same process
• THEN the second import is a no-op (no errors, no overwrites)

Requirement: renderComponent wraps React render with cleanup and userEvent

renderComponent(ui, options?) SHALL render the React tree using @testing-library/react's render, auto-register cleanup on afterEach, and return the standard RenderResult extended with a userEvent instance.

Scenario: Render and event dispatch

• WHEN renderComponent(<Button />) is called and the returned userEvent.click(getByRole('button')) is awaited
• THEN the click is dispatched and observable side-effects run

Scenario: Render failure produces RenderError

• WHEN the React tree throws synchronously during render
• THEN renderComponent throws RenderError with code === "TESTING_DOM.RENDER.SETUP_FAILED" and cause set to the original error

Requirement: jest-dom matchers extension

Importing @suaveplan/testing-dom/matchers SHALL extend vitest's expect with the @testing-library/jest-dom matcher set. Common matchers MUST be available afterward: toBeInTheDocument, toHaveTextContent, toBeDisabled, toBeEnabled, toHaveAttribute, toBeVisible, toHaveClass, toHaveValue.

Scenario: Matcher availability after side-effect import

• WHEN a test file does import "@suaveplan/testing-dom/matchers" and then asserts expect(node).toBeInTheDocument()
• THEN the assertion runs without "matcher does not exist" errors

Requirement: Structured errors with stable codes

All errors thrown from @suaveplan/testing-dom MUST be subclasses of TestingDomError extends Error carrying { code, cause?, context? }. Codes match ^TESTING_DOM\.[A-Z]+\.[A-Z_]+$.

Scenario: Coded error

• WHEN any helper throws
• THEN the thrown value instanceof TestingDomError is true AND err.code matches the regex

Requirement: Coverage and docs gates

Istanbul statement + branch coverage across packages/universal/testing-dom/src/ (excluding *.bench.ts, *.schemas.ts, runner/bun-test.ts) MUST be ≥ 95% on every dimension. Every implementation file (*.ts other than test/bench/schemas/types-in-feature-dirs/index barrels) MUST have a sibling .md of ≥ 200 words with simple + advanced examples.

Scenario: CI coverage gate

• WHEN bunx turbo test:coverage --filter=@suaveplan/testing-dom runs
• THEN statement, branch, function, and line coverage all ≥ 95%

Requirement: Test placement follows the genesis hard rule

Per-feature unit tests SHALL be co-located in src/ (named <feature>.test.ts next to <feature>.ts). Cross-cutting tests (dep-graph guard, tree-shake guard, no-disallowed grep guard, property tests) MUST live in tests/ sibling to src/.

Scenario: Per-feature unit tests live next to source

• WHEN a directory under src/ contains a feature module like render/render-component.ts
• THEN its unit tests are at src/render/render-component.test.ts (sibling) AND not in tests/

Scenario: Cross-cutting tests live in tests/

• WHEN a test exercises package-level concerns (dep-graph, tree-shake, no-disallowed grep, property invariants over multiple modules)
• THEN it lives under tests/ AND not in src/