Contract testing and end-to-end (E2E) testing both exist to catch integration bugs. They don’t catch the same bugs, though, and they run at different costs and at different points in the pipeline. So with contract testing vs E2E testing, I’d skip “which one?” and ask “which layer should catch which failure?”
Below I’ll cover what each one checks and where it falls short, then how I’d split the work between them. There’s a decision checklist at the end.
Contract testing vs E2E testing: the short version
An E2E test drives the real system the way a user would. It opens a browser, logs in, places an order, and checks the confirmation. When it passes, you know the whole stack worked together in that environment at that moment.
A contract test checks the agreement between two services. The consumer, say a web app, records what it expects from a provider, say an orders API. The provider then verifies that it still meets those expectations. You don’t need a browser or a full environment.
So E2E tests answer “does the user journey work?” Contract tests answer “can these two services still talk to each other?”
Side-by-side comparison
| Contract testing | E2E testing | |
|---|---|---|
| What it checks | Request and response shapes between a consumer and a provider | A full user journey through the real stack |
| Environment | None shared; each side tests on its own | A deployed environment with all services |
| Speed | Fast (unit-test speed) | Slow (browser plus network plus data) |
| Failure signal | Points to the exact field or endpoint that broke | Shows a symptom; root cause needs digging |
| Catches | Breaking API changes before deploy | UI bugs, config errors, integration and data issues |
| Misses | UI behavior, business logic across services | Problems in paths you didn’t script |
| Typical tools | Pact, PactFlow, Specmatic | Playwright, Cypress, Selenium |
| Ownership | Consumer and provider teams together | Usually QA or a platform team |
What contract tests look like
Here’s a minimal consumer test with Pact JS. The web app declares what it expects from the orders API:
import { PactV3, MatchersV3 } from '@pact-foundation/pact';
import { getOrder } from '../src/api';
const provider = new PactV3({ consumer: 'web-app', provider: 'orders-api' });
test('gets an existing order', async () => {
provider
.given('order 42 exists')
.uponReceiving('a request for order 42')
.withRequest({ method: 'GET', path: '/orders/42' })
.willRespondWith({
status: 200,
body: MatchersV3.like({ id: 42, status: 'PAID' }),
});
await provider.executeTest(async (mockServer) => {
const order = await getOrder(mockServer.url, 42);
expect(order.status).toBe('PAID');
});
});Running the test produces a contract file, which you publish to a Pact Broker or PactFlow. The provider verifies it in its own pipeline, and a release gate checks whether a version is safe to ship:
pact-broker can-i-deploy --pacticipant web-app --version $GIT_SHA --to-environment production --broker-base-url $PACT_BROKER_BASE_URL
# After a successful deploy, record it
pact-broker record-deployment --pacticipant web-app --version $GIT_SHA --environment productionThe pact-broker command comes from the Pact CLI, which you can run as a Docker image or a standalone binary. It isn’t bundled with @pact-foundation/pact, but it does ship as its own npm package, @pact-foundation/pact-cli.

