Skip to main content
The Case for Contract Testing — Anselm Fowel
AI & Technology

The Case for Contract Testing

9 min read
647 views
Share:

In 2019 we shipped a payment settlement service that talked to nine internal systems. The team that owned the ledger changed a field from a nullable string to a required one on a Thursday afternoon. Their unit tests passed. Their integration tests passed. Ours passed too, because we were testing against a mock we had written eight months earlier that still had the old shape. The mismatch surfaced in production at 6 a.m. the next morning, when the reconciliation batch tried to post entries that no longer validated, and a few thousand transactions sat in limbo until someone paged me.

The Case for Contract Testing
The Case for Contract Testing

Nobody wrote a bad test. Everyone tested the thing they owned. The gap was in the space between the two services, which is precisely the space nobody was testing. That is the problem contract testing exists to solve, and after a decade of watching integration failures eat weekends, I have become fairly opinionated about it.

What a contract actually is

A contract is a machine-checkable agreement about the shape of the messages passing between two services. Not a Confluence page. Not a Slack thread where someone said "yeah the API returns a customer object." An artifact, versioned in source control, that both sides run against. The consumer declares: given this request, I expect a response with these fields, these types, this status code. The provider proves it can honor that expectation.

The distinction I care about most is that a contract is written from the consumer's point of view. It captures only what the consumer actually uses. If the payments service ignores fourteen of the twenty fields the customer API returns, the contract says nothing about those fourteen. That sounds like a weakness. It is the whole point. It means the provider can change the fields nobody consumes without ceremony, and the moment they touch a field somebody does depend on, a build goes red.

Why mocks lie to you

Every team that integrates against another service ends up with a stub or a mock of that service, because you cannot run the whole company's infrastructure on your laptop. That mock is a fossil. It records what you believed the other service did on the day you wrote it. Nothing forces it to stay accurate, and services drift. Field renamed. Enum value added. A 200 that quietly became a 202. Your mock keeps returning the fossil, your tests keep passing, and your confidence is entirely counterfeit.

Contract testing is the mechanism that keeps the mock honest. The same contract that generates your local stub is replayed against the real provider in the provider's own pipeline. If the provider can no longer satisfy it, the provider's build fails before their change ever reaches you. The mock and the reality are pinned to the same document. That is the trick, and it is a genuinely good one.

A test that never fails when the world changes is not a test. It is a decoration that happens to be green.

Consumer-driven is the version that works

There are two broad flavors. Provider-driven, where the team that owns the API publishes a spec and consumers are expected to conform to it. And consumer-driven, where each consumer publishes the subset it needs and the provider must satisfy the union of all of them. I have run both. Consumer-driven wins, and it wins for a reason that is more organizational than technical.

Provider-driven contracts describe intent. Consumer-driven contracts describe usage. The gap between what a provider thinks its consumers need and what they actually call is enormous, and it is always full of surprises. When we switched a customer-facing onboarding flow to consumer-driven contracts, we discovered three downstream teams depending on a debug field we had scheduled for deletion. The provider spec never mentioned it. The contracts did, because someone was actually reading it. We would have broken all three.

The cost is real: consumers have to do work, and someone has to run a broker to store and share the contracts. But the payoff is that the provider knows, with certainty, who depends on what. In a regulated environment where a bad deploy to a payments path is a reportable incident, that certainty is worth a great deal.

What it looks like in practice

Here is a consumer test in .NET using Pact. The consumer, a settlement service, states exactly what it needs from the customer API. Notice how little it asks for.

[Fact]
public async Task GetCustomer_ReturnsSettlementFields()
{
    _pact.UponReceiving("a request for an active customer")
        .Given("customer 4471 exists and is active")
        .WithRequest(HttpMethod.Get, "/customers/4471")
        .WillRespond()
        .WithStatus(HttpStatusCode.OK)
        .WithJsonBody(new
        {
            id = Match.Type("4471"),
            status = Match.Regex("active", "active|suspended"),
            settlementAccountId = Match.Type("acct_88a2")
        });

    await _pact.VerifyAsync(async ctx =>
    {
        var client = new CustomerClient(ctx.MockServerUri);
        var customer = await client.GetAsync("4471");
        Assert.Equal("active", customer.Status);
        Assert.False(string.IsNullOrEmpty(customer.SettlementAccountId));
    });
}

