api-integration-test

When to trigger

• The implementing agent authors integration tests for a spec whose ACs require database-state assertions, queue-dispatch verification, or audit-event rows.
• Test files live under the api package's integration-test directory (e.g. test/*.integration.test.ts).
• A spec's acceptance criteria reference: cookie Max-Age bounds, Retry-After headers, non-enumeration assertions, audit-event table rows, or queue add side effects.
• The operator says "author integration tests", "write API integration tests", or "add integration coverage for ".

Procedure

1. Confirm the live stack is reachable. Boot the project's local development stack and verify the API health endpoint responds before writing any test. Integration tests require the real backing services (database, cache, queue) running — they FAIL against mocked services. The boundary rule: if a test could run without a real database, it is a unit test; route to vitest-unit instead.

2. Use app.inject() as the default invocation form. Fastify's app.inject({ method, url, headers, payload }) dispatches requests through the full route-handler stack without opening a real socket. This is faster than supertest + an HTTP server and avoids port-collision issues in parallel test runs. Reserve real-socket (app.listen() + fetch()) only when the test exercises HTTP/2 or WebSocket behavior that inject() cannot simulate.

3. Establish per-test isolation. Choose one of two strategies:

   • Transaction rollback (preferred for speed): wrap each test in a database transaction via BEGIN; roll back in afterEach. Works when the code under test does NOT commit in a nested transaction.
   • Table truncation (required for tests that commit): in afterEach, truncate all affected tables in reverse-FK order. Slower but universally safe. Additionally, namespace test-generated data to prevent bleed between parallel runs: prefix email addresses with the test-file slug, prefix IP addresses with a test-run ID, and prefix queue job IDs where applicable.