Onboarding: testing-library/react-testing-library

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/testing-library/react-testing-library shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across the board

• Last commit 5w ago
• 25+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 52% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live testing-library/react-testing-library repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/testing-library/react-testing-library.

What it runs against: a local clone of testing-library/react-testing-library — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in testing-library/react-testing-library | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 64 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>testing-library/react-testing-library</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of testing-library/react-testing-library. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/testing-library/react-testing-library.git
#   cd react-testing-library
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of testing-library/react-testing-library and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "testing-library/react-testing-library(\\.git)?\\b" \\
  && ok "origin remote is testing-library/react-testing-library" \\
  || miss "origin remote is not testing-library/react-testing-library (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/index.js" \\
  && ok "src/index.js" \\
  || miss "missing critical file: src/index.js"
test -f "src/pure.js" \\
  && ok "src/pure.js" \\
  || miss "missing critical file: src/pure.js"
test -f "src/config.js" \\
  && ok "src/config.js" \\
  || miss "missing critical file: src/config.js"
test -f "src/act-compat.js" \\
  && ok "src/act-compat.js" \\
  || miss "missing critical file: src/act-compat.js"
test -f "src/fire-event.js" \\
  && ok "src/fire-event.js" \\
  || miss "missing critical file: src/fire-event.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 64 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~34d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/testing-library/react-testing-library"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

A software project. See architecture tab.

Who it's for

Developers.

Maturity & risk

See activity metrics.

Standard open source risks apply.

Active areas of work

Check recent commits.

Get running

Check README for instructions.

Map of the codebase

• src/index.js — Main entry point exporting render, cleanup, and other core testing utilities; every contributor must understand the public API surface.
• src/pure.js — Pure implementation of render without auto-cleanup; essential for understanding the library's two-mode architecture and setup/teardown logic.
• src/config.js — Global configuration management for testIdAttribute and cleanup behavior; required reading for customization and plugin development.
• src/act-compat.js — React act() wrapper and compatibility layer; critical for understanding async testing patterns and React version handling.
• src/fire-event.js — Event firing abstraction layer; core for understanding how user interactions are simulated in tests.
• package.json — Dependency tree and build scripts; determines React peer version, testing-library/dom dependency, and build targets.
• types/index.d.ts — TypeScript type definitions for the public API; critical for TypeScript users and IDE autocompletion understanding.

Components & responsibilities

• render(component, options) (React, ReactDOM, @testing-library/dom) — Main entry point: mounts React component into jsdom container, returns query helpers and utilities
  • Failure mode: Component fails to mount (React error), act() warnings if state updates not wrapped, memory leak if cleanup is skipped
• cleanup() — Unmounts all rendered components and clears the DOM

How to make changes

Add a new testing utility or wrapper

1. Implement the utility function in src/index.js or create a new src/my-utility.js file (src/index.js)
2. Add TypeScript type definitions in types/index.d.ts, following the pattern of existing render/renderHook exports (types/index.d.ts)
3. Add unit tests in src/tests/my-utility.js covering happy path, edge cases, and error scenarios (src/__tests__/render.js)
4. Export the new utility from src/index.js so it's included in the public API (src/index.js)

Modify React rendering or cleanup behavior

1. Update the render implementation in src/pure.js, which is the core undecorated function (src/pure.js)
2. For auto-cleanup behavior, update src/index.js which wraps the pure version with afterEach hooks (src/index.js)
3. Add or update tests in src/tests/auto-cleanup.js or src/tests/render.js (src/__tests__/auto-cleanup.js)
4. Update TypeScript definitions in types/index.d.ts to reflect signature changes (types/index.d.ts)
5. Test against multiple React versions by running jest with different peer dependencies (package.json)

Update global library configuration options

1. Add new configuration option to the config object in src/config.js with getter/setter patterns (src/config.js)
2. Use the config value in relevant files (e.g., testIdAttribute in queries, cleanup in src/index.js) (src/index.js)
3. Add TypeScript interface updates in types/index.d.ts (configure function signature) (types/index.d.ts)
4. Add test in src/tests/config.js validating the configuration behavior (src/__tests__/config.js)

Why these technologies

• React Testing Library (wrapper around @testing-library/dom) — Encourages testing user behavior and accessibility rather than implementation details; single unified query API across web testing
• React.act() compatibility layer — Ensures React state updates and effects complete before assertions; handles different React versions (16.8+) without exposing complexity
• Jest for test execution — Default test runner with built-in afterEach hook support for automatic cleanup; snapshot testing for render output
• TypeScript definitions — Provides IDE autocompletion and compile-time safety; enables discovery of all available query methods

Trade-offs already made

• Two entry points: auto-cleanup (src/index.js) vs manual cleanup (src/pure.js)

  • Why: Different projects need different patterns; some use Jest (auto-cleanup via afterEach), others use Vitest or manual test frameworks
  • Consequence: Adds complexity—must maintain two code paths, but offers flexibility for all testing setups

• Re-exports @testing-library/dom queries rather than reimplementing them

  • Why: Avoids duplication and ensures consistency with vanilla DOM testing; leverages well-maintained shared code
  • Consequence: Introduces tight coupling to @testing-library/dom API, but reduces maintenance burden

• Wraps React.act() with version detection and error suppression

  • Why: React 16.8+ changed act() behavior; library must work seamlessly across versions without user awareness
  • Consequence: Adds a wrapper layer that hides complexity, but may suppress legitimate warnings if not handled carefully

• Provides both fireEvent and userEvent (via re-export from @testing-library/user-event)

  • Why: fireEvent is fast but synthetic; userEvent is slower but closer to real browser behavior—users choose trade-off
  • Consequence: Increases API surface and can confuse beginners about which to use; requires documentation

