Quality & Testing · master area

Integration Testing

Wires several modules together with real (or near-real) dependencies. Catches the wiring mistakes no unit test sees — the assumptions about how other components behave that only fail in contact.

Owners: QA, Developer Phase it lives in: How We Build (Volume IV) The corpus principle this enacts: The pipeline catches a different chain level at each stage.

Where it lives in the chain

• How We Build · Testing as Chain Verification — the canon
• How We Build · The Pipeline — integration runs at its own stage

How to do this

Integration tests wire components together — a service plus its database, a frontend plus its API, a workflow plus its queue — and exercise the flow through them:

• Real dependencies where possible — a real Postgres in a container, not a mock.
• Test doubles only at the system boundary — the third-party payment provider is mocked; everything inside is real.
• End-to-end scenario — the Gherkin scenario from amigos runs through the entire flow, not against one layer.
• Idempotent setup — every test owns its data, sets it up, tears it down. No shared state.

What good practice looks like

The wallet bug would have been caught at integration if the test asked "given a user with a negative balance, what does the dashboard display?" Instead the test asked "given a user with a positive balance, what does the dashboard display?" — the happy path. The boundary scenario was missing from amigos, so the integration test was missing too, so the bug shipped to staging where exploratory testing caught it.

Integration testing is the layer that catches integration-gap — the chain-aware label for two systems specified to work together that don't. The JWT outage was an integration-gap that the pipeline missed because there was no integration test for token-claim compatibility. The fix from the postmortem was a new integration test.

The discipline: the integration test is the chain's verification that the brief's flow works end-to-end. Unit tests verify the logic; contract tests verify the boundaries; integration tests verify the travel between them.

Related crafts

• Contract Testing — the layer below
• Integration Design — what the tests are testing
• Unit Testing — the layer below that