skills/docs/testkit/testing/testing-dom

@suaveplan/testing-dom - DOM/React testing — vitest+bun-test conditional re-exports, createTestConfig, polyfills, render helpers, accessibility-first queries, jest-dom matchers, user-event v14

Summary

DOM and React component testing utilities for Suaveplan. Provides a single install that covers vitest config generation with WSL2-safe defaults, @testing-library/react render helpers, accessibility-first query aliases, @testing-library/jest-dom matchers, user-event v14 setup, and a dual-runner shim that routes between vitest and bun:test via package.json conditional exports.

Documentation tree

• config — (no submodules) - detect-environment — detectEnvironment probes the…
  • bun-test-config — createBunTestConfig produces a minimal bun test configuration object with the same polyfill preload and environment…
  • config — (no submodules) - detect-environment — detectEnvironment probes the…
  • detect-environment — detectEnvironment probes the current runtime and returns the most-specific test environment available: "happy-dom"…
  • detect-runner — detectRunner tells the caller whether the currently-executing process is vitest or bun-test. It's used by the runner-…
  • vitest-config — createVitestConfig builds a ready-to-use vitest test block with WSL2-safe defaults and the package's polyfills preloa…
• codes — TESTING_DOM_CODES is the package-local error code registry for @suaveplan/testing-dom. All codes share the `TESTING…
• testing-dom-error — TestingDomError is the single concrete error class thrown by @suaveplan/testing-dom. It intentionally does NOT exte…
• matchers — (no submodules)
  • matchers — (no submodules)
• observability — (no submodules)
  • instrumented — (no submodules)
• queries — (no submodules)
  • queries — (no submodules)
• render — (no submodules)
  • render-component — (no submodules)
• runner — (no submodules) - vitest — The runner/vitest module re-exports vite…
  • bun-test — The runner/bun-test module re-exports bun-test's primitives (describe, it, test, expect, beforeAll, `before…
  • mocks — The runner/mocks module offers a small set of dependency-injection friendly mock helpers that work identically under…
  • runner — (no submodules) - vitest — The runner/vitest module re-exports vite…
  • vitest — The runner/vitest module re-exports vitest's describe, it, test, expect, beforeAll, beforeEach, `afterAll…
• setup — (no submodules)
  • polyfills — (no submodules)
• user — (no submodules)
  • setup-user — (no submodules)

- detect-environment — `detectEnvironment` probes the…

• bun-test-config — createBunTestConfig produces a minimal bun test configuration object with the same polyfill preload and environment…

• config — (no submodules)- detect-environment — detectEnvironment probes the…

• detect-environment — detectEnvironment probes the current runtime and returns the most-specific test environment available: "happy-dom"…

• detect-runner — detectRunner tells the caller whether the currently-executing process is vitest or bun-test. It's used by the runner-…

• vitest-config — createVitestConfig builds a ready-to-use vitest test block with WSL2-safe defaults and the package's polyfills preloa…

• codes — TESTING_DOM_CODES is the package-local error code registry for @suaveplan/testing-dom. All codes share the `TESTING…

• testing-dom-error — TestingDomError is the single concrete error class thrown by @suaveplan/testing-dom. It intentionally does NOT exte…

• matchers — (no submodules)- matchers — (no submodules)- observability — (no submodules)- instrumented — (no submodules)- queries — (no submodules)- queries — (no submodules)- render — (no submodules)- render-component — (no submodules)- runner — (no submodules)- vitest — The runner/vitest module re-exports vite…

  • bun-test — The runner/bun-test module re-exports bun-test's primitives (describe, it, test, expect, beforeAll, `before…
  • mocks — The runner/mocks module offers a small set of dependency-injection friendly mock helpers that work identically under…
  • runner — (no submodules)- vitest — The runner/vitest module re-exports vite…
  • vitest — The runner/vitest module re-exports vitest's describe, it, test, expect, beforeAll, beforeEach, `afterAll…

• setup — (no submodules)- polyfills — (no submodules)- user — (no submodules)- setup-user — (no submodules)- detect-environment — detectEnvironment probes the…

