@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

20 KiB Raw Blame History