Test

Test

Pick the Right Layer First

Writing tests at the wrong layer is the most common testing mistake. A unit test that mocks everything doesn't catch integration bugs; an E2E test for a pure function is slow and fragile.

The pyramid holds: many units, fewer integrations, minimal E2E. Done only when the selected layer is named and justified.

Detect the Framework

Check before choosing:

cat package.json | grep -E '"jest"|"vitest"|"mocha"|"jasmine"'
cat pyproject.toml | grep -E 'pytest|unittest'
cat Gemfile | grep rspec

Don't assume Jest. Vitest is increasingly common in Vite/Next.js projects. Mixing test runners in a project is rarely intentional. For unfamiliar stacks, inspect project config and docs before writing tests.

Universal Quality Checks

• Tests cover error paths and edge cases, not just the happy path
• Tests verify behavior, not implementation — if you rename a private method, tests shouldn't break
• Mocks are used sparingly — over-mocking makes tests pass while real code breaks
• Test names read like specs: should return 404 when user is not found beats test user endpoint
• AAA pattern: Arrange → Act → Assert, with a blank line between sections

Red-Green-Refactor Flow (when requested)

1. Red — write a failing behavioral test that describes the desired behavior; done only when the relevant test command fails for the expected reason
2. Green — write the minimal code to make it pass; done only when the same command passes
3. Refactor — clean up while keeping tests green; done only when the command still passes after cleanup

Integration Test Methodology

Integration tests validate service boundaries — not business logic (that's unit tests) and not full user flows (that's E2E).

What to test at this layer:

• API endpoints: request/response structure, auth, error codes
• Database queries: ORM behavior, transactions, constraint violations
• Service-to-service contracts (Pact consumer-driven contract tests)
• Message queue consumers and event handlers

Data isolation — non-negotiable:

• Wrap each test in a transaction and roll back, or reset the test DB between runs
• Tests that share state cause order-dependent failures — the hardest class of flakiness to debug
• Mock third-party APIs, not your own services

Load references for runner-specific APIs, mocks, environments, MSW, Browser Mode, snapshots, type testing, coverage, and configuration.

E2E Test Methodology

E2E tests are expensive. Use them only for critical paths: checkout, auth, onboarding, file upload. Prefer accessible selectors, smart waits, unique test data, and cleanup via API or DB reset. Cover edge cases in unit/integration tests, not E2E.

Common Pitfalls

• Testing the mock, not the code — if the test only asserts a mock was called, it may not test behavior
• Fragile E2E selectors — use roles or stable test IDs instead of layout selectors
• No cleanup in integration tests — shared DB state causes order-dependent failures
• Snapshot tests as a crutch — use snapshots only for stable, serializable outputs

Completion Gate

Complete test work only after:

• the selected layer is named
• the relevant test command has been run
• failures are either fixed or reported with evidence
• new tests would fail against the old behavior when that can be checked
• red/green command output is reported for TDD work

References