Contract Testing

What it is

A contract test verifies that a consumer and a provider agree on their interface — the request/response shapes, status codes and events between two services — without deploying both together.

The consumer records its expectations as a contract (a pact). The provider runs that contract against its real implementation. If both pass, the integration is safe to ship.

1
  Consumer test  ──►  pact file  ──►  Provider verification
2
   (expectations)      (JSON)          (runs real provider)

This replaces fragile end-to-end environments with fast, independent checks — a natural fit for microservices and mobile/backend boundaries.

When to use it / when to avoid it

Use it for

Microservices and any consumer/provider split across teams
Mobile app against a backend API
Any interface where “we think we agree” is the risk

Avoid it when

There is one deployable, so a normal integration test is simpler
The API is trivial and stable and a schema test suffices

Frameworks & tools

Tool	Ecosystem	Notes
Pact	Multi (JS, Java, Go, .NET, Python, Ruby)	The de-facto standard; broker for sharing
PactFlow	Multi	Hosted Pact broker + can-i-deploy
Spring Cloud Contract	Java	Producer and consumer verification
Schemathesis	Multi	Property-based testing from OpenAPI schemas
Dredd	Multi	Validate implementations against OpenAPI/API Blueprint
Postman / Newman	Multi	Contract assertions in collections

Quick setup

1
npm install -D @pact-foundation/pact

1
<dependency>
2
  <groupId>au.com.dius.pact.consumer</groupId>
3
  <artifactId>junit5</artifactId>
4
  <version>4.6.15</version>
5
  <scope>test</scope>
6
</dependency>

1
go get github.com/pact-foundation/pact-go/v2

1
pip install pact-python

1
dotnet add package PactNet

Example

1
import { PactV3, MatchersV3 } from '@pact-foundation/pact';
2
const { like, integer } = MatchersV3;
3

4
const provider = new PactV3({ consumer: 'web', provider: 'users-api' });
5

6
it('gets a user by id', async () => {
7
  provider
8
    .given('user 42 exists')
9
    .uponReceiving('a request for user 42')
10
    .withRequest({ method: 'GET', path: '/users/42' })
11
    .willRespondWith({
12
      status: 200,
13
      body: { id: integer(42), name: like('Ada') },
14
    });
15

16
  await provider.executeTest(async (mock) => {
17
    const user = await getJson(`${mock.url}/users/42`);
18
    expect(user.name).toBe('Ada');
19
  });
20
});

1
@ExtendWith(PactConsumerTestExt.class)
2
class UserConsumerTest {
3
  @Pact(consumer = "web", provider = "users-api")
4
  public RequestResponsePact user42(PactDslWithProvider builder) {
5
    return builder
6
      .given("user 42 exists")
7
      .uponReceiving("a request for user 42")
8
      .path("/users/42")
9
      .method("GET")
10
      .willRespondWith()
11
      .status(200)
12
      .body("{\"id\":42,\"name\":\"Ada\"}")
13
      .toPact();
14
  }
15
}

1
pact.
2
  AddInteraction().
3
  Given("user 42 exists").
4
  UponReceiving("a request for user 42").
5
  WithRequest(dsl.Request{Method: "GET", Path: "/users/42"}).
6
  WillRespondWith(dsl.Response{Status: 200})

Anti-patterns & best practices

One contract per consumer. Each consumer owns its own expectations.
Use matchers, not exact values. like('Ada') is not the point; the shape is.
Version the contract and share it via a broker. Then ask “can I deploy?” before release.
Do not contract-test internal functions — only the network boundary counts.
Gate deploys with can-i-deploy so a provider is only released if all consumer contracts still pass.