testing-library/react-testing-library
github.com/testing-library/react-testing-library ↗ · 65 files · 383 KB
React Testing Library Simple and complete React DOM testing utilities that encourage good testing practices.
Overview
React Testing Library is a developer testing library that renders React components into a DOM and exposes queries and interaction helpers shaped around observable user behavior. At commit 20ce75f2907ca0e5c5a8ae595c0e9a4e368c7800, its small JavaScript runtime adapts React 18/19 roots, act scheduling, hydration, hook rendering, and cleanup while delegating DOM queries to @testing-library/dom. It ships npm entrypoints and handwritten TypeScript declarations; this brief is based on read-only inspection of runtime files, tests, documentation, configuration, and workflows.
System map
The runtime is a library loaded into a consumer's test process and DOM environment. React owns rendering, DOM Testing Library owns query machinery, and this repository supplies lifecycle and scheduling adapters. Distribution and release are described by package scripts and GitHub workflows.
- The package advertises dist/index.js as main, an ESM bundle as module, types/index.d.ts as declarations, and Node >=18.
- src/index.js adds runner lifecycle hooks and then re-exports src/pure.js; the published pure.js shim instead requires dist/pure.
- src/pure.js is the orchestration module: it imports React, both ReactDOM APIs, DOM query utilities, act compatibility, event adaptation, and configuration.
- Root adapters provide a common hydrate/render/unmount interface over ReactDOMClient and legacy ReactDOM methods.
- Lifecycle storage consists of module-local mountedContainers and mountedRootEntries; cleanup clears both after unmounting.
- React and ReactDOM 18 or 19 and DOM Testing Library 10 are peer integrations; @babel/runtime is the declared production dependency.
- Build runs three parallel kcd-scripts targets; test, lint, validate, and typecheck are package scripts, with typecheck invoking tsc against the root config.
- Release builds npm artifacts after validation and invokes semantic-release 25 only for pushes in the upstream repository; the package includes dist, shims, and declaration files.
Feature catalog
The user-facing surface is an API for test authors. It supports rendering, updating, hydration, hooks, interactions, diagnostics, and test isolation. DOM Testing Library exports broaden that surface without duplicating query implementations here.
- render accepts React UI and returns container, baseElement, bound queries, debug, rerender, unmount, and asFragment.
- Custom container and baseElement options control mounting and query scope; without either, render creates a div under document.body.
- hydrate attaches React to existing markup, while legacyRoot selects older rendering APIs only when ReactDOM.render exists.
- wrapper supplies a surrounding component, and reactStrictMode can be configured globally or overridden per render.
- renderHook exposes a stable result ref, rerender, and unmount, with initialProps passed to the hook callback.
- fireEvent forwards DOM event helpers and adds React-specific enter/leave, selection, and focus/blur event sequences; act is also publicly exported.
- Consumers receive DOM Testing Library exports, including screen and asynchronous query utilities used in the integration tests.
- cleanup is public and normally registered automatically; consumers can choose the pure entrypoint or load dont-cleanup-after-each.js to control teardown themselves.
Data flow
React nodes and render options enter the root orchestration layer, then become DOM content and query-bound results. Configuration and scheduling state are shared within the loaded modules and test global. Hook output and snapshots are transient outputs rather than durable persistence.
- render rejects a supplied onUncaughtError and unsupported legacyRoot before defaulting baseElement or allocating a container.
- A new container selects a root factory and records the root in both tracking structures; a known container retrieves its existing root by scanning mountedRootEntries.
- UI is first wrapped in the optional wrapper component, then optionally enclosed in StrictMode, before rendering or hydration inside act.
- onCaughtError and onRecoverableError flow into createRoot or hydrateRoot at root creation; they are not supplied anew when an existing root is reused.
- Queries bind to baseElement, whereas asFragment serializes container.innerHTML into a DocumentFragment and debug formats its selected element through prettyDOM.
- configure evaluates functional deltas against merged configuration, forwards non-reactStrictMode fields to DOM Testing Library, and assigns reactStrictMode in RTL's local config.
- renderHook computes pendingResult during TestComponent rendering, publishes it to result.current in useEffect, and passes new rerender arguments as renderCallbackProps.
- cleanup unmounts roots inside act, removes only containers directly under document.body, and clears in-memory tracking; custom parent elements remain outside that removal boundary.
Behavior traces
The inspected flows cover import setup, component lifecycle, hydration, events, async queries, and hooks. Each trace follows runtime functions and relevant test usage rather than assuming behavior from filenames. These walks were read from source and were not executed.
- Startup: pure-module evaluation installs DOM timer/async/event wrappers; index.js then checks RTL_SKIP_AUTO_CLEANUP, registers afterEach or teardown, and registers beforeAll/afterAll act-environment management when both hooks exist.
- Initial render: render validates options → defaults to document.body → appends a div → createConcurrentRoot calls createRoot → tracking is populated → renderRoot calls root.render inside act → query helpers are returned.
- Update and teardown: result.rerender calls renderRoot with the captured root, wrapper, and scope; result.unmount calls root.unmount in act; cleanup later walks registered roots and clears their tracking.
- Hydration: render with hydrate:true creates a concurrent root through act(hydrateRoot); renderRoot subsequently calls the adapter's no-op hydrate, and rerender later uses root.render. The hydration test then clicks the existing button and asserts updated text.
- Interaction: fireEvent.click forwards to the DOM helper; the configured eventWrapper runs its callback inside act, but nested wrapper invocations execute directly. The nesting regression dispatches input from an effect and checks both updates and act warnings.
- Async query: a fixture effect schedules a promise or timer update → the test awaits waitFor/findBy → asyncWrapper disables the act flag, awaits its callback, drains microtasks via setTimeout(0), advances detected Jest fake timers, and restores the prior flag in finally.
- Hook flow: renderHook extracts initialProps → render mounts TestComponent → renderCallback computes output → useEffect writes result.current → returned rerender calls baseRerender with new props, while unmount is inherited from render.
- Explicit act: withGlobalActEnvironment saves the prior flag and enables it; synchronous callbacks restore immediately, object thenables restore on resolution/rejection, and synchronous exceptions restore before rethrow.
Testing signals
Tests and CI were inspected, not executed; no passing result or measured coverage is asserted. Jest suites in src/__tests__ exercise DOM behavior, scheduling, cleanup, hooks, and React-version branches, while types/test.tsx supplies declaration checks. The inspected inventory is bounded, and several tests or configuration branches explicitly limit what can be concluded.
- Jest configuration extends kcd-scripts/config, and tests/setup-env.js installs jest-dom assertions, console-call enforcement, TextEncoder, and a worker_threads MessageChannel.
- Rendering tests assert portals, fragment snapshots, wrapper composition, StrictMode effects, repeated-container rendering, hydration interactivity, and version-gated legacy behavior.
- Cleanup suites test automatic cleanup and its skip switch, effect teardown, detached containers, non-flushing of microtasks, and preservation of missing-act warnings.
- Event tests generate React-handler and native-listener cases from an event table; a separate regression asserts nested eventWrapper behavior and absence of act warnings.
- Async integration tests exercise waitForElementToBeRemoved, waitFor, and findBy across real, legacy fake, and modern fake timers, including long promise chains; their loaders simulate data rather than contacting a server.
- Hook tests assert committed output, rerender props, providers, and version-gated legacy roots; renderHook's recoverable-error test accepts the option but contains a TODO instead of triggering recovery.
- types/test.tsx checks render/query/config/hook usage and container inference; root typecheck includes types with strict and exactOptionalPropertyTypes enabled, but onCaughtError's cross-version fixture uses @ts-ignore.
- PR CI spans Node 18/24 and React 18.x/latest/canary/experimental, permits non-latest failures, and uploads coverage. Jest relaxes per-job core thresholds while Codecov specifies a 100% project target for selected flags.
Risk map
The main source-observed risks concern shared state, lifecycle boundaries, compatibility, and validation strength. Security-sensitive authority appears in release automation; the inspected core runtime operates on the test DOM and callbacks rather than implementing authentication or transport. These observations and labeled hypotheses are not confirmed vulnerabilities or whole-repository absence claims.
- Even the pure implementation changes shared DOM Testing Library configuration at import time and writes IS_REACT_ACT_ENVIRONMENT during operations; selecting pure only avoids index.js lifecycle registration.
- RTL_SKIP_AUTO_CLEANUP is tested by truthiness rather than equality with 'true', and the same guard disables both cleanup registration and suite-level act-environment hooks.
- configure assigns reactStrictMode even when a delta omits it, replacing the previous value with undefined; the inspected config suite does not assert retention after a DOM-only delta.
- The Set and array must remain synchronized; result.unmount does not deregister its root, and a later render on that container selects the stored root. This is a lifecycle hotspot, not a demonstrated failure in this inspection.
- Async scheduling depends on Jest-specific timer markers and a zero-delay timer to drain microtasks; global flag restoration for asynchronous act is tied to consuming its returned thenable.
- debug sends formatted DOM to console.log, while asFragment reparses container.innerHTML without a sanitization step. Hypothesis: sensitive fixture content can enter logs or snapshots; these helpers are not a content-security boundary. (inferred)
- README authentication and localStorage code is an example application, while inspected async test loaders return synthetic promises. Treating those as shipped authentication, persistence, or real-network coverage would misstate the library boundary.
- Release automation grants OIDC and repository write permissions, consumes workflow secret references, and installs without a lockfile; non-latest React validation jobs allow failure. These are consequential release boundaries, with no credential values read or exploit established.
Extension points
Consumer extension primarily happens through render options and configuration rather than a plugin registry. The root adapters and event forwarding also provide internal seams for compatibility work. Public additions need coordinated runtime exports, declarations, and behavioral tests.
- RenderOptions.queries accepts a custom query set, and renderRoot binds it through getQueriesForElement; custom sets replace defaults unless the caller merges them.
- RenderResult maps each supplied query key to BoundFunction, preserving custom-query typing through the generic render overload.
- wrapper is the documented seam for reusable render helpers that install providers; renderHook passes it through the same render pipeline.
- configure accepts object or functional deltas and forwards DOM options, supporting changes such as testIdAttribute alongside RTL strict mode.
- createConcurrentRoot and createLegacyRoot are internal factories with the same lifecycle methods; render chooses between them via legacyRoot.
- fireEvent copies every enumerable DOM helper at module load, then overrides selected helpers; new React event adaptations belong beside those explicit sequences.
- onCaughtError and onRecoverableError are root-creation callback seams, with onCaughtError typed conditionally against installed ReactDOM RootOptions; onUncaughtError is deliberately excluded.
- The pure import lets alternative runners own cleanup scheduling while retaining the public API; its declaration forwarding chain ends at the same types/index.d.ts surface.
Contributor handoff
Begin edits at the runtime/type boundary and read the focused behavioral suite before changing contracts. Existing scripts and workflow definitions describe intended validation, but tests and CI were inspected, not executed during this assignment. The investigation is bounded and supplies neither passing results nor exhaustive security or coverage conclusions.
- For lifecycle work, first read index.js, pure.js, and act-compat.js together: runner registration, root ownership, and React's global act flag cross module boundaries.
- Keep public API edits paired with types/index.d.ts and types/test.tsx; CONTRIBUTING identifies handwritten declarations as the API update location.
- For an authorized implementation, start with the relevant src/__tests__ suite through npm test, then use typecheck or validate as needed; those commands were only inspected here.
- Preserve React 18/19 branches and version-gated assertions; a successful latest-only run would not establish legacy-root compatibility.
- Tests changing global configuration capture and restore it; tests mocking console must respect the harness's unexpected-call and teardown checks.
- Use actual scripts as authority over older documentation: CONTRIBUTING mentions dtslint, while package.json's explicit typecheck invokes tsc and the root config includes types without emitting output.
- Inspect package-manager context before installing: package.json declares Yarn 1.22.22, while contribution setup and CI use npm, and CI explicitly disables lockfile use.
- Treat release automation as a separate authority boundary: configured branch pushes can trigger publication, and maintainer documentation warns that BREAKING CHANGE commit text drives major releases.
Languages
| Language | Files | Share of source |
|---|---|---|
| JavaScript | 31 | 89% |
| Markdown | 12 | docs/config |
| JSON | 4 | docs/config |
| TypeScript | 4 | 11% |
| YAML | 3 | docs/config |
Start reading here
Probable source entrypoint: src/index.js — inferred from the directory tree and manifest, not the upstream docs.
Source roots
src/ (23 files)
Source layout — src/
| Path | Files |
|---|---|
src/__mocks__/ | 1 |
src/__tests__/ | 17 |
src/act-compat.js | 1 |
src/config.js | 1 |
src/fire-event.js | 1 |
src/index.js | 1 |
src/pure.js | 1 |
Repository structure
| Top-level path | Files |
|---|---|
src/ | 23 |
.github/ | 7 |
other/ | 5 |
types/ | 4 |
tests/ | 4 |
.codesandbox/ | 1 |
Docs found: CONTRIBUTING.mdREADME.md
Package
package.json — @testing-library/react v0.0.0-semantically-released, 14 declared dependencies.
@babel/runtime@testing-library/dom@testing-library/jest-dom@types/react@types/react-domchalkdotenv-clijest-diffkcd-scriptsnpm-run-all2reactreact-dom
CI & config entrypoints
README.md— Repository readme.github/workflows/release.yml— GitHub Actions workflow.github/workflows/validate.yml— GitHub Actions workflowpackage.json— npm scripts: build, build:bundle:main, build:bundle:pure, build:main, format, install:csb, lint, prebuild
Structural health signals
Average score 8.9/10 across 31 analyzed source files; 0 hotspots surfaced.
src/__tests__/render.js— 299 lines, score 6.7 (Deep nesting, Long function/block)src/__tests__/end-to-end.js— 234 lines, score 6.9 (Deep nesting, High churn)src/__tests__/events.js— 256 lines, score 7.4 (Deep nesting, High churn)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
20ce75f2907c2026-08-28 — fix: Avoid act() re-entrant when dispatching events (#1468)be9d81d913142026-04-02 — docs: fix typos in comments and types (#1446)f32bd1b033d52026-01-19 — fix: Update 'onCaughtError' type inference in 'RenderOptions' to work with React v19 (#1438)a2d37ffa09d82025-12-15 — fix: Switch to trusted publishing (#1437)cd6a175a28062025-12-13 — chore: fix action permissions (#1436)