Mocking strategy documented

Unit tests that call real external services — databases, APIs, email providers — are not unit tests: they are slow, flaky, and environment-dependent. ISO 25010:2011 §6.5.5 requires that tests produce deterministic results. Without consistent mocking, a failing test might be a real bug, a network blip, a rate limit hit, or a service outage — and distinguishing between them wastes engineering time. Real API calls in tests also risk leaking test data to production systems or incurring costs from development runs.

Adopt a consistent mocking strategy. For HTTP calls, msw (Mock Service Worker) intercepts at the network layer and works with any fetch-based code:

// tests/mocks/handlers.ts
import { http, HttpResponse } from 'msw'

export const handlers = [
  http.get('/api/users/:id', ({ params }) => {
    return HttpResponse.json({ id: params.id, name: 'Test User' })
  }),
  http.post('/api/users', () => {
    return HttpResponse.json({ id: 'new-id' }, { status: 201 })
  }),
]

For module-level mocking in Vitest:

vi.mock('@/lib/email', () => ({
  sendEmail: vi.fn().mockResolvedValue({ success: true }),
}))

Store reusable fixture data in tests/fixtures/ as typed constants or JSON files.

• ID: code-quality-essentials.testing.mocking-strategy

• Severity: low

• What to look for: Check test files for consistent use of mocking patterns to isolate the unit under test. Look for vi.mock() (Vitest), jest.mock() (Jest), or manual mock files in __mocks__/ directories. External service dependencies (API calls, database access, email sending, third-party SDKs) should be mocked in unit tests — not called for real. Also check for fixture data files: JSON files or TypeScript constants in __fixtures__/, tests/fixtures/, or similar directories that provide consistent test data. If tests appear to call real external services (no mocking setup, no HTTP interceptors like msw), flag this as a test isolation problem.

• Pass criteria: Enumerate all relevant code locations. Unit tests use vi.mock/jest.mock or similar to isolate external dependencies. Mock data fixtures are present and reusable. External HTTP calls in tests use MSW or a fetch mock with at least 1 verified location.

• Fail criteria: Unit tests appear to call real external services or APIs without mocking. No fixture data. Mocking is entirely absent.

• Skip (N/A) when: No test files exist.

• Detail on fail: "Unit tests appear to call real APIs without mocking; no mock files or fixtures found in test directories"

• Remediation: Adopt a consistent mocking strategy. For HTTP calls, msw (Mock Service Worker) is the gold standard:

  // tests/mocks/handlers.ts
  import { http, HttpResponse } from 'msw'
  
  export const handlers = [
    http.get('/api/users/:id', ({ params }) => {
      return HttpResponse.json({ id: params.id, name: 'Test User' })
    }),
    http.post('/api/users', () => {
      return HttpResponse.json({ id: 'new-id' }, { status: 201 })
    }),
  ]
  

  For module mocking in Vitest:

  vi.mock('@/lib/email', () => ({
    sendEmail: vi.fn().mockResolvedValue({ success: true }),
  }))