• bun-test-config — createBunTestConfig produces a minimal bun test configuration object with the same polyfill preload and environment…

• config — (no submodules)- detect-environment — detectEnvironment probes the…

• detect-environment — detectEnvironment probes the current runtime and returns the most-specific test environment available: "happy-dom"…

• detect-runner — detectRunner tells the caller whether the currently-executing process is vitest or bun-test. It's used by the runner-…

• vitest-config — createVitestConfig builds a ready-to-use vitest test block with WSL2-safe defaults and the package's polyfills preloa…

• codes — TESTING_DOM_CODES is the package-local error code registry for @suaveplan/testing-dom. All codes share the `TESTING…

• testing-dom-error — TestingDomError is the single concrete error class thrown by @suaveplan/testing-dom. It intentionally does NOT exte…

• matchers — (no submodules)- matchers — (no submodules)- observability — (no submodules)- instrumented — (no submodules)- queries — (no submodules)- queries — (no submodules)- render — (no submodules)- render-component — (no submodules)- runner — (no submodules)- vitest — The runner/vitest module re-exports vite…

  • bun-test — The runner/bun-test module re-exports bun-test's primitives (describe, it, test, expect, beforeAll, `before…
  • mocks — The runner/mocks module offers a small set of dependency-injection friendly mock helpers that work identically under…
  • runner — (no submodules)- vitest — The runner/vitest module re-exports vite…
  • vitest — The runner/vitest module re-exports vitest's describe, it, test, expect, beforeAll, beforeEach, `afterAll…

• setup — (no submodules)- polyfills — (no submodules)- user — (no submodules)- setup-user — (no submodules)- detect-environment — detectEnvironment probes the…

• bun-test-config — createBunTestConfig produces a minimal bun test configuration object with the same polyfill preload and environment…

• config — (no submodules)- detect-environment — detectEnvironment probes the…

• detect-environment — detectEnvironment probes the current runtime and returns the most-specific test environment available: "happy-dom"…

• detect-runner — detectRunner tells the caller whether the currently-executing process is vitest or bun-test. It's used by the runner-…

• vitest-config — createVitestConfig builds a ready-to-use vitest test block with WSL2-safe defaults and the package's polyfills preloa…

• codes — TESTING_DOM_CODES is the package-local error code registry for @suaveplan/testing-dom. All codes share the `TESTING…

• testing-dom-error — TestingDomError is the single concrete error class thrown by @suaveplan/testing-dom. It intentionally does NOT exte…

• matchers — (no submodules)- matchers — (no submodules)- observability — (no submodules)- instrumented — (no submodules)- queries — (no submodules)- queries — (no submodules)- render — (no submodules)- render-component — (no submodules)- runner — (no submodules)- vitest — The runner/vitest module re-exports vite…

  • bun-test — The runner/bun-test module re-exports bun-test's primitives (describe, it, test, expect, beforeAll, `before…
  • mocks — The runner/mocks module offers a small set of dependency-injection friendly mock helpers that work identically under…
  • runner — (no submodules)- vitest — The runner/vitest module re-exports vite…
  • vitest — The runner/vitest module re-exports vitest's describe, it, test, expect, beforeAll, beforeEach, `afterAll…

• setup — (no submodules)- polyfills — (no submodules)- user — (no submodules)- setup-user — (no submodules)- bun-test-config — createBunTestConfig produces a minimal bun test configuration object with the same polyfill preload and environment…

• config — (no submodules)- detect-environment — detectEnvironment probes the current runtime and returns the most-specific test environment available: "happy-dom"…

• detect-runner — detectRunner tells the caller whether the currently-executing process is vitest or bun-test. It's used by the runner-…

• vitest-config — createVitestConfig builds a ready-to-use vitest test block with WSL2-safe defaults and the package's polyfills preloa…