You can also go spec-first. PactFlow’s bi-directional contract testing compares a consumer’s contract with the provider’s OpenAPI spec. Providers don’t write Pact tests, but they still test their API against that spec and upload the results (PactFlow docs). Tools like Specmatic can also check an OpenAPI spec for backward-compatible changes.
What E2E tests look like
An E2E test goes through the UI instead:
import { test, expect } from '@playwright/test';
test('customer can pay for an order', async ({ page }) => {
await page.goto('/orders/42');
await page.getByRole('button', { name: 'Pay now' }).click();
await expect(page.getByText('Payment received')).toBeVisible();
});This test catches things a contract never will, like a broken button, a wrong redirect, or a missing environment variable. But if the orders API renames status to state, this test only tells you that the page broke. You’d still have to dig through logs to find out why.
Why contract testing is still rare
Contract testing sounds like an easy win, but not many teams use it. In Postman’s 2025 State of the API report, only 17% of respondents said they use contract testing, against 67% for functional and integration testing. Postman’s audience is self-selected, but that’s still a big gap.
Download numbers say the same thing. In the week of Sept. 28 to Oct. 4, 2026, @pact-foundation/pact had about 781,000 npm downloads, while @playwright/test had about 86 million, more than 100 times as many (npm trends).
Why the gap? I think it’s more organizational than technical. PactFlow itself says “the number one reason that Pact implementations fail is a lack of buy in” from both consumer and provider teams (PactFlow). If only one side commits, contract testing doesn’t work.
Why E2E alone isn’t enough
What many teams do instead is add more E2E tests to cover integration risk. That gets expensive fast. E2E suites are slow, they need a full environment, and they tend to be flaky.
API changes make that worse. In a 2022 survey of 335 developers and testers, Gruber and Fraser identified undocumented API changes as one of three causes of flaky tests that hadn’t been reported before (arXiv 2203.00483). So a provider changes a field without warning, the E2E suite goes red, and someone loses an afternoon working out why. A contract test would have flagged that exact field before the deploy.
Where API and integration tests fit
Contract testing vs E2E testing isn’t really a two-layer choice. There’s a wide middle layer of API and integration tests. These tests call a real service, often with a real database, and check business behavior. Does a refund update the balance? Does an expired token get a 401?
Contracts don’t do that. A contract checks that the response has a status field of the right type. It doesn’t check that the status is correct for a given business rule. That’s what API and integration tests are for.
So a healthy setup usually has three layers:
- Contract tests for the shape of each service boundary
- API and integration tests for business rules within a service
- A small set of E2E tests for the journeys that make or lose money

Common contract testing mistakes
If you do adopt contract testing, these are the mistakes I’d watch for:
- Treating contracts as functional tests. Contracts should describe what the consumer needs, not every rule the provider enforces.
- Over-specifying values. Use matchers like
like()to check shapes, not exact values. Otherwise every data change breaks the contract. - Skipping provider states. States such as “order 42 exists” let the provider set up data for each interaction. Without them, verification gets brittle.
- No release gate. Contracts only protect you if a check like
can-i-deployactually blocks unsafe releases.
My take: how I’d split the work
I’d spend E2E tests sparingly. Every consumer-provider pair that changes often gets a contract, checked in CI before deploy, because that’s the cheapest place to catch a broken field. E2E tests are the expensive ones, so I’d save them for a few critical journeys like login, checkout, and payment, and keep that set small and stable. Business logic goes to API and integration tests, which are faster than E2E and broader than contracts.
The point is to stop using E2E tests as your only integration check. Let contracts catch shape changes early, and let E2E confirm the journeys users care about most.
And start small. You don’t need contracts for every service on day one. Pick the one integration that breaks most often, add a consumer contract, and wire up the release gate. If that saves you a few red builds, expand from there.
Contract testing vs E2E testing decision checklist
Go through these for each integration risk:
- Do two services owned by different teams change independently? Use a contract test.
- Is the risk in the user journey, UI behavior, or configuration? Use an E2E test.
- Do you already have OpenAPI specs? Consider a spec-first contract approach (for example, bi-directional contract testing, a PactFlow feature).
- Will both the consumer and provider teams maintain contracts? If not, sort out buy-in first.
- Is this a critical revenue path? Keep at least one E2E test for it.
- Does the E2E suite often fail after backend deploys? That’s a sign you’re missing contracts.

Keep reading
If you’re still choosing the browser tool that will run those E2E tests, start with Playwright vs Selenium.

[…] a tool, the next question is which test layer should catch which failure, and that’s where contract testing vs E2E testing comes […]
[…] a UI test the right way to check a JSON contract; that’s a coverage question, covered in contract testing vs E2E testing. Once the layer is right, these are the questions I’d ask of a new […]