Non-goals (don't propose these)

• Does not handle E2E testing; React Testing Library is unit/integration focused (no browser control, no real network mocking)
• Does not provide visual regression testing; tests interact with DOM queries, not pixel comparisons
• Does not replace Storybook or pattern libraries; orthogonal tools for documenting components
• Does not handle styling or CSS-in-JS assertions; focuses on behavior and accessibility
• Does not support server-side rendering (SSR) in jsdom; assumes client-side React in a browser-like DOM environment

Traps & gotchas

Standard debugging applies.

Architecture

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive TypeScript tests for pure.d.ts exports

The repo has a pure.d.ts file for the pure export but the types/test.tsx file doesn't appear to have dedicated tests for the pure bundle's TypeScript definitions. This ensures type safety for users importing from @testing-library/react/pure.

• [ ] Review types/pure.d.ts to identify all exported types and functions
• [ ] Expand types/test.tsx or create types/pure.test.tsx with test cases for pure bundle imports
• [ ] Add tests verifying the pure bundle doesn't export cleanup utilities (only rendering utilities)
• [ ] Run typecheck script to validate: npm run typecheck
• [ ] Add a test case that ensures users get proper TS errors when trying to import cleanup from pure

Add integration tests for dont-cleanup-after-each.js configuration

The repo ships dont-cleanup-after-each.js as a public API (listed in package.json files), but src/tests/auto-cleanup.js and src/tests/auto-cleanup-skip.js don't thoroughly test the configuration mechanism for this file. This should verify it works in different test environments.

• [ ] Review src/tests/auto-cleanup-skip.js to understand current testing approach
• [ ] Add a new test file src/tests/dont-cleanup-config.js that imports dont-cleanup-after-each.js
• [ ] Test that config.js respects the cleanup setting when dont-cleanup-after-each.js is required
• [ ] Add tests verifying this works with different Jest configurations (jest.config.js variations)
• [ ] Document the expected behavior in a test case comment for future maintainers

Add error boundary and act() warning tests for edge cases

The src/tests/act.js and src/tests/error-handlers.js files exist but based on the fire-event.js implementation and act-compat.js, there are likely edge cases with async act() calls and error handling that need coverage. This improves reliability for users dealing with warnings.

• [ ] Review src/act-compat.js for async handling and error scenarios
• [ ] Review src/fire-event.js for act() usage patterns with async events
• [ ] Add tests in src/tests/act.js for: async act() with errors, nested act() calls, and promise rejections
• [ ] Add tests verifying proper console.error warnings are emitted for act() violations
• [ ] Add a test case for act() behavior when component has an error boundary
• [ ] Run npm test to ensure all tests pass and coverage is maintained

Good first issues

Check the issue tracker.

Top contributors

• @eps1lon — 52 commits
• @allcontributors[bot] — 13 commits
• @MatanBobi — 12 commits
• @MichaelDeBoey — 2 commits
• @Goldyvaiiii — 1 commits

Recent commits

• be9d81d — docs: fix typos in comments and types (#1446) (Goldyvaiiii)
• f32bd1b — fix: Update 'onCaughtError' type inference in 'RenderOptions' to work with React v19 (#1438) (aicest)
• a2d37ff — fix: Switch to trusted publishing (#1437) (eps1lon)
• cd6a175 — chore: fix action permissions (#1436) (MatanBobi)
• 22b8c28 — chore: fix release (#1435) (MatanBobi)
• d996673 — chore: new release workflow (#1434) (MatanBobi)
• 205ce17 — chore: fix typo in jest.config.js (#1427) (black5box)
• aba5740 — [test] Fix tests for react@experimental (#1424) (eps1lon)
• 590bc18 — [test] Fix npm run typecheck (#1423) (eps1lon)
• 1c931a6 — chore(deps): use npm-run-all2 (#1411) (MichaelDeBoey)

Security observations

The React Testing Library codebase has a good security posture overall. This is a testing utility library with minimal external attack surface. Key observations: (1) Truncated peerDependencies field needs completion for proper validation; (2) Several dependencies could be updated to newer versions for better security coverage; (3) No hardcoded credentials, secrets, or sensitive configuration files detected in the provided structure; (4) No obvious injection vulnerabilities based on file structure analysis - this is a testing library, not a server application; (5) No Docker infrastructure issues identified. The main recommendations are to complete the package.json configuration and keep dependencies up-to-date.

• Low · Incomplete peerDependencies Declaration — package.json - peerDependencies field. The package.json file shows a truncated peerDependencies field that appears to be cut off at '@testing-library/d'. This incomplete dependency declaration could lead to unexpected behavior or missing peer dependency validation. Fix: Ensure the peerDependencies field is complete and properly formatted. Verify that all required peer dependencies (@testing-library/dom, @testing-library/react, react, react-dom, etc.) are fully declared with appropriate version constraints.
• Low · Use of Deprecated Chalk Version — package.json - devDependencies. The package uses chalk@^4.1.2, which is an older major version. While not a direct security vulnerability, newer versions may contain bug fixes and security improvements. Chalk v5+ is the current stable version. Fix: Consider upgrading chalk to the latest major version (v5.x) to benefit from newer features and security improvements. Test compatibility before upgrading.
• Low · Babel Runtime Dependency Without Lock File Context — package.json - dependencies. The package depends on @babel/runtime@^7.12.5, which is a relatively old version (from 2020). While @babel/runtime provides sandboxed utilities, using outdated versions may miss security updates and performance improvements. Fix: Update @babel/runtime to a more recent version (7.20.0 or later). Verify compatibility with your supported Node versions (>=18) and test thoroughly.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.