Pact is a consumer-driven contract testing framework that verifies the interactions between microservices without running all services simultaneously. The consumer writes tests that generate a contract (a ‘pact’), and the provider runs against that contract to confirm it can meet the consumer’s expectations. This catches API breaking changes early before they ever reach a shared environment. Pact supports JavaScript, Java, Python, Go, and more.<\/p>\n\n\n\n
Picture this: your frontend team ships a new build. Everything looks fine locally. Then staging falls over because the user profile API changed a field name and no one knew.<\/p>\n\n\n\n
This is one of the most common and most expensive bugs in microservices architecture. Two teams, two repos, one unspoken assumption and by the time anyone notices, the damage is done.<\/p>\n\n\n\n
That’s exactly the problem Pact contract testing was built to solve. In this tutorial, you’ll learn what Pact is, why it matters more than you might think, and how to write your first consumer-driven contract test in JavaScript step by step.<\/p>\n\n\n\n
Pact is an open-source framework for contract testing between services that communicate over HTTP or message queues. It takes a consumer-driven approach meaning the service that consumes an API (the consumer) defines what it expects, and the service that provides the API (the provider) verifies it can meet those expectations.<\/p>\n\n\n\n
The output of a consumer test is a JSON file called a pact. That pact gets shared with the provider team (usually via the Pact Broker), and the provider runs it against their actual API to check for any mismatches.<\/p>\n\n\n\n Think of a pact like a shared agreement between two teams. The consumer says: ‘I need the \/users\/{id} endpoint to return an object with at least these fields.’ The provider says: ‘Yes, we can do that here’s the proof.’<\/p>\n\n\n\n Microservices move fast. APIs change. And when they do, the teams consuming those APIs are often the last to find out.<\/p>\n\n\n\n The traditional response is a shared integration environment where all services run together. But shared environments are slow, flaky, and expensive. When something breaks, you spend more time figuring out whose change caused it than fixing the actual problem.<\/p>\n\n\n\n Consumer-driven contract testing with Pact gives you something better:<\/p>\n\n\n\n Here’s the complete lifecycle of a Pact contract, from consumer test to deployment:<\/p>\n\n\n\n How does Pact stack up against the alternatives? Here’s an honest comparison:<\/p>\n\n\n\n Let’s say your frontend service calls a \/users\/{id} endpoint on a user service. Here’s the Pact consumer test:<\/p>\n\n\n\n A few things worth understanding in this code:<\/p>\n\n\n\n After this runs, you’ll find a generated JSON pact file in your \/pacts directory. It documents every interaction your frontend expects from the user service.<\/p>\n\n\n\n Now switch to the provider side \u2014 the user service. The provider needs to verify it can meet every interaction in the pact file.<\/p>\n\n\n\n The Pact Broker is a service that stores pact files and verification results. Instead of sharing JSON files by hand, consumers publish their pacts to the broker, and providers pull from it during their CI builds.<\/p>\n\n\n\n You can self-host the Pact Broker (it’s open source) or use PactFlow, the managed SaaS version from the Pact Foundation.<\/p>\n\n\n\n Here’s a scenario that plays out more often than teams like to admit.<\/p>\n\n\n\n A backend team renames the email field to emailAddress on the \/users\/{id} response. They update their own tests, their documentation, and their consumers list \u2014 but they miss the mobile app team, who’s consuming the same endpoint.<\/p>\n\n\n\n Without Pact, this goes to production. The mobile app breaks. Users can’t log in. An incident is raised.<\/p>\n\n\n\n With Pact, the provider verification step fails the moment the provider team changes that field. The CI build for the user service fails. The mobile app’s pact shows exactly which field is missing. The fix happens before any deployment.<\/p>\n\n\n\n [HUMAN EDITOR: Replace this scenario with a real incident from your team or a project you’ve worked on \u2014 the more specific the better. Include the actual field that broke, the services involved, and how long it took to catch before vs. after adopting Pact.]<\/p>\n\n\n\n\ud83d\udcca Data Point <\/strong>Pact has over 4,000 GitHub stars on its JavaScript implementation alone and is used by teams at Atlassian, REA Group, and ITV. The Pact Foundation maintains official client libraries for 10+ languages.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Why Does Consumer-Driven Contract Testing Matter?<\/strong><\/h2>\n\n\n\n
\u26a0\ufe0f Warning <\/strong>End-to-end tests in a shared environment tell you that something is broken. They rarely tell you which service boundary broke it, or when the incompatibility was introduced. That makes debugging expensive.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n \n
\ud83d\udca1 Contrarian Perspective <\/strong>Pact is not magic, and it’s not free. Setting up the Pact Broker, maintaining contracts across teams, and handling versioning adds real overhead. Teams with only 2\u20133 services and good communication might find Pact more process than it’s worth. It pays off most in organizations with 5+ services and independent deployment schedules. [HUMAN EDITOR: Add your team’s actual threshold here]<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n How Does Pact Work? The Full Flow<\/strong><\/h2>\n\n\n\n
\n
\ud83d\udca1 Pro Tip <\/strong>The ‘Can I Deploy’ tool is one of Pact’s most underused features. It queries the Pact Broker and returns a definitive yes or no on whether a given version of your service is compatible with all its known consumers or providers in a specific environment. Add it as a gate in your deployment pipeline.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Pact vs. Other API Testing Approaches<\/strong><\/h2>\n\n\n\n
Approach<\/strong><\/td> Tests In Isolation?<\/strong><\/td> Catches Contract Breaks?<\/strong><\/td> Requires Running All Services?<\/strong><\/td> Best For<\/strong><\/td><\/tr> Unit tests with mocks<\/td> Yes<\/td> No<\/td> No<\/td> Internal logic, not API contracts<\/td><\/tr> End-to-end tests<\/td> No<\/td> Yes (eventually)<\/td> Yes<\/td> Full flow validation<\/td><\/tr> Schema validation (OpenAPI)<\/td> Yes (partial)<\/td> Partially<\/td> No<\/td> Syntax, not behavior<\/td><\/tr> Pact contract testing<\/td> Yes<\/td> Yes (explicitly)<\/td> No<\/td> Service boundary changes in CI<\/td><\/tr> Manual API testing (Postman)<\/td> No<\/td> No (ad hoc)<\/td> Often<\/td> Exploratory, one-off checks<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Step-by-Step: Writing Your First Pact Consumer Test in JavaScript<\/strong><\/h2>\n\n\n\n
Prerequisites<\/strong><\/h3>\n\n\n\n
\n
Step 1 \u2014 Install Pact<\/strong><\/h3>\n\n\n\n
npm install –save-dev @pact-foundation\/pact<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n \u2705 Best Practice <\/strong>Add @pact-foundation\/pact to devDependencies only. Your production bundle should never include testing libraries.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Step 2 \u2014 Write the Consumer Test<\/strong><\/h3>\n\n\n\n
const { Pact } = require(‘@pact-foundation\/pact’);const { like, term } = require(‘@pact-foundation\/pact’).Matchers;const path = require(‘path’);const { fetchUser } = require(‘.\/userClient’);
const provider = new Pact({ consumer: ‘FrontendApp’, provider: ‘UserService’, port: 1234, log: path.resolve(__dirname, ‘logs’, ‘pact.log’), dir: path.resolve(__dirname, ‘pacts’),});
describe(‘User Service – Consumer Tests’, () => { beforeAll(() => provider.setup()); afterAll(() => provider.finalize());
describe(‘GET \/users\/42’, () => { beforeEach(() => provider.addInteraction({ state: ‘user 42 exists’, uponReceiving: ‘a request for user 42’, withRequest: { method: ‘GET’, path: ‘\/users\/42’ }, willRespondWith: { status: 200, body: { id: like(42), name: like(‘Alice’), email: term({ generate: ‘alice@example.com’, matcher: ‘.+@.+\\..+’ }), } } }));
it(‘returns user data’, async () => { const user = await fetchUser(42); expect(user.name).toBeDefined(); expect(user.email).toBeDefined(); }); });});<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n\n
Step 3 \u2014 Run the Consumer Test<\/strong><\/h3>\n\n\n\n
npx jest –testPathPattern=userService.pact.test.js<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Step-by-Step: Running Pact Provider Verification<\/strong><\/h2>\n\n\n\n
const { Verifier } = require(‘@pact-foundation\/pact’);const path = require(‘path’);
describe(‘User Service – Provider Verification’, () => { it(‘validates the expectations of FrontendApp’, () => { return new Verifier({ provider: ‘UserService’, providerBaseUrl: ‘http:\/\/localhost:3000’, pactUrls: [path.resolve(__dirname, ‘..\/consumer\/pacts\/FrontendApp-UserService.json’)], providerStatesHandler: (state) => { if (state === ‘user 42 exists’) { \/\/ seed your test database with user ID 42 } } }).verifyProvider(); });});<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n\u26a0\ufe0f Warning <\/strong>The providerStatesHandler is the part most teams skip and then regret. Without it, provider state setup is inconsistent \u2014 some tests will pass one day and fail the next because the data wasn’t there. Treat provider states as first-class setup code.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n The Pact Broker: Sharing Contracts Across Teams<\/strong><\/h2>\n\n\n\n
Publishing a Pact to the Broker<\/strong><\/h3>\n\n\n\n
npx pact-broker publish .\/pacts \\ –consumer-app-version=$(git rev-parse –short HEAD) \\ –broker-base-url=https:\/\/your-broker.pactflow.io \\ –broker-token=$PACT_BROKER_TOKEN<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Checking If a Version Is Safe to Deploy<\/strong><\/h3>\n\n\n\n
npx pact-broker can-i-deploy \\ –pacticipant FrontendApp \\ –version=$(git rev-parse –short HEAD) \\ –to-environment production \\ –broker-base-url=https:\/\/your-broker.pactflow.io \\ –broker-token=$PACT_BROKER_TOKEN<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n \u2705 Best Practice <\/strong>Run can-i-deploy as a mandatory step in your deployment pipeline \u2014 after all tests pass but before any artifact is promoted. It’s the gate that makes the whole Pact workflow actually safe.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Real-World Scenario: Catching a Breaking Change<\/strong><\/h2>\n\n\n\n
Pros and Cons of Pact Contract Testing<\/strong><\/h2>\n\n\n\n
Pros<\/strong><\/td> Cons<\/strong><\/td><\/tr> Catches breaking changes before deployment<\/td> Adds tooling and process overhead<\/td><\/tr> Tests run in isolation \u2014 no shared environment needed<\/td> Requires buy-in from both consumer and provider teams<\/td><\/tr> Works in CI\/CD with fast feedback loops<\/td> Provider state management can be complex<\/td><\/tr> Supports 10+ languages via official Pact Foundation SDKs<\/td> PactFlow (managed broker) has a paid tier for larger teams<\/td><\/tr> ‘Can I Deploy’ gives deterministic deployment safety<\/td> Learning curve for teams new to consumer-driven contracts<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Best Practices for Pact in Production Projects<\/strong><\/h2>\n\n\n\n
\n