Skip to content

Latest commit

 

History

History
207 lines (150 loc) · 6.9 KB

react.md

File metadata and controls

207 lines (150 loc) · 6.9 KB

React + Vitest Testing Guide

Ready-to-use snippets for testing your React applications with Vitest and React Testing Library

Status: Piloted on a React + .NET production template

This is the React counterpart of the Nuxt guide. The doctrine is identical — data-test-* selectors, exhaustive case plans in task-test.md, isolated deterministic tests — only the tooling changes. Read AGENTS.md first; this guide is the cookbook, not the playbook.


Basic Configuration

Installation

npm install -D vitest @vitejs/plugin-react jsdom @vitest/coverage-v8 @testing-library/react @testing-library/user-event @testing-library/jest-dom msw

vite.config.ts (test block)

test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: ['./src/test/setup.ts'],
    coverage: {
        provider: 'v8',
        reporter: ['text', 'html'],
        include: ['src/**', 'lib/**'],
        exclude: ['**/*.test.*', 'src/test/**'],
        thresholds: { lines: 80, branches: 80, functions: 80, statements: 80 },
    },
},

src/test/setup.ts

import '@testing-library/jest-dom'
import { afterEach } from 'vitest'
import { cleanup, configure } from '@testing-library/react'

configure({ testIdAttribute: 'data-test-id' })

afterEach(() => {
    cleanup()
})

Without the configure line, getByTestId looks for data-testid and every snippet below silently fails — it is part of the infra, not an option.

Selector lint gate

Wire the ESLint override from AGENTS.md Step 3 so getByText, getByRole, querySelector, closest, toHaveClass and friends are red in test files, and ban the app's real store module via no-restricted-imports. The infra is not done until a forbidden selector fails lint.

src/test/utils.tsx — render helper and group query

import { render } from '@testing-library/react'
import { Provider } from 'react-redux'
import { MemoryRouter } from 'react-router-dom'
import { configureStore } from '@reduxjs/toolkit'
import type { ReactElement } from 'react'
import userReducer, { initialUserState, type UserState } from '../store/userSlice'

type PreloadedState = { user?: Partial<UserState> }

export function makeTestStore(preloaded: PreloadedState = {}) {
    return configureStore({
        reducer: { user: userReducer },
        preloadedState: preloaded.user
            ? { user: { ...initialUserState, ...preloaded.user } }
            : undefined,
    })
}

export function renderWithProviders(
    ui: ReactElement,
    { preloaded, route = '/' }: { preloaded?: PreloadedState; route?: string } = {},
) {
    const store = makeTestStore(preloaded)
    const result = render(
        <Provider store={store}>
            <MemoryRouter initialEntries={[route]}>{ui}</MemoryRouter>
        </Provider>,
    )
    return { ...result, store }
}

export function getAllByTestClass(container: HTMLElement, name: string) {
    return Array.from(
        container.querySelectorAll<HTMLElement>(`[data-test-class="${name}"]`),
    )
}

Every test mounts through renderWithProviders with a fresh, seeded store — never the app's singleton store (src/store/store), which drags redux-persist, real middlewares and shared state into your tests. getAllByTestClass lives here, outside the lint override's scope, so group selection stays possible while querySelector stays banned in test files.


Data Attributes Conventions

Same two attributes and naming rules as the Nuxt guide, written JSX-style:

<button data-test-id="bon-form-submit">Envoyer</button>
<input data-test-id="bon-client-name-input" />
<div data-test-class="bon-piece-row">...</div>

Name by role, never by style or position. env-attr-cleaner strips them from staging/production builds.


Core Cases

Select and assert on a unique element

renderWithProviders(<BonFormulaire />)
expect(screen.getByTestId('bon-form-submit')).toBeDisabled()

Select and count a group

const { container } = renderWithProviders(<BonFormulaire />)
const rows = getAllByTestClass(container, 'bon-piece-row')
expect(rows).toHaveLength(3)

User interactions

const user = userEvent.setup()
renderWithProviders(<LoginForm />)
await user.type(screen.getByTestId('login-email-input'), 'a@b.fr')
await user.click(screen.getByTestId('login-submit'))
expect(screen.getByTestId('login-error')).toHaveTextContent('Mot de passe requis')

Assert a variant through state, not classes

Never toHaveClass('bg-destructive') — the Tailwind class is styling, not behaviour, and renames green-break your suite. Expose the state as a hook and assert on it:

<div data-test-id="alert" data-test-state={variant}>...</div>
expect(screen.getByTestId('alert')).toHaveAttribute('data-test-state', 'destructive')

Mock the network with typed fixtures (MSW)

import { http, HttpResponse } from 'msw'
import { setupServer } from 'msw/node'
import type { Intervention } from '../types/intervention'

const intervention: Intervention = {
    id: 12,
    clientName: 'Fitness Park',
    startDate: '2026-07-17T08:00:00Z',
    endDate: '2026-07-17T10:00:00Z',
}

export const server = setupServer(
    http.get('/Intervention/GetInterventionById/:id', () =>
        HttpResponse.json(intervention),
    ),
)

The fixture is typed from the real contract: a mock of a renamed endpoint or a drifted shape fails at type-check instead of greening a broken integration.

Freeze time and test the exact boundary

beforeEach(() => {
    vi.useFakeTimers()
    vi.setSystemTime(new Date('2026-07-17T12:00:00Z'))
})

afterEach(() => {
    vi.useRealTimers()
})

it('keeps the intervention active 59 minutes after its end', () => { ... })
it('drops the intervention 61 minutes after its end', () => { ... })

A grace period tested only far from its threshold (30 minutes before, 3 hours after) still passes if the constant silently changes — the two boundary cases are the ones that pin it.

Do not test the framework

A disabled native button never fires onClick; that is the DOM's contract, not your component's. Test the logic you wrote — the prop wiring, the state transition, the guard — or the case earns nothing.

Permission-gated units

Same matrix as AGENTS.md Step 5.2: drive the permission state as an input (seed the store's permission list, mock the gate hook), cover authorized and refused, assert every enforcement layer through data-test-* hooks. The expected outcome comes from the plan, never from the app's own check.


Table of Contents by Use Case

The Nuxt guide's use-case catalogue applies case-for-case; transpose the mounting (renderWithProviders instead of mountSuspended) and the interaction layer (user-event instead of trigger). Cases that prove React-specific enough to diverge get their own snippet here — propose them via Issue or PR, same template as the Nuxt guide.