{"canonical_url":"https://engineer.company/glossary/contract-testing/","content_markdown":"# Contract testing\n\n## What it is\n\nContract testing checks that two components agree about the requests, responses or messages they\nexchange. A parcel tracking screen and a tracking service may each behave correctly in isolation.\nThe screen still breaks if it expects a field called `status` and the service sends `state`. A\ntest can protect the interface by expressing what the screen actually uses and verifying that the\nservice can supply it.\n\nPact describes one approach in which the consumer runs against a controlled substitute for the\nprovider. Its test records interactions in a contract. The provider then verifies the contract by\nexercising its own implementation under specified conditions. For messages, the equivalent\nevidence concerns the observable message consumed and produced. The two sides can check their\nexpectations while they work and release independently, as long as the evidence refers to the\nversions they intend to use together.\n\nOther teams use contract testing to mean checking one provider against its published interface\ndescription, such as an OpenAPI document. That is useful when the written specification is the\nshared agreement. An interface description can state field shapes, status codes and allowed\nvalues. Consumer-driven examples also show which combinations a particular caller uses and what\nassumptions the caller made. A working arrangement can include both methods. A journey through\nthe real integration still checks things outside the individual exchange, such as routing,\ncredentials and environment configuration.\n\n## Why it matters\n\nAn interface often outlives the code that first implemented it. A service team can rename a field\nand update its own tests without changing a separately maintained caller. A mobile client may\ncontinue to run an older version for months. Even a small type change matters if a caller uses it\nto choose what to display. A contract test can make those dependencies visible before a change\nships.\n\nSeparate release timing makes compatibility information useful. An old consumer might support\nonly a handful of status values. A new provider may need to add an intermediate status. The teams\ncan add support in the consumer first, continue to accept both forms during the transition and\nremove the old behavior after confirming the depended-on versions no longer use it. Which order\nis safe depends on the recorded contracts, real usage and the system's release policy. A\nsuccessful test of one recent pair does not prove compatibility for all clients still in use.\n\nTests should express the meaningful points of agreement. If any well-formed reference is fine,\nmatch the reference format and avoid requiring an exact sample value. If a field determines\ncustomer-visible behavior, check its type and the values the client understands. A carefully\nchosen example preserves room for the provider to change internals and for the consumer to keep\nusing agreed behavior.\n\n## What it looks like in practice\n\nConsider a fictional parcel tracking app. It requests a parcel by its reference. When a parcel\nexists and is in transit, the screen expects a success status, the parcel reference and a text\nvalue it can map to an in-transit label. When a parcel is unknown, the screen expects a distinct\nresponse and shows a way to check the reference. Each interaction is tied to a precondition, such\nas “the requested parcel is in transit” or “there is no parcel with that reference”.\n\nTest the consumer through its actual request code against the controlled substitute. Confirm the\napplication displays the appropriate result from each example. Then verify the same interactions\non the provider's actual response path. Create deterministic fixtures for the relevant provider\nstate and reset them between checks. If the test uses a stub for its database or for an external\ncarrier, keep the request parsing, application logic and response serialization that the consumer\ndepends on in the test path.\n\nTry changing the provider's `status` field to `state` while leaving the current consumer\nunchanged. Verification should fail for the missing field and identify the affected interaction.\nA new optional field that the consumer ignores should be allowed if the agreement permits it.\nKeep the separate verification runs tied to their genuine versions, because combining a new\nprovider result and an old contract sample without provenance makes it hard to know which pair\nwas tested.\n\nIn our [note on opening a dApp in Solana mobile wallets](/notes/solana-mobile-wallet-deeplinks/),\nseveral integrations expect different deep-link paths and query parameter encoding. The note\nrecords those actual differences and includes device checks. A small contract-style verification\nof generated URLs could protect the request shape for each wallet. An actual device run can show\nwhether a browser passes the link to the installed app and whether the journey completes. The two\nobservations answer different questions.\n\n## Where it goes wrong\n\nContracts can become too rigid when every response byte has to match one saved example. A\nprovider may be free to add an unused field or change the formatting of an independent message.\nMake a field mandatory when a caller uses it or when the public specification requires it.\nDeclare ordering, units or exact text only when the agreement needs them. Leave harmless\nvariability available.\n\nA test also loses value when it bypasses the real boundary. Verifying a hand-written example of a\nJSON object exercises the example and may never run the serializer. Testing only that the\nsubstitute returned the expected fixture can leave the consumer's parser untouched. Run the real\nrequest, serialization or parsing code on the side under test. Record which side was exercised\nand what its dependencies supplied.\n\nFinally, one recorded happy path says little about missing data, unknown references or versions\nthat still run in the field. Identify the error paths the consumer handles and the compatibility\nobligations the provider actually supports. Keep enough integration testing to exercise\nconfiguration and routing. A clear contract gives teams a smaller, faster piece of evidence they\ncan use on every relevant change.\n\n## Further reading\n\n- [Pact documentation on what contract testing\n  checks](https://docs.pact.io/#what-is-contract-testing)\n- [How Pact verifies consumers and\n  providers](https://docs.pact.io/getting_started/how_pact_works)\n- [Pact documentation on provider states](https://docs.pact.io/getting_started/provider_states)\n- [OpenAPI Specification for describing HTTP\n  interfaces](https://spec.openapis.org/oas/latest.html)\n\n\u003chttps://engineer.company/glossary/contract-testing/\u003e\n","date_modified":"2026-11-19T19:18:49Z","description":"How contract testing checks real interface expectations, with a parcel tracking example, provider states and guidance for independent releases.","formats":{"gemtext":"https://engineer.company/glossary/contract-testing/index.gmi","gopher":"https://engineer.company/glossary/contract-testing/gophermap","html":"https://engineer.company/glossary/contract-testing/","json":"https://engineer.company/glossary/contract-testing/index.json","markdown":"https://engineer.company/glossary/contract-testing/index.md","pdf":"https://engineer.company/glossary/contract-testing/index.pdf"},"kind":"page","language":"en","title":"What is contract testing?","url":"https://engineer.company/glossary/contract-testing/","version":1}