Pact review: contract testing tutorial and pricing

In a consumer test you describe an interaction: given a provider state, upon receiving a request, the provider will respond with a certain response. Pact starts a mock server on a local port, your real API client calls it, and the mock checks the request and returns the response you described. If the test passes, Pact writes the interaction into a JSON pact file named after the consumer and provider. Because only interactions the consumer’s code actually exercises end up in the file, the contract records what the consumer uses, not everything the provider offers. That is what consumer-driven means, and it is why providers can change unused fields freely.

Provider verification takes the pact files, fetches them from a Broker or reads them locally, and replays each request against a running instance of the real provider. Before each interaction it calls a provider state handler, code you write that puts the provider into the state the interaction names, such as a payment that exists or a user who is not authenticated. The verifier then compares the real response with the contract using its matching rules. Each side runs in its own pipeline, at its own pace, and neither needs the other deployed. The cost is that state handlers are real test code that must keep pace with the provider’s data model.

A contract that demanded exact values would break whenever test data changed. Matchers record the shape instead: like says any value of the same type, eachLike says an array whose items look like this one, and integer, string, regex and datetime constrain specific fields. The example values are what the mock returns to the consumer; the rules are what the provider is checked against. Over-specifying is the classic mistake, because asserting exact values or fields the consumer never reads turns a contract test into a brittle functional test of the provider.

The Pact Broker stores every published pact and verification result against application versions, branches and environments. From that it builds a matrix of which consumer versions have been verified against which provider versions. can-i-deploy queries the matrix before a release: given this version and the target environment, have all the integrations it depends on been verified against what is deployed there? record-deployment then tells the Broker what was released. Webhooks let a changed pact trigger the provider’s verification build. The Broker is open source; PactFlow is the hosted commercial version from SmartBear with extra features.

Put Pact tests next to the API client they cover, one file per provider, and include only the requests the consumer really makes and only the response fields it really reads. Use type matchers for values and regex or datetime matchers for formats, and keep exact values for things the consumer genuinely depends on, such as an enum it switches on. Name provider states as facts about data, such as payment 42 is authorised, not as steps, so the provider team can implement them once and reuse them. Prefer one interaction per meaningful response, including the error responses your client handles, because untested error shapes are where contract surprises tend to sit.

The provider’s verification test starts the service, or a test instance of it with external dependencies stubbed, and points the Verifier at the Broker. The consumer version selectors recommended by the Pact docs fetch the main branch of each consumer, every version currently deployed or released, and any consumer branch with the same name as the provider branch. Enable pending pacts so a consumer’s new expectation does not break the provider build, and publish verification results only from CI, with the git commit as the provider version and the branch name set, which can-i-deploy relies on.

On the consumer side the pipeline has three jobs to do: run the Pact tests, publish the pact files with the commit as the version and the branch name, and, before deploying, ask can-i-deploy. The Rust pact-broker-cli is the current command-line client and has an official GitHub Action that installs it, pinned through the action ref. With PactFlow, authenticate with an API token in PACT_BROKER_TOKEN; the open-source Broker takes PACT_BROKER_USERNAME and PACT_BROKER_PASSWORD instead. After a successful deployment, call record-deployment so the Broker knows what is in each environment, otherwise deployedOrReleased selectors and can-i-deploy have nothing to compare against.

Start with one consumer and one provider that change often and break each other, not with the whole estate. Get the full loop working there, consumer test, publish, provider verification, can-i-deploy and record-deployment, before adding more integrations, because a half-built loop gives a false sense of safety. Create the environments in the Broker first, since can-i-deploy and record-deployment refer to them by name. Set up a Broker webhook so a changed pact triggers the provider’s verification build; without it, the consumer waits for the provider’s next unrelated commit. Agree who owns a failing verification: the consumer who changed an expectation, or the provider who changed behaviour.

Pact checks that requests and responses have the shape both sides expect for the interactions the consumer exercises. It does not check business rules in the provider, performance, or what happens across three services in a real environment. Keep functional tests in the provider’s own suite, keep a thin layer of end-to-end journeys for the paths that matter most, and use a mock server such as WireMock for failure cases like timeouts that a contract does not describe. Contract tests make that end-to-end layer smaller and less flaky; they rarely remove it entirely.