React Testing Library (RTL) doesn’t test your component’s implementation details; it tests its behavior from the user’s perspective. This is the core principle that makes your tests more robust and less brittle.
Let’s see RTL in action. Imagine a simple Counter component:
// src/Counter.js
import React, { useState } from 'react';
function Counter() {
const [count, setCount] = useState(0);
return (
<div>
<p>You clicked {count} times</p>
<button onClick={() => setCount(count + 1)}>
Click me
</button>
</div>
);
}
export default Counter;
Here’s how you’d test it with RTL, focusing on user interaction:
// src/Counter.test.js
import React from 'react';
import { render, screen, fireEvent } from '@testing-library/react';
import Counter from './Counter';
test('increments count when button is clicked', () => {
render(<Counter />); // Render the component
// Get the button by its accessible name (the text content)
const buttonElement = screen.getByRole('button', { name: /click me/i });
expect(buttonElement).toBeInTheDocument();
// Check the initial count
const paragraphElement = screen.getByText(/you clicked 0 times/i);
expect(paragraphElement).toBeInTheDocument();
// Simulate a click event on the button
fireEvent.click(buttonElement);
// Check if the count updated
expect(screen.getByText(/you clicked 1 time/i)).toBeInTheDocument();
// Click again
fireEvent.click(buttonElement);
expect(screen.getByText(/you clicked 2 times/i)).toBeInTheDocument();
});
RTL encourages you to query elements the way a user would. Instead of looking for a component by its name or a CSS class, you’re encouraged to find elements by their accessible roles (like button, textbox, dialog), their associated labels, or their visible text content. This means your tests will pass as long as the component’s functionality remains accessible to a user, even if you refactor the internal implementation (e.g., change state management or component structure).
The render function from @testing-library/react is your entry point. It takes your React component and renders it into a virtual DOM environment provided by jsdom (by default, when running in Node.js). The screen object is a collection of query methods that allow you to select elements from this rendered output.
Key query methods include:
getByRole: Finds elements by their ARIA role. This is often the most robust method as it leverages accessibility information.getByLabelText: Finds form elements (like inputs, textareas, selects) by their associated<label>element’s text.getByPlaceholderText: Finds form elements by theirplaceholderattribute.getByText: Finds elements by their text content. Be mindful of exact matches vs. regular expressions, and consider how whitespace might affect matches.getByDisplayValue: Finds form elements by their current value.getByAltText: Finds elements like<img>or<area>by theiraltattribute.getByTitle: Finds elements by theirtitleattribute.
You typically combine these with fireEvent (or @testing-library/user-event for more realistic interactions) to simulate user actions like clicks, typing, or hovering.
The philosophy behind RTL is to test the "what," not the "how." You’re testing that when a user clicks a button, the displayed text updates. You’re not testing that a specific useState hook was called or that a particular method was invoked internally. This separation of concerns makes your tests resilient to refactoring.
When you need to interact with elements that aren’t immediately visible or might appear after an asynchronous operation, you’ll use waitFor or waitForElementToBeRemoved. For instance, if a component fetches data and then displays it, you’d wrap your assertion within waitFor to give the component time to update.
import { render, screen, waitFor } from '@testing-library/react';
import MyComponent from './MyComponent'; // Assume MyComponent fetches data
test('displays fetched data after loading', async () => {
render(<MyComponent />);
// Initially, maybe a loading indicator is shown
expect(screen.getByText('Loading...')).toBeInTheDocument();
// Wait for the data to appear and the loading indicator to disappear
await waitFor(() => {
expect(screen.queryByText('Loading...')).not.toBeInTheDocument();
});
expect(screen.getByText('Some fetched data')).toBeInTheDocument();
});
A crucial aspect often overlooked is the selection of the right query. While getByText is convenient, it can be fragile. If a component renders a list of items and you use getByText('Item 1'), and later add another item that also contains "Item 1" in its text, your test might fail. Preferring getByRole with accessible names or getByLabelText for form inputs provides a more stable foundation. For example, if you have a button with an icon and text, screen.getByRole('button', { name: /submit/i }) is superior to screen.getByText('Submit') because it correctly identifies the button based on its accessible name, which often combines the button text and any ARIA labels.
Another common pitfall is testing internal component state or methods directly. RTL explicitly discourages this. If you find yourself wanting to assert the value of a prop passed to a child component or check if a specific internal function was called, you’re likely straying from the user-centric approach. Instead, ask yourself: "How would a user perceive this change?" and test for that observable outcome.
When dealing with complex forms or user flows, consider using @testing-library/user-event. It provides a more realistic simulation of user interactions than fireEvent, handling things like focus management and keyboard events more accurately. For instance, userEvent.type(inputElement, 'hello') is generally preferred over fireEvent.change(inputElement, { target: { value: 'hello' } }) because it simulates individual keystrokes.
The next logical step after mastering basic rendering and interaction is understanding how to handle context, routing, and custom hooks within your tests, often by providing mock implementations or wrapping your component in necessary providers.