Instruction file imported from E2E-Solution/ai-led-sdlc-starter-template-for-github-copilot (.github/instructions/tests.instructions.md). Copyright stays with the author.

Test rules

Framework

• Unit tests: Vitest. Run with pnpm test.
• End-to-end tests: Playwright under e2e/. Run with pnpm test:e2e.
• React component tests use @testing-library/react. Query by accessible role first, then label, then test id as a last resort.

Structure

• One describe block per unit under test. Nest describe blocks for scenarios.
• Test names: it("returns X when Y") — describe the behaviour, not the implementation.
• Arrange / Act / Assert. Blank line between sections in non-trivial tests.

Data

• Use factory functions in tests/factories/ to build test fixtures. Do not hand-roll the same object in 10 tests.
• Never use real customer data, even anonymised. Generate with faker or fixed-seed factories.
• Integration tests hit a real test database — do not mock Prisma. Reason: mock/prod divergence has masked broken migrations in the past.

Mocking

• Mock at the network boundary (msw for HTTP) or at clear module seams.
• Do not mock the unit you are testing.
• Reset mocks between tests (beforeEach or Vitest's restoreMocks: true).

Assertions

• Prefer specific matchers (toEqual, toMatchObject) over toBe for objects.
• Snapshot tests only for stable, well-named outputs. Never snapshot whole component trees.

Avoid

• test.skip and test.only committed to main.
• Sleeping (await new Promise(r => setTimeout(r, 1000))) — use vi.useFakeTimers() or Testing Library's waitFor.
• Tests that depend on execution order.