Skip to content

Integration Testing Guide

Write the failing integration test first.

Integration tests verify that pieces of the system work together: HTTP → service → database → response.

Where Things Live

apps/backend/src/
  some.controller.spec.ts   ← integration test next to the controller
Each test file gets a fresh in-memory Postgres - no Docker needed.

apps/solver/tests/
  test_contract.py   ← NestJS ↔ FastAPI contract tests

Tools

Layer Tool Focus
API → DB Jest + PGLite Controller, Service, and ORM integration
Microservices FastAPI NestJS ↔ FastAPI contracts

What to Run

pnpm run test:int             # all integration tests

What to Worry About

Test isolation

PGLite is fresh per file, but state leaks between tests within the same file. Always use beforeEach to reset data. Never rely on test execution order.

What belongs here vs unit tests

An integration test must cross a real boundary (HTTP → service, service → DB). If you're mocking the database, it's a unit test - move it.

Fixtures

Keep seed data minimal. Only insert the exact rows your test needs.

Definition of Done

Integration Test Checklist
  • [ ] Failing test written before the feature.
  • [ ] Full path covered: Request → Service → DB → Response.
  • [ ] Each test file is fully isolated - no shared state.
  • [ ] External HTTP calls (solver, third-party) are mocked.
  • [ ] Suite passes locally (pnpm run test:int).