# Contract testing

## What it is

Contract testing checks that two components agree about the requests, responses or messages they
exchange. A parcel tracking screen and a tracking service may each behave correctly in isolation.
The screen still breaks if it expects a field called `status` and the service sends `state`. A
test can protect the interface by expressing what the screen actually uses and verifying that the
service can supply it.

Pact describes one approach in which the consumer runs against a controlled substitute for the
provider. Its test records interactions in a contract. The provider then verifies the contract by
exercising its own implementation under specified conditions. For messages, the equivalent
evidence concerns the observable message consumed and produced. The two sides can check their
expectations while they work and release independently, as long as the evidence refers to the
versions they intend to use together.

Other teams use contract testing to mean checking one provider against its published interface
description, such as an OpenAPI document. That is useful when the written specification is the
shared agreement. An interface description can state field shapes, status codes and allowed
values. Consumer-driven examples also show which combinations a particular caller uses and what
assumptions the caller made. A working arrangement can include both methods. A journey through
the real integration still checks things outside the individual exchange, such as routing,
credentials and environment configuration.

## Why it matters

An interface often outlives the code that first implemented it. A service team can rename a field
and update its own tests without changing a separately maintained caller. A mobile client may
continue to run an older version for months. Even a small type change matters if a caller uses it
to choose what to display. A contract test can make those dependencies visible before a change
ships.

Separate release timing makes compatibility information useful. An old consumer might support
only a handful of status values. A new provider may need to add an intermediate status. The teams
can add support in the consumer first, continue to accept both forms during the transition and
remove the old behavior after confirming the depended-on versions no longer use it. Which order
is safe depends on the recorded contracts, real usage and the system's release policy. A
successful test of one recent pair does not prove compatibility for all clients still in use.

Tests should express the meaningful points of agreement. If any well-formed reference is fine,
match the reference format and avoid requiring an exact sample value. If a field determines
customer-visible behavior, check its type and the values the client understands. A carefully
chosen example preserves room for the provider to change internals and for the consumer to keep
using agreed behavior.

## What it looks like in practice

Consider a fictional parcel tracking app. It requests a parcel by its reference. When a parcel
exists and is in transit, the screen expects a success status, the parcel reference and a text
value it can map to an in-transit label. When a parcel is unknown, the screen expects a distinct
response and shows a way to check the reference. Each interaction is tied to a precondition, such
as “the requested parcel is in transit” or “there is no parcel with that reference”.

Test the consumer through its actual request code against the controlled substitute. Confirm the
application displays the appropriate result from each example. Then verify the same interactions
on the provider's actual response path. Create deterministic fixtures for the relevant provider
state and reset them between checks. If the test uses a stub for its database or for an external
carrier, keep the request parsing, application logic and response serialization that the consumer
depends on in the test path.

Try changing the provider's `status` field to `state` while leaving the current consumer
unchanged. Verification should fail for the missing field and identify the affected interaction.
A new optional field that the consumer ignores should be allowed if the agreement permits it.
Keep the separate verification runs tied to their genuine versions, because combining a new
provider result and an old contract sample without provenance makes it hard to know which pair
was tested.

In our [note on opening a dApp in Solana mobile wallets](/notes/solana-mobile-wallet-deeplinks/),
several integrations expect different deep-link paths and query parameter encoding. The note
records those actual differences and includes device checks. A small contract-style verification
of generated URLs could protect the request shape for each wallet. An actual device run can show
whether a browser passes the link to the installed app and whether the journey completes. The two
observations answer different questions.

## Where it goes wrong

Contracts can become too rigid when every response byte has to match one saved example. A
provider may be free to add an unused field or change the formatting of an independent message.
Make a field mandatory when a caller uses it or when the public specification requires it.
Declare ordering, units or exact text only when the agreement needs them. Leave harmless
variability available.

A test also loses value when it bypasses the real boundary. Verifying a hand-written example of a
JSON object exercises the example and may never run the serializer. Testing only that the
substitute returned the expected fixture can leave the consumer's parser untouched. Run the real
request, serialization or parsing code on the side under test. Record which side was exercised
and what its dependencies supplied.

Finally, one recorded happy path says little about missing data, unknown references or versions
that still run in the field. Identify the error paths the consumer handles and the compatibility
obligations the provider actually supports. Keep enough integration testing to exercise
configuration and routing. A clear contract gives teams a smaller, faster piece of evidence they
can use on every relevant change.

## Further reading

- [Pact documentation on what contract testing
  checks](https://docs.pact.io/#what-is-contract-testing)
- [How Pact verifies consumers and
  providers](https://docs.pact.io/getting_started/how_pact_works)
- [Pact documentation on provider states](https://docs.pact.io/getting_started/provider_states)
- [OpenAPI Specification for describing HTTP
  interfaces](https://spec.openapis.org/oas/latest.html)

<https://engineer.company/glossary/contract-testing/>
