Test what people can see, not how the component works

A React component has two kinds of users. One is the person at the screen: Ama with her mouse, a staff member with a keyboard, someone with a screen reader. The other is the developer who renders the component and passes it props. An implementation detail is anything neither of them can see: the name of a state variable, whether you used useState or useReducer, CSS class names, a private helper function, how many times the component rendered.

Tests that check implementation details fail in two directions. They give false alarms: you move the adjustment panel from useState to a reducer, the screen works exactly as before, and ten tests go red because they read state that no longer exists. And they give false comfort: someone changes the Save button into an icon with no label, the class name stays the same, every test passes, and a screen reader user hears only "button". After a few false alarms, people "fix" red tests by updating them to match the code, and then the tests check nothing.

Testing Library is built around one idea, stated on its guiding principles page: the closer your tests are to the way the software is used, the more confidence they give you. Before you write an assertion, ask: could the person at the screen, or the parent component, notice this? They can notice text and numbers on the screen, whether a button is enabled, which element has focus, an error next to a field, a request that reaches the server, a callback prop such as onSaved being called, and the URL. They cannot notice your state, your hooks or your class names.

// Breaks when you refactor, passes when people are stuck
vi.mock('@/lib/api');                                  // the real fetch code never runs
const { container } = render(<AdjustForm storeId="S027" item={rice} />);
fireEvent.change(container.querySelector('#delta')!, { target: { value: '-2' } });
fireEvent.click(container.querySelector('.btn-primary')!);  // finds an icon button too
expect(saveAdjustment).toHaveBeenCalled();             // "it called my function"
expect(container.querySelector('.toast--ok')).not.toBeNull();

// Fails only when Ama could not do this
const user = userEvent.setup();
render(<AdjustForm storeId="S027" item={rice} />);
await user.type(screen.getByLabelText('Change'), '-2');
await user.click(screen.getByRole('button', { name: 'Save adjustment' }));
await waitFor(() =>
  expect(screen.getByRole('status')).toHaveTextContent('Saved: Rice 5 kg is now 10'));

The second test reads like Ama's morning: find the Change field by its label, type, press the button called "Save adjustment", see the confirmation. It survives any rewrite that keeps that experience, and it fails if the label, the button name or the message disappears. You still use unit tests for logic (Errors, debugging and testing covers Vitest); this lesson is about the screen on top of that logic.