|
---
|
||
|
|
title: 'React Testing Library Cheat Sheet'
|
||
|
|
date: 2022-09-09 00:00:00
|
||
|
|
background: bg-blue-500
|
||
|
|
tags:
|
||
|
|
- react
|
||
|
|
- testing
|
||
|
|
- javascript
|
||
|
|
- cheatsheet
|
||
|
|
|
||
|
|
categories:
|
||
|
|
- Testing
|
||
|
|
|
||
|
|
intro: |
|
||
|
|
When it comes to testing React apps manually, we can either choose to render individual component trees in a simplified test environment or run the complete app in a realistic browser environment (end-to-end testing). But for automated tests, React Testing Library (RTL) is recommended for its user-centric approach and maintainability.
|
||
|
|
plugins:
|
||
|
|
- copyCode
|
||
|
|
---
|
||
|
|
|
||
|
|
## Introduction
|
||
|
|
|
||
|
|
React Testing Library is built on top of DOM Testing Library to test React components by querying and interacting with real DOM nodes, avoiding reliance on implementation details.
|
||
|
|
|
||
|
|
## Basic level
|
||
|
|
|
||
|
|
### 1. Purpose & Solution
|
||
|
|
|
||
|
|
RTL addresses maintainability by focusing on user-visible behavior:
|
||
|
|
|
||
|
|
- Tests run in actual DOM nodes.
|
||
|
|
- Queries mirror user interactions.
|
||
|
|
- `data-testid` as an escape hatch when needed.
|
||
|
|
- Encourages accessibility.
|
||
|
|
|
||
|
|
### 2. A basic component render test
|
||
|
|
|
||
|
|
**Component (App.js):**
|
||
|
|
|
||
|
|
```js
|
||
|
|
const title = 'Hello, World!';
|
||
|
|
|
||
|
|
function App() {
|
||
|
|
return <div>{title}</div>;
|
||
|
|
}
|
||
|
|
|
||
|
|
export default App;
|
||
|
|
```
|
||
|
|
|
||
|
|
**Test (App.test.js):**
|
||
|
|
|
||
|
|
```js
|
||
|
|
import { render } from '@testing-library/react';
|
||
|
|
import App from './App';
|
||
|
|
|
||
|
|
describe('App', () => {
|
||
|
|
test('renders App component', () => {
|
||
|
|
render(<App />);
|
||
|
|
});
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
Add debug to inspect output:
|
||
|
|
|
||
|
|
```js
|
||
|
|
import { render, screen } from '@testing-library/react';
|
||
|
|
import App from './App';
|
||
|
|
|
||
|
|
describe('App', () => {
|
||
|
|
test('renders App component', () => {
|
||
|
|
render(<App />);
|
||
|
|
screen.debug();
|
||
|
|
});
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
Output in console:
|
||
|
|
|
||
|
|
```html
|
||
|
|
<body>
|
||
|
|
<div>
|
||
|
|
<div>Hello, World!</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
```
|
||
|
|
|
||
|
|
### 3. Why use RTL vs Enzyme?
|
||
|
|
|
||
|
|
1. Tests based on user interactions, not internal APIs.
|
||
|
|
2. Improves maintainability after refactors.
|
||
|
|
3. Intuitive syntax (`getByText`, `getByAltText`, etc.).
|
||
|
|
|
||
|
|
### 4. Queries in RTL
|
||
|
|
|
||
|
|
```js
|
||
|
|
import { render, screen } from '@testing-library/react';
|
||
|
|
|
||
|
|
test('should show login form', () => {
|
||
|
|
render(<Login />);
|
||
|
|
const input = screen.getByLabelText('Username');
|
||
|
|
// events & assertions
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
**Single element queries:**
|
||
|
|
|
||
|
|
- `getBy*`: throws if none found
|
||
|
|
- `queryBy*`: returns null if none
|
||
|
|
- `findBy*`: async Promise
|
||
|
|
|
||
|
|
**Multiple elements queries:**
|
||
|
|
|
||
|
|
- `getAllBy*`: throws if none
|
||
|
|
- `queryAllBy*`: returns \[] if none
|
||
|
|
- `findAllBy*`: async Promise array
|
||
|
|
|
||
|
|
### 5. Component tree testing level
|
||
|
|
|
||
|
|
- Test at user interaction level, not per individual child component unless needed.
|
||
|
|
|
||
|
|
## Intermediate level
|
||
|
|
|
||
|
|
### 1. Jest vs RTL
|
||
|
|
|
||
|
|
- **Jest**: Test runner & assertion library (`describe`, `test`, `expect`).
|
||
|
|
- **RTL**: DOM utilities for React; works within Jest (or other runners).
|
||
|
|
|
||
|
|
### 2. Mocking with MSW
|
||
|
|
|
||
|
|
```js
|
||
|
|
// fetch.test.jsx
|
||
|
|
import React from 'react';
|
||
|
|
import { rest } from 'msw';
|
||
|
|
import { setupServer } from 'msw/node';
|
||
|
|
import { render, fireEvent, waitFor, screen } from '@testing-library/react';
|
||
|
|
import '@testing-library/jest-dom';
|
||
|
|
import Fetch from '../fetch';
|
||
|
|
|
||
|
|
const server = setupServer(
|
||
|
|
rest.get('/greeting', (req, res, ctx) =>
|
||
|
|
res(ctx.json({ greeting: 'hello there' }))
|
||
|
|
)
|
||
|
|
);
|
||
|
|
|
||
|
|
beforeAll(() => server.listen());
|
||
|
|
afterEach(() => server.resetHandlers());
|
||
|
|
afterAll(() => server.close());
|
||
|
|
|
||
|
|
test('loads and displays greeting', async () => {
|
||
|
|
render(<Fetch url="/greeting" />);
|
||
|
|
fireEvent.click(screen.getByText('Load Greeting'));
|
||
|
|
await waitFor(() => screen.getByRole('heading'));
|
||
|
|
expect(screen.getByRole('heading')).toHaveTextContent('hello there');
|
||
|
|
expect(screen.getByRole('button')).toBeDisabled();
|
||
|
|
});
|
||
|
|
|
||
|
|
test('handles server error', async () => {
|
||
|
|
server.use(rest.get('/greeting', (req, res, ctx) => res(ctx.status(500))));
|
||
|
|
render(<Fetch url="/greeting" />);
|
||
|
|
fireEvent.click(screen.getByText('Load Greeting'));
|
||
|
|
await waitFor(() => screen.getByRole('alert'));
|
||
|
|
expect(screen.getByRole('alert')).toHaveTextContent('Oops, failed to fetch!');
|
||
|
|
expect(screen.getByRole('button')).not.toBeDisabled();
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
### 3. `render` options
|
||
|
|
|
||
|
|
```js
|
||
|
|
import { render } from '@testing-library/react';
|
||
|
|
import '@testing-library/jest-dom';
|
||
|
|
|
||
|
|
test('renders a message', () => {
|
||
|
|
const table = document.createElement('table');
|
||
|
|
const { container } = render(<TableBody {...props} />, {
|
||
|
|
container: document.body.appendChild(table),
|
||
|
|
baseElement: document.body,
|
||
|
|
hydrate: true,
|
||
|
|
legacyRoot: true,
|
||
|
|
queries: {
|
||
|
|
/* custom queries */
|
||
|
|
}
|
||
|
|
});
|
||
|
|
expect(container).toBeInTheDocument();
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
### 4. `renderHook` usage
|
||
|
|
|
||
|
|
```js
|
||
|
|
import { renderHook } from '@testing-library/react';
|
||
|
|
|
||
|
|
test('returns logged in user', () => {
|
||
|
|
const { result, rerender } = renderHook(
|
||
|
|
({ name } = {}) => useLoggedInUser(name),
|
||
|
|
{ initialProps: { name: 'Alice' } }
|
||
|
|
);
|
||
|
|
expect(result.current).toEqual({ name: 'Alice' });
|
||
|
|
rerender({ name: 'Bob' });
|
||
|
|
expect(result.current).toEqual({ name: 'Bob' });
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
## Advanced Level
|
||
|
|
|
||
|
|
### 1. Adding custom queries
|
||
|
|
|
||
|
|
```js
|
||
|
|
const dom = require('@testing-library/dom');
|
||
|
|
const { queryHelpers, buildQueries } = require('@testing-library/react');
|
||
|
|
|
||
|
|
// Override testId attribute
|
||
|
|
export const queryByTestId = queryHelpers.queryByAttribute.bind(
|
||
|
|
null,
|
||
|
|
'data-test-id'
|
||
|
|
);
|
||
|
|
export const queryAllByTestId = queryHelpers.queryAllByAttribute.bind(
|
||
|
|
null,
|
||
|
|
'data-test-id'
|
||
|
|
);
|
||
|
|
export function getAllByTestId(container, id, ...rest) {
|
||
|
|
const els = queryAllByTestId(container, id, ...rest);
|
||
|
|
if (!els.length)
|
||
|
|
throw queryHelpers.getElementError(
|
||
|
|
`No element with [data-test-id="${id}"]`,
|
||
|
|
container
|
||
|
|
);
|
||
|
|
return els;
|
||
|
|
}
|
||
|
|
export function getByTestId(container, id, ...rest) {
|
||
|
|
const els = getAllByTestId(container, id, ...rest);
|
||
|
|
if (els.length > 1)
|
||
|
|
throw queryHelpers.getElementError(
|
||
|
|
`Multiple elements with [data-test-id="${id}"]`,
|
||
|
|
container
|
||
|
|
);
|
||
|
|
return els[0];
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
Or using `buildQueries`:
|
||
|
|
|
||
|
|
```js
|
||
|
|
const queryAllByDataCy = (...args) =>
|
||
|
|
queryHelpers.queryAllByAttribute('data-cy', ...args);
|
||
|
|
const [
|
||
|
|
queryByDataCy,
|
||
|
|
getAllByDataCy,
|
||
|
|
getByDataCy,
|
||
|
|
findAllByDataCy,
|
||
|
|
findByDataCy
|
||
|
|
] = buildQueries(
|
||
|
|
queryAllByDataCy,
|
||
|
|
(c, v) => `Found multiple elements with data-cy="${v}"`,
|
||
|
|
(c, v) => `Unable to find element with data-cy="${v}"`
|
||
|
|
);
|
||
|
|
```
|
||
|
|
|
||
|
|
### 2. Skipping auto cleanup
|
||
|
|
|
||
|
|
- Via CLI: `cross-env RTL_SKIP_AUTO_CLEANUP=true jest`
|
||
|
|
- Or add to Jest `setupFiles`: `import '@testing-library/react/dont-cleanup-after-each';`
|
||
|
|
|
||
|
|
### 3. Migrating from Enzyme
|
||
|
|
|
||
|
|
1. Install RTL & jest-dom.
|
||
|
|
2. Replace `shallow`/`mount` with `render` + `screen`.
|
||
|
|
3. Migrate tests incrementally.
|
||
|
|
|
||
|
|
### 4. Querying within elements
|
||
|
|
|
||
|
|
```js
|
||
|
|
import { render, within } from '@testing-library/react';
|
||
|
|
|
||
|
|
const { getByText } = render(<MyComponent />);
|
||
|
|
const section = getByText('messages');
|
||
|
|
const hello = within(section).getByText('hello');
|
||
|
|
```
|
||
|
|
|
||
|
|
### 5. Integration testing
|
||
|
|
|
||
|
|
```js
|
||
|
|
import { render, cleanup, waitFor } from '@testing-library/react';
|
||
|
|
import userEvent from '@testing-library/user-event';
|
||
|
|
import nock from 'nock';
|
||
|
|
import App from '../App';
|
||
|
|
|
||
|
|
const REPOS = [{ name: 'repo1', description: '...' }];
|
||
|
|
|
||
|
|
beforeAll(() =>
|
||
|
|
nock('https://api.github.com')
|
||
|
|
.persist()
|
||
|
|
.get('/users/alice/repos')
|
||
|
|
.reply(200, REPOS)
|
||
|
|
);
|
||
|
|
afterEach(cleanup);
|
||
|
|
|
||
|
|
test('user sees public repos', async () => {
|
||
|
|
render(<App />);
|
||
|
|
userEvent.type(screen.getByPlaceholderText('Enter username'), 'alice');
|
||
|
|
userEvent.click(screen.getByRole('button', { name: /submit/i }));
|
||
|
|
await waitFor(() =>
|
||
|
|
REPOS.forEach((r) => expect(screen.getByText(r.name)).toBeInTheDocument())
|
||
|
|
);
|
||
|
|
expect(screen.queryByText('Loading...')).toBeNull();
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
## Conclusion
|
||
|
|
|
||
|
|
This comprehensive cheat sheet covers basic to advanced RTL usage—rendering, querying, mocking, custom queries, and integration tests—to help you write robust, maintainable tests.
|