react-testing-library

General-purpose guide for testing React components and hooks with React Testing Library (RTL) and Vitest. Project-agnostic — works with any Vite + React setup.

Philosophy: Fewer Tests, Real Scenarios

"Write tests. Not too many. Mostly integration." — Kent C. Dodds

1. Use-case coverage > code coverage — aim for 100% use-case coverage, not 100% line coverage. Think about what the user can DO, not what the code does internally.
2. Write fewer, longer tests — one test that walks through a full user flow beats six isolated assertions. Combine related steps (render → interact → verify) into a single test.
3. Test behavior, not implementation — assert on what the user sees and can do. Never assert on internal state, hook calls, or DOM structure.
4. Mock at boundaries only — mock API calls and external services. Never mock your own components, hooks, or context internals.
5. Each test must justify its existence — if removing a test wouldn't reduce your confidence that the app works, delete it.

The Testing Trophy (what to invest in)

    E2E        ← Few: critical user journeys only (Playwright/Cypress)
  Integration  ← MOST tests: components with real providers, MSW for APIs
  Unit         ← Some: complex pure logic, utilities, formatters
Static Analysis ← Always: TypeScript, ESLint

---

Setup from Scratch

1. Install Dependencies

npm install -D vitest @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom

Optional but recommended:

npm install -D msw                     # Network-level API mocking
npm install -D @vitest/coverage-v8     # Code coverage

2. Vitest Config

Create vitest.config.js at the client root (or extend vite.config.js):

import { defineConfig, mergeConfig } from 'vitest/config';
import viteConfig from './vite.config.js';

export default mergeConfig(viteConfig, defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: ['./src/test/setup.js'],
    css: true,
    include: ['src/**/*.test.{js,jsx,ts,tsx}'],
  },
}));

3. Setup File

Create src/test/setup.js:

import '@testing-library/jest-dom/vitest';

This registers matchers like toBeInTheDocument(), toBeVisible(), toHaveTextContent().

4. Package Scripts

Add to package.json:

{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage"
  }
}

---

Test Scenarios by Component Type

Before writing tests, identify the component type and pick scenarios from this matrix. Write 1-3 tests per component — each test covers a full user flow, not a single assertion.

Form Component (e.g., BlogEditor, LoginForm, CommentForm)

List/Table Component (e.g., BlogList, CommentList, Dashboard)

Detail/View Component (e.g., BlogDetail, UserProfile)

Auth-Gated Component (e.g., AdminPanel, ProtectedRoute)

Shared/Presentational Component (e.g., BlogCard, Button, Modal)

---

Complete Spec Template

This is what a well-structured test file looks like. Each test walks through a real user flow.

// BlogList.test.jsx
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { render, screen, within } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { MemoryRouter } from 'react-router';
import { http, HttpResponse } from 'msw';
import { setupServer } from 'msw/node';
import BlogList from './BlogList';

// --- MSW setup: mock the API at the network level ---
const blogs = [
  { _id: '1', title: 'First Post', category: 'Technology', excerpt: 'About tech' },
  { _id: '2', title: 'Second Post', category: 'Startup', excerpt: 'About startups' },
];

