testing-react

Test Classification

Type	Tool	Target	File pattern
Unit	Vitest	Pure functions, utilities, services	Co-located *.test.ts
Component	Vitest + RTL	React components	Co-located *.test.tsx
Hook	Vitest + RTL	Custom hooks	Co-located *.test.ts
E2E	Playwright	User flows, critical paths	Separate e2e/ directory

Default to component tests for React components. Unit tests for pure functions and service classes. See e2e-testing for Playwright patterns.

Setup

Vitest config: environment: 'jsdom', globals: true, setupFiles pointing to a file that imports @testing-library/jest-dom/vitest. Use @vitejs/plugin-react and mirror path aliases from tsconfig.json.

Critical Rules

• Query priority: getByRole > getByLabelText > getByPlaceholderText > getByText > getByTestId. Use data-testid only when no accessible query works.
• Mock boundaries: Mock API services, navigation, and external providers. Render child components and UI libraries real for integration confidence.
• One behavior per test with AAA structure. Name tests should <behavior> when <condition>.
• Async: Use findBy* for async elements, waitFor after state-triggering actions, vi.useFakeTimers() for debounce/timer logic.
• User events: Prefer userEvent over fireEvent for realistic interactions.
• Cleanup: vi.clearAllMocks() in beforeEach. Recreate test state per test instead of sharing mutable variables.
• Incremental workflow: When testing a directory, process one file at a time (simplest first). Run and verify each before proceeding.
• Tests expose bugs, not the reverse: If a test uncovers broken or buggy behavior, highlight the issue and propose a fix to the source code. Never adjust the test to match incorrect behavior.

Component Test

import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

vi.mock('@/api/client');

describe('UserForm', () => {
  beforeEach(() => { vi.clearAllMocks(); });

  it('should submit valid form data', async () => {
    const onSubmit = vi.fn();
    render(<UserForm onSubmit={onSubmit} />);

    await userEvent.type(screen.getByLabelText(/email/i), '[email protected]');
    await userEvent.click(screen.getByRole('button', { name: /submit/i }));

    await waitFor(() => {
      expect(onSubmit).toHaveBeenCalledWith(
        expect.objectContaining({ email: '[email protected]' }),
      );
    });
  });
});