integration-testing

Integration testing

Unit tests prove each piece works against your assumptions about its neighbours. Integration tests prove the assumptions were right. Almost every "all tests pass but production is broken" story lives in that gap — a mock that returns a shape the real service never returns.

These cost more than unit tests and less than end-to-end. Spend them on the seams where your assumptions about someone else's behaviour are most likely wrong.

1. Pick the seams worth the cost

Test the boundaries where you cross into something you do not control:

• Your code against a real database: queries, migrations, transactions, constraints. The highest-value integration tests in most applications, because SQL and ORM behaviour is where mocks lie most.
• Your service against its dependencies: real HTTP, real serialization.
• Message producers against consumers: that the payload one writes is one the other parses.
• Your code against the filesystem, clock, or queue, where behaviour is subtle.

Do not integration-test pure logic. If it has no boundary, it belongs in a unit test.

Done when: each planned test crosses a boundary you do not own.

2. Use the real thing, not a mock

The entire point is exercising real behaviour. A mocked database tests your mock.

• Containers for infrastructure: a real Postgres, Redis, or Kafka in a container. Testcontainers-style libraries make this a few lines and it is worth it.
• The same version as production. Testing on a different major version tests a different system.
• Real HTTP against a local instance where you can run the dependency; a recorded or contract-verified stub where you cannot.

For third-party services you cannot run: record real responses once, replay them, and re-record on a schedule. A hand-written stub drifts from reality silently and gives false confidence indefinitely.

Done when: no test in this suite mocks the thing it is testing against.

3. Make each test own its data