guimap01/test-react

React Unit Testing

Stack: Vitest + @testing-library/react + @testing-library/user-event + @testing-library/jest-dom.

Vitest is configured in vite.config.ts (environment: "jsdom", globals: true). All tests run through Vite's pipeline — no transform config needed.

File conventions

| What | Where | |------|-------| | Page / component tests | src/<domain>/__tests__/<name>.test.tsx | | Shared render helpers | src/test/utils.tsx | | Global setup | src/test/setup.ts |

Run with pnpm test (watch) or pnpm test:run (CI).

Core patterns

Render helper

Always wrap components that use <Link> or any router primitive in MemoryRouter:

import { renderWithRouter } from "@/test/utils";

renderWithRouter(<LoginPage />);

Mocking hooks

Mock at the module level with vi.mock, then set the return value per test with vi.mocked:

vi.mock("@/context/auth-context");

const mockLogin = vi.fn();

beforeEach(() => {
  vi.clearAllMocks();
  vi.mocked(useAuth).mockReturnValue({
    user: null, isLoading: false,
    login: mockLogin, register: vi.fn(), logout: vi.fn(),
  });
});

User interactions

Always use userEvent.setup() — not fireEvent — for realistic browser simulation:

const user = userEvent.setup();
await user.type(screen.getByLabelText(/email/i), "[email protected]");
await user.click(screen.getByRole("button", { name: /sign in/i }));

Form validation tests

Add noValidate to every <form> that uses a JS validation library. Without it, jsdom's native browser validation blocks the submit event before react-hook-form runs, causing validation tests to silently fail:

// In the component — required for tests to work
<form noValidate onSubmit={...}>

Then in the test:

// Submit → wait for the zod error to appear
await user.click(screen.getByRole("button", { name: /submit/i }));
expect(await screen.findByText("Invalid email address")).toBeInTheDocument();

Async assertions

Use findBy* (returns a promise) for elements that appear after async work. Use waitFor to assert something eventually becomes true:

// Element appears after async: findBy
expect(await screen.findByText(/invalid email/i)).toBeInTheDocument();

// Mock was called after async: waitFor
await waitFor(() => expect(mockLogin).toHaveBeenCalledWith({ ... }));

Loading state

Use a never-resolving promise to hold the component in the pending state:

let resolve!: () => void;
mockLogin.mockReturnValue(new Promise<void>((r) => { resolve = r; }));

await user.click(submitButton);

expect(await screen.findByRole("button", { name: /signing in/i })).toBeDisabled();
resolve(); // clean up

Error alerts

mockLogin.mockRejectedValue(new Error("Unauthorized"));
// ... fill and submit ...
expect(await screen.findByText(/invalid email or password/i)).toBeInTheDocument();

What NOT to do

• Never use array index as a key in dynamic lists
• Never use fireEvent for form submission — use userEvent.setup() and user.click
• Never snapshot-test components with shadcn classes — they change frequently and make noise
• Never import the real axios/api client in tests — mock the context or hook layer instead

Checklist for a new test file

• [ ] vi.mock(...) for all hooks/contexts used by the component
• [ ] vi.clearAllMocks() in beforeEach
• [ ] renderWithRouter if the component contains any <Link>
• [ ] noValidate on <form> in the component under test
• [ ] Uses findBy* for async elements, getBy* for synchronous
• [ ] Loading state tested with a pending promise
• [ ] Error state tested with a rejected mock
• [ ] Happy path tested: correct args passed to mocked function