Contract Testing vs Integration Testing: Differences and Examples

Key takeaways

• Contract tests check the interactions a consumer and provider agree to support.
• Integration tests exercise connected components within a defined scope.
• A mock response or schema document alone does not verify that the provider fulfills consumer expectations.
• Both approaches depend on meaningful assertions and accurate test setup.

Contract testing checks compatibility at an interface between a consumer and a provider. Integration testing exercises connected components to check that their interaction works.

The categories can overlap: provider contract verification may execute several real components. The useful distinction is the question being asked and the evidence the test supplies.

Imagine an order-history screen that reads an orders API. The screen depends on response fields and status values. The API depends on database queries and configuration. A field rename and a broken database migration threaten the same feature through different paths.

What a Contract Test Checks

Suppose the client expects an order like this:

{
  "id": "ord_42",
  "status": "shipped",
  "trackingUrl": "https://tracking.example.com/orders/ord_42"
}

The client might require a string ID, recognize a defined set of statuses, and use the tracking URL as a link. A contract can capture those expectations alongside the request method, path, headers, and relevant error responses.

If the provider changes trackingUrl to tracking_link, verification should expose the incompatibility before the client encounters it.

The contract should focus on behavior the consumer relies on. Requiring every incidental field or an arbitrary example ID can make harmless changes fail verification.

Consumer Tests and Provider Verification Work Together

In consumer-driven contract testing, a test exercises the consumer’s API client against a controlled provider substitute. The resulting contract records the interactions the consumer expects.

The provider then verifies those interactions against its implementation. Pact’s consumer guidance explains why tests should exercise request construction and response handling while keeping expectations no stricter than necessary.

Provider verification supplies the other half of the evidence. The provider needs appropriate state for each scenario, such as an existing shipped order or an unknown order ID.

A passing consumer test alone establishes compatibility with the substitute. It does not establish compatibility with the actual provider.

What an Integration Test Adds

An integration test might start the orders API with a real test database, insert an order, request it, and assert the returned values.

That exercises query behavior, mappings, serialization, and the connection between the application and database. It can reveal a missing migration even if a provider contract test uses a stubbed data layer.

Another integration test might use the real consumer client against the running API. The scope should be stated explicitly; “integration test” does not necessarily mean the complete production environment.

A local database test cannot establish that production credentials or routing are correct.

Compare Concrete Failure Modes

Change or failure	Useful coverage
Required response field is removed	Contract verification
Consumer sends the wrong query parameter	Consumer API-client contract test
Database query maps the wrong column	Integration test using the real mapping and database
Update succeeds but is not persisted	Integration test that reads the result back
Gateway drops a required header	Integration coverage including that gateway
UI ignores a valid response	UI or consumer behavior test

An integration test can also detect a removed field if it exercises and asserts that behavior. The distinction is not that each failure belongs exclusively to one category.

A test asserting only HTTP 200 may miss both a wrong response and a broken consumer.

Schema Validation Is Useful but Narrower

A schema can define allowed fields and types. Validating a response against it provides evidence about that response’s shape.

It does not necessarily prove that an actual consumer sends the documented request, handles the response correctly, or agrees with the meaning of a field.

For example, both cents and dollars can be represented by a number. A type-only check cannot resolve a disagreement about units. Include examples or assertions for the semantics that matter.

This is also why a mock server needs a connection to the real interface rather than becoming its own source of truth.

Keep Deployment Evidence Current

Contracts and verification results need to correspond to the versions you intend to deploy. Yesterday’s successful verification against an older provider is not evidence about today’s change.

Keep published consumer expectations current, verify relevant provider changes, and retire contracts deliberately when consumers stop using them.

Contract coverage can reduce the need to repeat every compatibility check in a large shared environment. It does not remove the need for focused tests of persistence, authentication, transactions, and important runtime connections.

Build a Suite Around the Order Journey

For the order-history feature, a practical combination is a consumer contract test for interpreting the response, provider verification for compatibility, a database integration test for retrieval, and a small browser test for rendering.

Each test should contribute distinct evidence. Playwright can check the browser behavior, while the lower-level checks make failures easier to locate.

When the backend is unfinished, API mocking can unblock development. The eventual provider and integration checks are what connect that early work to an implemented system.

Choose a test by the failure it needs to expose, then be explicit about the components it actually exercises.