testing-react-with-vitest

name

testing-react-with-vitest

description

Expert guidance for writing Vitest tests for React applications using React Testing Library. Covers component tests, custom hooks, utility tests, sociable testing philosophy, and the RTL query priority system. Favors sociable tests over heavy mocking, stubs over mocks. Use when working with .test.ts/.test.tsx files, vitest.config.ts, React Testing Library, @testing-library/user-event, @testing-library/jest-dom, renderHook, or when discussing React testing patterns, component testing, hook testing, or test organization.

Testing React with Vitest

Expert guidance for writing great Vitest tests for React applications using React Testing Library.

Quick Start

Testing...	Reference File	Key Topics
Core Vitest setup, matchers, spies	core-vitest	describe, it, expect, vi.fn, vi.mock, timers
RTL queries, render, screen	react-testing-library	render, screen, queries, waitFor, debug
User interactions	user-event	setup, click, type, keyboard, async events
Sociable tests, stubs, boundaries	sociable-testing	Real components, stub boundaries, functional core
Custom hooks with renderHook	custom-hooks	renderHook, act, providers, cleanup
Component testing patterns	component-patterns	Forms, modals, lists, error boundaries, a11y
jest-dom assertion matchers	assertions	toBeInTheDocument, toBeVisible, toHaveTextContent

Testing Philosophy

These principles are non-negotiable defaults for all React testing advice.

Sociable Tests by Default

Use real child components. A test for <CheckoutPage /> should render real <CartSummary /> and <PaymentForm /> components, not mocked replacements. Sociable tests catch integration bugs, survive refactors, and test actual behavior.

Stubs Over Mocks

When you must replace a dependency, prefer stubs that return canned data over mocks that verify call sequences. A stubbed fetch that returns { items: [] } is better than a mock that asserts fetch was called with specific arguments.

Test Behavior, Not Implementation

Assert on what the user sees and can do. Never assert on internal state, hook return values observed from outside, or component instance methods. If a user cannot observe it, do not test it.

Only Stub at True System Boundaries

Real boundaries: fetch/HTTP clients, browser APIs (localStorage, navigator, IntersectionObserver), third-party services, timers. Not boundaries: your own components, hooks, utilities, or context providers.

Query Priority: role > label > text > testid

Prefer accessible queries. getByRole('button', { name: 'Submit' }) is better than getByTestId('submit-btn'). Test IDs are a last resort when no accessible query works.

Anti-Patterns

• Mocking child components: vi.mock('./CartSummary') hides integration bugs. Render real children unless they hit a system boundary.
• Testing implementation details: expect(setState).toHaveBeenCalledWith(...) couples tests to internals. Assert on rendered output instead.
• Snapshot overuse: Large snapshots break on every change and nobody reads the diffs. Prefer targeted assertions on specific elements.
• Using container.querySelector: Bypasses the accessibility-first query model. Use screen.getByRole, screen.getByLabelText, or screen.getByText instead.
• Wrapping every action in act(): RTL's render, fireEvent, and user-event already wrap in act(). Manual act() is only needed for direct state updates outside RTL.
• Testing CSS classes or inline styles: These are implementation details. Use toBeVisible(), toHaveAccessibleName(), or test the behavior the style enables.
• Mocking your own hooks: vi.mock('./useCart') tests the component in isolation from its real logic. Let the component use its real hooks.
• getByTestId as a first choice: Always try getByRole, getByLabelText, getByText, getByPlaceholderText first. Test IDs are a last resort.

Reference File IDs

core-vitest . react-testing-library . user-event . sociable-testing . custom-hooks . component-patterns . assertions