Seagull Testing Guide

Quick start (default approach)

When implementing a feature that touches backend/frontend:

1. Classify behavior:

   • service semantics (pure rules): put tests near the service
   • cross-layer behavior (tRPC + react-query + cache invalidation + timers): use packages/test-integration
   • deployment-shape behavior (real Postgres + pooling + true concurrency): run strict smoke tests pre-release

2. Prefer real integrations over hook mocks:

   • Do not mock useMutation when the goal is react-query/tRPC integration.
   • Only mock/alias platform-only deps (Expo/RN modules that break node/jsdom).

3. Use header-injected identity for multi-user tests:

   • Client: set httpBatchLink({ headers: () => ({ 'x-test-user-id': userId }) })
   • Server: in createContext({ headers }), read headers.get('x-test-user-id')