Python Contract Testing — ELI5

Imagine two kids building a Lego project together. One builds the castle, the other builds the drawbridge. They agree: “The drawbridge will have two pegs on top, and the castle wall will have two matching holes.” That agreement is their contract.

If the castle kid changes the wall to have three holes, the drawbridge won’t fit anymore. But if they check the agreement first, they know not to make that change — or to tell the drawbridge kid first.

Contract testing works exactly like this, but for software.

When two computer programs talk to each other, they agree on what messages look like. “I’ll send you a user’s name, email, and age. You’ll send back a success message.” That’s their contract.

Contract testing checks that both sides still follow the agreement. The sender keeps sending what it promised. The receiver still handles what it expects. If either side changes without updating the contract, the test fails and everyone knows before anything breaks for real users.

This matters because in big applications, many programs talk to each other. The login service talks to the user database, which talks to the email service, which talks to the notification system. If any one of those changes how it communicates without telling the others, things break in confusing ways.

Contract testing catches those breaks early, before they reach real users.

One thing to remember: Contract testing is a promise between two services — “I’ll always send this, you’ll always accept that” — and the tests verify nobody breaks their promise.