Testing guide

This is the why of testing in CommunityRule. For file layout, helper APIs, and required imports see .cursor/rules/testing.mdc.

Philosophy

Test behaviour, not implementation. Assert on what a user can see and do (visible text, roles, labels, keyboard paths). Avoid leaning on internal class names, hook internals, or memoization details.
One consolidated file per component. A component's standard suite, variant assertions, and behaviour-specific cases all live in tests/components/<Name>.test.tsx.
Accessibility is non-negotiable. Every component suite runs jest-axe; full-page WCAG runs in Playwright. A failing axe check is a failing build.
E2E is sparse and high-signal. Playwright covers critical journeys, visual regression of major pages, and a handful of edge cases — not per-component clicks. Component coverage is the job of Vitest.

Layered coverage

Layer	Tool	Scope
Unit	Vitest	Pure logic, reducers, utilities (`tests/unit/`).
Component	Vitest + RTL	DS components in isolation (`tests/components/`).
Page / context	Vitest + RTL	Screens and provider wiring (`tests/pages/`, `tests/contexts/`).
Accessibility (page)	Playwright + axe	WCAG 2.1 AA on key pages (`tests/accessibility/e2e/`).
E2E	Playwright	Critical journeys, visual regression, edge cases (`tests/e2e/`).

What to test vs. skip

Test:

Public behaviour — visible text, roles, ARIA, keyboard activation.
State transitions users observe (error → success, disabled → enabled).
Interaction contracts (click handlers, form submission, dropdown selection).
Accessibility invariants.

Skip:

Pure styling that changes with the design system (exact shadow radius, minor spacing).
Hook internals or memoization specifics.
Responsive visibility in JSDOM — use Playwright instead.

Running tests

npm test                  # vitest run with coverage
npm run test:component    # vitest, components only (faster inner loop)
npm run e2e               # playwright (alias: test:e2e)
npm run visual:update     # refresh playwright screenshots after UI changes

Adding tests for a new component

Create app/components/<Name>/.
Create tests/components/<Name>.test.tsx and call componentTestSuite (see .cursor/rules/testing.mdc).
Add behaviour-specific describe blocks for any unique interactions.
Run npm run test:component -- --run tests/components/<Name>.test.tsx.

Storybook is documentation, not tests

Stories are visual examples for design review and Code Connect — they do not replace component tests. Run npm run storybook locally to browse.

2.7 KiB Raw Blame History