testing-guidelines

# Testing Guidelines ## Frameworks and Setup Unit tests use Vitest with jsdom. Component tests use `@testing-library/react`. Global setup lives in `src/test/setup.ts`. Test files colocate with source: `*.test.ts` for utilities, `*.test.tsx` for components. ## Running Tests - `npm run test` runs type-check, lint, vitest, and build. Use this before pushing. - `vitest run` for tests only. - `vitest` for watch mode during development. - `npm run test:visual` runs Playwright visual regression tests. - `npm run test:visual:update` updates visual snapshots. ## Assertion Style Favor user-facing assertions: `getByRole`, `getByText`, `getByLabelText`, `getByPlaceholderText`. Query by what the user sees and interacts with. Avoid testing implementation details. No direct state access. No querying by `data-testid` unless no user-facing alternative exists. ## Mocking Mock browser APIs (`window.location`, `fetch`, `IntersectionObserver`, etc.) as needed. Use `vi.fn()` for spies and `vi.mock()` for module mocks. Keep mocks minimal and scoped to the test file. Reset mocks between tests with `vi.restoreAllMocks()` or per-test cleanup. ## Determinism Tests must be deterministic. No relying on real timers, network calls, or shared mutable state. Use `vi.useFakeTimers()` for time-dependent logic. Isolate each test so it can run independently in any order. ## Rules - Do not commit failing tests. Fix before pushing. - Add or update tests alongside any feature change or bug fix. Tests are not optional. - If a test is temporarily skipped, it must have a linked issue: `it.skip('description #123')`.