• codes — TESTING_DOM_CODES is the package-local error code registry for @suaveplan/testing-dom. All codes share the `TESTING…

• testing-dom-error — TestingDomError is the single concrete error class thrown by @suaveplan/testing-dom. It intentionally does NOT exte…

• matchers — (no submodules) - matchers — (no submodules)- observability — (no submodules) - instrumented — (no submodules)- queries — (no submodules) - queries — (no submodules)- render — (no submodules) - render-component — (no submodules)- runner — (no submodules) - bun-test — The runner/bun-test module re-exports bun-test's primitives (describe, it, test, expect, beforeAll, `before…

  • mocks — The runner/mocks module offers a small set of dependency-injection friendly mock helpers that work identically under…
  • runner — (no submodules) - vitest — The runner/vitest module re-exports vitest's describe, it, test, expect, beforeAll, beforeEach, `afterAll…

• setup — (no submodules) - polyfills — (no submodules)- user — (no submodules) - setup-user — (no submodules)

Install

bun add @suaveplan/testing-dom

Peer dependencies (install separately if using React rendering):

bun add react react-dom @vitejs/plugin-react

Quick Start

Vitest config

// vitest.config.ts
import { defineConfig } from "vitest/config";
import { createVitestConfig } from "@suaveplan/testing-dom/config";
import { fileURLToPath } from "node:url";

export default defineConfig(
  createVitestConfig(fileURLToPath(new URL(".", import.meta.url)), {
    environment: "happy-dom",
    coverage: true,
  })
);

Rendering a React component

import { renderComponent } from "@suaveplan/testing-dom/render";
import { byRole, findRole } from "@suaveplan/testing-dom/queries";
import "@suaveplan/testing-dom/matchers"; // extends expect with jest-dom matchers

it("submits the form", async () => {
  const { user } = renderComponent(<MyForm onSubmit={handleSubmit} />);

  await user.click(byRole("button", { name: /submit/i }));

  const status = await findRole("status");
  expect(status).toHaveTextContent("Saved");
});

Modules

Subpath	Module	Description
@suaveplan/testing-dom/config	src/config/vitest-config.md	createVitestConfig — builds the vitest test block with WSL2-safe pool: "forks", polyfill setup files, and Istanbul coverage defaults
	src/config/bun-test-config.md	createBunTestConfig — equivalent config builder for bun test
	src/config/detect-runner.md	detectRunner — infers the active test runner from package.json and environment variables
	src/config/detect-environment.md	detectEnvironment — resolves the vitest test environment (node, happy-dom, jsdom)
	src/config/config.md	createTestConfig — unified entry point that delegates to the correct runner-specific builder
@suaveplan/testing-dom/render	src/render/render-component.md	renderComponent — thin wrapper over @testing-library/react render that auto-cleans between calls and returns an attached user event instance
@suaveplan/testing-dom/queries	src/queries/queries.md	Accessibility-first query aliases (byRole, findRole, queryRole, byLabelText, byText, byPlaceholderText) plus full re-export of screen and within
@suaveplan/testing-dom/user	src/user/setup-user.md	setupUser — produces a @testing-library/user-event v14 instance with happy-dom-safe defaults and automatic fake-timer integration
@suaveplan/testing-dom/matchers	src/matchers/matchers.md	Side-effect import that extends vitest's expect with the full @testing-library/jest-dom matcher set
@suaveplan/testing-dom/polyfills	src/setup/polyfills.md	Setup file that installs web-platform polyfills (TextEncoder, ResizeObserver, etc.) required by happy-dom in Node/Bun
@suaveplan/testing-dom/errors	src/errors/testing-dom-error.md	Typed error classes (RenderError) and error codes for failures surfaced by this package
	src/errors/codes.md	TESTING_DOM_ERROR_CODES registry
(runner shim)	src/runner/vitest.md	Vitest runner re-exports (describe, it, test, expect, vi, beforeEach, …)
	src/runner/bun-test.md	bun:test runner shim with the same surface — activated by the "bun" conditional export
	src/runner/mocks.md	fn, spy, stub, mock, fakeClock, restoreMocks, restoreTimers — runner-agnostic mock helpers
	src/runner/runner.md	Runner abstraction types
(observability)	src/observability/instrumented.md	instrumented — optional OTel wrapper (gated by TESTING_DOM_OTEL_ENABLED=1) that records call counts and duration histograms for package entrypoints