That test generates a contract file. The contract goes to a broker. The customer API's pipeline pulls every contract published against it and replays each interaction against the real provider, with the "customer 4471 exists and is active" state set up beforehand. Three fields are under contract. Everything else the customer API returns is free to change. If someone renames settlementAccountId, the provider's verification fails and names the consumer that will break.

Enjoying this article?

Get more like it in your inbox — practical engineering leadership, fintech, and AI. No spam, unsubscribe anytime.

The provider state problem

The hardest part of contract testing is not the contract. It is the phrase "customer 4471 exists and is active." The provider has to be able to conjure that state on demand during verification. That means provider state handlers: little hooks that seed a database, stub an internal dependency, or flip a feature flag so the described precondition holds.

This is where teams give up, and I understand why. Setting up realistic state for a service with a tangled data model is genuine work. But it is work that pays a second dividend, because those state handlers are the clearest documentation you will ever have of the preconditions your API actually depends on. When we forced ourselves to write a handler for "account is over its credit limit," we found two code paths that assumed the check happened upstream and did not re-validate. That was a latent bug worth more than the test that surfaced it.

Where I don't use it

Contract testing is not a religion, and I have seen it applied where it does more harm than good. A few honest limits:

  • Third-party APIs you don't control. You cannot make Stripe run your contract in their pipeline. For those, use recorded interactions and a scheduled canary that hits the real sandbox, not a contract.
  • Deep semantic behavior. A contract proves the shape of the response, not that the interest calculation is correct. It will happily verify a beautifully typed wrong number. Business logic still needs its own tests.
  • Rapidly prototyping internal tools where both sides are one team behind one deploy. The overhead outweighs the drift risk when there is no real boundary.
  • Event choreography with many optional fields and loose schemas. Contracts can work here, but the effort curve is steep, and a schema registry may serve you better.

The value scales with the cost of the boundary. Two teams, separate deploy cadences, a payment or ledger path between them: that is the sweet spot, and it is exactly where an integration failure hurts most.

The cultural shift it forces

The technical setup is a weekend. The cultural change is the real project. Contract testing moves the moment of failure from "consumer's runtime, in production, at 6 a.m." to "provider's pipeline, before merge." That is a redistribution of pain, and the people who now feel the pain earlier are not always the people who caused it.

Provider teams initially hate this. Their build now fails because of a consumer they have never met, over a field they consider an implementation detail. The reframe that lands is ownership: if your consumers depend on it, it is not an implementation detail, it is your public surface, and you should know when you are about to break it. Once a provider team has been saved from a bad deploy two or three times by a red contract build, the resentment fades. They start treating the list of consumers as a feature, not a burden.

Rolling it out without a big bang

Do not try to contract-test every integration in the company at once. That is how these initiatives die in a steering committee. Pick the single boundary that has caused the most production incidents in the last year. You almost certainly already know which one it is; every organization has that one integration that everybody dreads touching.

Put contracts on that boundary, wire the broker into both pipelines, and let the first prevented incident make your case for you. When we did this, the first genuine catch came within three weeks: a provider changed a status enum, their verification went red, and the fix took an hour instead of the two-day incident it would have been. I did not have to argue for the second boundary. The provider team asked for it.

Anselm Fowel, CTO and fintech architect
Anselm Fowel — CTO & fintech architect

Conclusion

Here is the thing I would tell my younger self, the one who spent that morning in 2019 untangling stuck settlements. The bug was never the field change. Field changes are normal and healthy; systems that cannot change fields are already dead. The bug was that a routine change could reach production without a single automated check standing between it and the consumers it would break. Contract testing does not stop the world from changing. It just makes sure that when the shape of a promise changes, the promise-breaker finds out first, in a pipeline, with a name attached, instead of the promise-keeper finding out last, in an incident, with a pager going off. Move the surprise earlier. That is the entire game, and it is worth playing.

Enjoyed this article? Share it with others!

Share:

Get new posts in your inbox

Occasional, practical notes on engineering leadership, fintech, and building with AI. No spam, unsubscribe anytime.

Comments (0)

Leave a Comment

Comments are moderated and will appear after review.

No comments yet. Be the first to comment!

About the author

Anselm Fowel

Anselm Fowel

Chief Technology Officer & fintech architect. 16+ years leading engineering across AlliancePay, Mondu, Transalliance, Global Accelerex, and Fidelity Bank — writing here about engineering leadership, fintech architecture, and AI in production.

Read next