const server = setupServer(
  http.get('/api/blogs', () => HttpResponse.json({ success: true, blogs })),
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

// --- Render helper (keeps tests DRY) ---
const renderBlogList = () =>
  render(<MemoryRouter><BlogList /></MemoryRouter>);

// --- Tests: 3 tests covering ALL real scenarios ---
describe('BlogList', () => {
  it('loads blogs and lets user navigate to a post', async () => {
    const user = userEvent.setup();
    renderBlogList();

    // Loading state appears first
    expect(screen.getByText(/loading/i)).toBeInTheDocument();

    // Blogs appear after fetch
    expect(await screen.findByText('First Post')).toBeInTheDocument();
    expect(screen.getByText('Second Post')).toBeInTheDocument();

    // User clicks a blog card
    await user.click(screen.getByRole('link', { name: /first post/i }));
    // Assert navigation happened (or verify detail view renders)
  });

  it('shows empty state when no blogs exist', async () => {
    server.use(
      http.get('/api/blogs', () => HttpResponse.json({ success: true, blogs: [] })),
    );
    renderBlogList();

    expect(await screen.findByText(/no blogs/i)).toBeInTheDocument();
    expect(screen.queryByRole('article')).not.toBeInTheDocument();
  });

  it('shows error message when API fails', async () => {
    server.use(
      http.get('/api/blogs', () => HttpResponse.json(
        { success: false, message: 'Server error' },
        { status: 500 },
      )),
    );
    renderBlogList();

    expect(await screen.findByRole('alert')).toBeInTheDocument();
    expect(screen.queryByRole('article')).not.toBeInTheDocument();
  });
});

Form Spec Template

// LoginForm.test.jsx
describe('LoginForm', () => {
  it('logs in with valid credentials and shows dashboard', async () => {
    const user = userEvent.setup();
    render(<MemoryRouter><LoginForm /></MemoryRouter>);

    // Fill form
    await user.type(screen.getByLabelText(/email/i), 'admin@test.com');
    await user.type(screen.getByLabelText(/password/i), 'password123');
    await user.click(screen.getByRole('button', { name: /sign in/i }));

    // Success: redirected or success message
    expect(await screen.findByText(/welcome/i)).toBeInTheDocument();
  });

  it('shows validation errors when submitted empty', async () => {
    const user = userEvent.setup();
    render(<MemoryRouter><LoginForm /></MemoryRouter>);

    await user.click(screen.getByRole('button', { name: /sign in/i }));

    // Both fields show errors
    expect(await screen.findByText(/email is required/i)).toBeInTheDocument();
    expect(screen.getByText(/password is required/i)).toBeInTheDocument();

    // Form is still visible (not redirected)
    expect(screen.getByRole('button', { name: /sign in/i })).toBeInTheDocument();
  });

  it('shows server error when API returns 401', async () => {
    server.use(
      http.post('/api/admin/login', () =>
        HttpResponse.json({ success: false, message: 'Invalid credentials' }, { status: 401 }),
      ),
    );
    const user = userEvent.setup();
    render(<MemoryRouter><LoginForm /></MemoryRouter>);

    await user.type(screen.getByLabelText(/email/i), 'admin@test.com');
    await user.type(screen.getByLabelText(/password/i), 'wrongpassword');
    await user.click(screen.getByRole('button', { name: /sign in/i }));

    expect(await screen.findByText(/invalid credentials/i)).toBeInTheDocument();
  });
});

---

Import Rules

// Test runner — ALWAYS from vitest
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';

// RTL — render, screen, waitFor
import { render, screen, waitFor, within } from '@testing-library/react';

// User interaction — ALWAYS userEvent, NEVER fireEvent
import userEvent from '@testing-library/user-event';

// Hook testing
import { renderHook, act } from '@testing-library/react';

NEVER import from jest. Use vi.fn(), vi.spyOn(), vi.mock().

---

Query Priority

Queries are ordered by how closely they reflect user experience.

Tier 1 — Accessible (default choice)

Tier 2 — Semantic

Tier 3 — Last resort

Query Variants

Role Query Patterns

getByRole('button', { name: /submit/i })
getByRole('heading', { level: 2 })
getByRole('textbox', { name: /email/i })
getByRole('link', { name: /read more/i })
getByRole('checkbox', { name: /agree/i })
getByRole('combobox')              // <select>
getByRole('status')                // role="status"
getByRole('alert')                 // role="alert"
getByRole('dialog')                // <dialog> or role="dialog"
getByRole('navigation')            // <nav>

---

userEvent

Always call userEvent.setup() before rendering. All methods are async.

Pattern:

const user = userEvent.setup();
render(<Component />);
await user.click(screen.getByRole('button', { name: /save/i }));

---

Async Testing

findBy — element appears after async work

render(<BlogList />);
expect(await screen.findByText('Blog Title')).toBeInTheDocument();

waitFor — multiple assertions, complex conditions

await waitFor(() => {
  expect(screen.getAllByRole('listitem')).toHaveLength(3);
});

waitForElementToBeRemoved — element disappears

render(<BlogList />);
await waitForElementToBeRemoved(() => screen.queryByText('Loading...'));

Rules

• Never use setTimeout or fixed delays
• Never use act() directly unless testing hooks outside components — RTL wraps it
• findBy is preferred over waitFor + getBy for single-element waits
• waitFor retries until the callback passes or times out (default 1000ms)

---

Component Testing Patterns

Basic render + interaction

1. Arrange — render the component with props/providers
2. Act — simulate user interaction via userEvent
3. Assert — check what the user would see

Combine all three into a single test when they form one user flow. Don't split Arrange/Act/Assert into separate it() blocks.

Render helper

Create a local renderComponent function when the component needs providers:

const renderComponent = (props = {}) =>
  render(
    <MemoryRouter>
      <MyComponent defaultProp="value" {...props} />
    </MemoryRouter>
  );

Asserting absence

// queryBy returns null — safe with .not
expect(screen.queryByText('Error')).not.toBeInTheDocument();

Scoping queries with within

const card = screen.getByRole('article');
expect(within(card).getByText('Title')).toBeInTheDocument();

---

Hook Testing

Use renderHook for hooks with complex pure logic only. If a hook just fetches data or manages simple state, test it through the component that uses it instead.

import { renderHook, act } from '@testing-library/react';

const { result } = renderHook(() => useCounter());
act(() => result.current.increment());
expect(result.current.count).toBe(1);

For hooks needing providers, pass a wrapper:

renderHook(() => useAuth(), {
  wrapper: ({ children }) => <AuthProvider>{children}</AuthProvider>,
});

---

React Router Wrapping

Components using <Link>, useNavigate, useParams, or useLocation must be wrapped:

// Simple
render(<MemoryRouter><MyComponent /></MemoryRouter>);

// With route params
render(
  <MemoryRouter initialEntries={['/blogs/123']}>
    <Routes>
      <Route path="/blogs/:id" element={<BlogDetail />} />
    </Routes>
  </MemoryRouter>
);

---

Mocking Strategies

MSW (Mock Service Worker) — preferred for all data-fetching components

Intercepts at the network layer. Tests don't couple to HTTP client internals. Most realistic approach.

import { setupServer } from 'msw/node';
import { http, HttpResponse } from 'msw';

const server = setupServer(
  // Default happy-path handlers
  http.get('/api/blogs', () => HttpResponse.json({ success: true, blogs: [...] })),
  http.post('/api/blogs', async ({ request }) => {
    const body = await request.json();
    return HttpResponse.json({ success: true, blog: { _id: '1', ...body } }, { status: 201 });
  }),
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

// Override for specific tests:
it('handles error', async () => {
  server.use(
    http.get('/api/blogs', () => HttpResponse.json({ success: false }, { status: 500 })),
  );
  // ...
});

Module mock (vi.mock) — fallback when MSW is overkill

vi.mock('../../api/blogApi', () => ({
  getBlogs: vi.fn(),
}));

• Mock at the API/hook level, not at Axios/fetch level
• Reset in beforeEach: vi.clearAllMocks()
• Use vi.mocked(fn) for type-safe access to mock methods

Context mocking

Wrap component in a test provider with controlled values. Don't mock context internals — render with the real provider.

Timers

vi.useFakeTimers();
// ... render and trigger timer-dependent code
vi.advanceTimersByTime(3000);
vi.useRealTimers(); // restore in afterEach

---

What to Test / What to Skip

Test (as user-visible flows):

• User journeys: form fill → submit → feedback
• Data display: loading → loaded → interaction
• State transitions: empty → filled, logged out → logged in
• Error boundaries: API failure → error message
• Conditional UI: different user roles see different things

Skip:

• Internal state (useState values)
• Implementation details (hook calls, private functions)
• CSS classes or inline styles
• Third-party library internals
• Render counts or performance
• Snapshot tests (unless explicitly requested)
• Constants or static data
• Individual assertions that belong inside a longer flow test

---

jest-dom Matchers Reference

---

Test File Conventions

• Place tests next to source: BlogCard.jsx -> BlogCard.test.jsx
• Use .test.jsx extension (not .spec.jsx)
• One describe per component/hook
• Test names describe user-visible behavior: "user fills form and sees success message"
• Use vi.fn() for all mock functions
• Call userEvent.setup() before render()
• Always use screen — never destructure from render()
• 1-3 tests per component (user flows), 1-2 per hook, 2-3 per utility

---

Anti-Patterns