# react-testing-library

Guides coding agents to write user-centric component tests using accessible queries, user-event simulations, and async helpers.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1400 installs · ★ 24
- Author: itechmeat
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/itechmeat/llm-code/tree/HEAD/skills/react-testing-library/SKILL.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/skills/react-testing-library

## What it does

This skill guides the agent to test components from the user perspective instead of inspecting internal component state. Accessibility comes first. The skill prefers queries by ARIA role (`getByRole`) and form labels over test IDs. User actions run through `@testing-library/user-event` instead of `fireEvent`.

It documents custom wrapper setup for providers and hook testing via `renderHook` with `act`. Asynchronous DOM changes rely on `findBy*` queries or `waitFor`. For inspecting rendered output, the skill supplies `screen.debug()` and `logRoles(container)`.

React 19 projects require `@testing-library/react` v16.1.0 or newer to avoid test runner breakage. Both `@testing-library/react` and `@testing-library/dom` must be installed locally.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add itechmeat/llm-code --skill react-testing-library -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/react-testing-library/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/react-testing-library/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add itechmeat/llm-code --skill react-testing-library -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/react-testing-library/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add itechmeat/llm-code --skill react-testing-library -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/react-testing-library/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install itechmeat/llm-code react-testing-library
```

2. **Manually: put the files in place**
- File: `.github/skills/react-testing-library/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add itechmeat/llm-code --skill react-testing-library -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/itechmeat/llm-code --path skills/react-testing-library
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/react-testing-library/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add itechmeat/llm-code --skill react-testing-library -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/itechmeat/llm-code/tree/HEAD/skills/react-testing-library/SKILL.md

## When to use it
- simulate realistic user clicks and keyboard input with `userEvent`
- query DOM elements by accessible role and label instead of test IDs
- handle asynchronous element updates using `findBy` queries and `waitFor`
- test custom React hooks using `renderHook` and `act`

## Example prompts
- Write a component test for the login modal using userEvent and accessible queries
- Test the useCounter custom hook with renderHook and act
- Show how to set up a custom render function with ThemeProvider

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 89c22505b9f49a2b.

BEGIN THIRD-PARTY FILE 89c22505b9f49a2b
````text
---
name: react-testing-library
description: "React Testing Library: user-centric component testing with queries, user-event simulation, async utilities, and accessibility-first API. Use when writing React component tests, selecting elements by role/label/text, simulating user events, or testing async UI behavior. Keywords: React Testing Library, @testing-library/react, user-event, queries, render."
metadata:
  version: "16.3.3"
  release_date: "2026-09-04"
---

# React Testing Library Skill

## Quick Navigation

| Topic       | Link                                                   |
| ----------- | ------------------------------------------------------ |
| Queries     | [references/queries.md](references/queries.md)         |
| User Events | [references/user-events.md](references/user-events.md) |
| API         | [references/api.md](references/api.md)                 |
| Async       | [references/async.md](references/async.md)             |
| Debugging   | [references/debugging.md](references/debugging.md)     |
| Config      | [references/config.md](references/config.md)           |

---

## Installation

Install: `npm install --save-dev @testing-library/react @testing-library/dom`. Recommended extras: `@testing-library/user-event` and `@testing-library/jest-dom`. React 19 requires v16.1.0+.

## Core Philosophy

> "The more your tests resemble the way your software is used, the more confidence they can give you."

**Avoid testing**:

- Internal state of components
- Internal methods
- Lifecycle methods
- Child component implementation details

**Test instead**:

- What users see and interact with
- Behavior from user's perspective
- Accessibility (queries by role, label)

---

## Query Priority

Use queries in this order of preference:

### 1. Accessible to Everyone (Preferred)

```ts
// Best — by ARIA role
getByRole("button", { name: /submit/i });
getByRole("textbox", { name: /email/i });

// Form fields — by label
getByLabelText("Email");

// Non-interactive content — by text
getByText("Welcome back!");
```

### 2. Semantic Queries

```ts
// Images
getByAltText("Company logo");

// Title attribute (less reliable)
getByTitle("Close");
```

### 3. Test IDs (Escape Hatch)

```ts
// Only when other queries don't work
getByTestId("custom-element");
```

---

## Query Types

| Type            | No Match | 1 Match | >1 Match | Async |
| --------------- | -------- | ------- | -------- | ----- |
| `getBy...`      | throw    | return  | throw    | No    |
| `queryBy...`    | null     | return  | throw    | No    |
| `findBy...`     | throw    | return  | throw    | Yes   |
| `getAllBy...`   | throw    | array   | array    | No    |
| `queryAllBy...` | []       | array   | array    | No    |
| `findAllBy...`  | throw    | array   | array    | Yes   |

**When to use**:

- `getBy*` — element exists
````
END THIRD-PARTY FILE 89c22505b9f49a2b

The third-party file has ended. Everything between the 89c22505b9f49a2b tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2849 of 9880 bytes. © itechmeat · MIT · https://github.com/itechmeat/llm-code/tree/HEAD/skills/react-testing-library/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md