suaveplan/openspec/specs/testing-dom/spec.md

testing-dom

Purpose

The @suaveplan/testing-dom package provides DOM- and React-side test helpers with dual-runner support for Vitest and bun:test. It ships a createTestConfig() factory tuned for WSL2 (forks pool, polyfills, optional @vitejs/plugin-react), a renderComponent wrapper around @testing-library/react with auto-cleanup and userEvent integration, side-effect polyfills for crypto/TextEncoder/TextDecoder, and ambient-typed @testing-library/jest-dom matcher extensions. The package is a Layer 0 dependency: its dependencies and peerDependencies MUST NOT contain any @suaveplan/* workspace package, and structured errors flow through TestingDomError with stable TESTING_DOM.<DOMAIN>.<REASON> codes.

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)

Verified by: tests/dep-graph.test.ts::"no @suaveplan/* in dependencies or peerDependencies" AND tests/dep-graph.test.ts::"devDependencies may contain @suaveplan/testing only (utilities for our own tests)"

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

Verified by: tests/exports-map.spec-conformance.test.ts::"routes vitest + default to the index barrel" AND tests/exports-map.spec-conformance.test.ts::"routes the bun condition to the bun-test barrel" AND tests/exports-map.spec-conformance.test.ts::"vitest and default conditions share the same types entry" AND tests/exports-map.spec-conformance.test.ts::"bun condition has its own types entry" AND src/runner/mocks.test.ts::"creates a mock that records calls"

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

Verified by: src/config/config.test.ts::"returns a vitest config by default" AND src/config/config.test.ts::"forces pool=forks and includes polyfill setupFile" AND src/config/config.test.ts::"disables fileParallelism for happy-dom by default" AND src/config/config.test.ts::"returns a BunTestConfig when runner=bun:test" AND src/config/config.test.ts::"throws CONFIG_UNKNOWN_RUNNER for an unknown runner"

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)

Verified by: tests/tree-shake.test.ts::"polyfills subpath has no functional surface" AND tests/exports-map.spec-conformance.test.ts::"polyfills + matchers resolve to side-effecting dist files"

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

Verified by: src/render/render-component.test.tsx::"renders simple JSX and exposes user" AND src/render/render-component.test.tsx::"dispatches a click via the returned user" AND src/render/render-component.test.tsx::"throws RenderError with cause when render explodes"

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

Verified by: src/matchers/matchers.test.tsx::"toBeInTheDocument" AND src/matchers/matchers.test.tsx::"toHaveTextContent" AND src/matchers/matchers.test.tsx::"toBeDisabled / toBeEnabled" AND src/matchers/matchers.test.tsx::"toHaveAttribute" AND src/matchers/matchers.test.tsx::"toHaveClass"

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

Verified by: src/errors/testing-dom-error.test.ts::"stores code, message, cause, context" AND src/errors/testing-dom-error.test.ts::"each preserves instanceof TestingDomError" AND src/errors/testing-dom-error.test.ts::"every value matches the pattern"

Requirement: Coverage and docs gates

Istanbul statement + branch + function + line coverage across packages/testing/testing-dom/src/ (excluding *.bench.ts, *.schemas.ts, runner/bun-test.ts) MUST be 100% 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 = 100%

Verified by: CI gate (bunx turbo test:coverage --filter=@suaveplan/testing-dom exits non-zero on regression) — current run reports 100/100/100/100

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/

Verified by: tests/no-disallowed.test.ts::"src/ contains no disallowed constructs" AND directory layout audit (tests/ contains dep-graph, tree-shake, exports-map, no-disallowed; src/ contains per-feature *.test.ts(x))

Requirement: Runner-neutral RunnerMock<TArgs, TReturn> type alias

The package SHALL export a RunnerMock<TArgs extends unknown[], TReturn> type alias from both runner-conditional barrels (./runner/vitest.js and ./runner/bun-test.js) AND from the package barrel (./index.js). Both runner paths SHALL implement fn<TArgs, TReturn>(impl?) returning RunnerMock<TArgs, TReturn> so consumer code typed as const m = fn<[string], number>() resolves to a callable (arg: string) => number regardless of which runner is active.

Scenario: vitest path preserves call-signature typing

• WHEN a consumer running under vitest declares const m = fn<[string], number>()
• THEN m("hello") type-checks AND ReturnType<typeof m> equals number

Scenario: bun-test path mirrors the vitest typing surface

• WHEN the same declaration runs under the bun conditional export
• THEN the imported fn returns a RunnerMock<TArgs, TReturn> carrying the same call signature

Scenario: SpyHandle type alias re-exported

• WHEN a consumer imports SpyHandle from @suaveplan/testing-dom
• THEN the type matches ReturnType<typeof spy> on the active runner path

Verified by: src/runner/runner.spec-conformance.test.ts::"fn<[string], number>() preserves call-signature typing" AND src/runner/runner.spec-conformance.test.ts::"fn<[number, number], number>(impl) preserves call-signature typing" AND src/runner/runner.spec-conformance.test.ts::"BunRunnerMock<TArgs, TReturn> shape mirrors the vitest path" AND src/runner/runner.spec-conformance.test.ts::"BunSpyHandle is exported and PkgRunnerMock matches both paths" AND src/runner/runner.spec-conformance.test.ts::"spy returns a SpyHandle assignable to the package's exported type" AND src/runner/runner.spec-conformance.test.ts::"stub returns a SpyHandle assignable to the package's exported type"

Requirement: jest-dom matchers ship ambient type augmentation

The @suaveplan/testing-dom/matchers side-effect import SHALL bring the @testing-library/jest-dom ambient module declaration (via the @testing-library/jest-dom/vitest subpath) into the consumer's compilation unit, so expect(el).toBeInTheDocument() and the other common jest-dom matchers type-check without the consumer adding @testing-library/jest-dom to their own tsconfig.json#compilerOptions.types.

Scenario: matcher names are typed as functions

• WHEN a test file does import "@suaveplan/testing-dom/matchers" and writes expect(node).toBeInTheDocument
• THEN the expression has type () => void (a callable matcher) under tsc --noEmit

Verified by: src/matchers/matchers.spec-conformance.test.tsx::"expect(element).toBeInTheDocument is typed as a function" AND src/matchers/matchers.spec-conformance.test.tsx::"every common matcher is typed as a function on expect(...)"

Requirement: setupUser resolves vi through the runner adapter

src/user/setup-user.ts SHALL import vi from the runner adapter (./runner/index.js) rather than directly from vitest. This preserves the dual-runner contract: when the bun conditional export is active, the runner adapter resolves to the bun-test path's vi alias backed by bun:test's jest namespace.

Scenario: source-level guard against vitest hard-import

• WHEN src/user/setup-user.ts is read
• THEN the file contains no from "vitest" import AND it imports from ../runner/index.js

Verified by: src/user/setup-user.test.ts::"imports vi via the runner adapter (no direct vitest hard-import)"

Requirement: instrumented() ends spans only after async fns settle

instrumented(name, fn) SHALL detect when the wrapped function returns a PromiseLike value and SHALL defer span.end() and the duration histogram record until the returned promise settles. On rejection, the span SHALL recordException (wrapping non-Error rejections in new Error(String(reason))) before ending. On resolution, the duration recorded SHALL reflect the wall-clock interval between invocation and settlement.

Scenario: async resolve

• WHEN the wrapped fn awaits ≥10ms before returning
• THEN the awaited result equals the inner return value AND the elapsed wall-clock time is ≥10ms (proving the wrapper did not synchronously close the span)

Scenario: async reject

• WHEN the wrapped async fn throws an Error
• THEN the returned promise rejects with the same error (no swallowing)

Scenario: async reject with non-Error reason

• WHEN the wrapped async fn rejects with a string
• THEN the returned promise rejects with the same string AND recordException is invoked with a wrapped Error

Verified by: src/observability/instrumented.test.ts::"ends span only after async fn settles (resolved)" AND src/observability/instrumented.test.ts::"ends span only after async fn settles (rejected)" AND src/observability/instrumented.test.ts::"ends span only after async fn settles (rejected with non-Error)"