Unit, Integration, and Contract Testing for APIs

Introduction

API tests can check business rules, framework and database behavior, consumer-visible contracts, or a complete user flow. Putting each check at the right boundary helps catch real failures without making every test slow and brittle.

This guide compares unit, integration, contract, and end-to-end testing, with examples of behavior assertions and CI verification. It also covers flaky suites, test-data protection, and the trade-offs of mocks versus real dependencies.

Put checks at the right boundary

Think of each test as crossing one observable boundary. A unit test can call a business rule directly, an integration test exercises HTTP routing or persistence, and a contract test checks the serialized exchange a consumer expects. Put the assertion at the narrowest boundary that can expose the failure; add an end-to-end test when the composition itself is what you need to verify.

Example: test observable behavior

Assert the response contract, not private helper calls. This simple test checks that duplicate submission returns the same resource when the API supports an idempotency key.

it("returns the existing payment for a replayed key", async () => {
  const first = await client.post("/payments", payload, {
    headers: { "Idempotency-Key": "order-812" },
  });
  const replay = await client.post("/payments", payload, {
    headers: { "Idempotency-Key": "order-812" },
  });
  expect(first.status).toBe(201);
  expect(replay.status).toBe(201);
  expect(replay.body.id).toBe(first.body.id);
});

When to use each test and when not to

Write many small unit tests for deterministic logic. Add integration tests where framework, database, or protocol behavior matters. Use contract tests when independent consumers and providers must coordinate safely. Keep end-to-end tests for critical paths that genuinely need full composition. Avoid using mocks to prove a database transaction works, and avoid a large end-to-end suite that duplicates every branch already covered lower down.

Verify consumer contracts before deployment

Consumer-driven contracts work best when the contract moves through CI with the code that depends on it. A consumer publishes a versioned contract after its tests pass. The provider build verifies its candidate against active consumer contracts and publishes a result tied to that build. Deployment checks can then confirm that the exact provider version has passed verification for the consumers it serves.

Keep contract ownership explicit. A breaking change should identify affected consumers and give them time to update; remove an old contract only after its consumer no longer relies on it. Contracts should record observable behavior, not internal implementation details. This makes compatibility checks useful without forcing providers to keep obsolete internals forever.

Production failure scenarios and mitigations

Mocks model a successful dependency but the real service returns 429; include error contracts and retry behavior. A test database omits production indexes or constraints; run migrations against the same database engine in CI. Contract tests pass because they share generated types but never exercise wire compatibility; test serialized HTTP payloads. Flaky tests cause teams to rerun and ignore failures; isolate clocks, random values, and external network dependencies, then quarantine only with an owner and expiry.

Observability checklist

• Report test duration, failure category, and responsible boundary.
• Track flaky tests and rerun rate instead of hiding retries.
• Keep contract verification results attached to the build artifact.
• Record which API routes and error cases lack coverage.
• Run a small smoke check after deployment and watch real error rates.

Security notes and pitfalls

Never use production credentials or unrestricted personal data in test fixtures. Keep secret values in a managed CI secret store and rotate them. Test authorization failures and tenant isolation, not only successful requests. Avoid logging full tokens or payloads when a test fails. A common pitfall is asserting only 200; validate schema, permissions, side effects, and useful error semantics.

Trade-Off Table

Security and Compliance Notes

• Use synthetic identities and records; if regulations or incident analysis require production-derived data, document approval, de-identification, access limits, and deletion dates.
• Give CI test identities the narrowest roles needed, and test both allowed and denied operations across tenant boundaries.
• Treat test reports, snapshots, and contract artifacts as data: redact secrets and personal fields, restrict access, and set retention to match their diagnostic value.
• Keep audit-relevant checks reproducible. Record the tested API version and contract artifact with the build, but never include credentials in the artifact.

Common Pitfalls / Anti-Patterns

• Testing only status codes: assert response shape, authorization, side effects, and error semantics so a superficially successful response cannot hide a broken contract.
• Sharing implementation between test and production paths: a fake that calls the same serializer or validation helper may repeat the same defect; exercise the wire format at the integration boundary.
• Treating contract verification as exhaustive: contracts cover recorded consumer expectations, so retain provider tests for behavior consumers have not declared.
• Letting flaky tests become normal: retries can hide nondeterminism; track the owner and expiry for quarantined tests and remove the quarantine after fixing its cause.

Quick Recap Checklist

• Use unit tests for local behavior and integration tests for real component boundaries.
• Verify consumer-visible request, response, and error contracts.
• Keep end-to-end tests small, deterministic, and useful when diagnosing failures.
• Fix sources of flakiness instead of allowing retries to hide them.

Interview Questions

Further Reading

• API contracts explains how to define and evolve consumer-visible guarantees.
• OpenAPI and machine-readable specifications covers describing API shapes in a form that tools can validate.
• API examples, schemas, and error documentation shows how schemas and examples help consumers understand the wire contract.
• Pact documentation explains consumer-driven contracts and provider verification.
• The Practical Test Pyramid discusses balancing test scope, feedback speed, and maintenance cost.

Conclusion

A test suite is useful when each test answers a clear question. Cover local logic quickly, test infrastructure boundaries against real components, and verify consumer contracts before independent releases. Keep full workflows focused so failures remain actionable.