How does a Pact provider verification run fetch pacts and replay each interaction?

## Verification runs in the provider's build A pact is written by a consumer's test and read by a provider's test. Verification is therefore a job in the **provider's** pipeline: the consumer's repository is not checked out, its HTTP client never executes, and its serialisers, retries and timeouts are not exercised. What arrives is a JSON document containing interactions - each one a recorded request, an expected response, the matching rules that say how loosely each part may be compared, and zero or more named provider states. ## Choosing a pact source The first decision the test makes is where pacts come from, and it has consequences beyond convenience. | Source | Pact-JVM annotation | What it is for | | --- | --- | --- | | Pact Broker | `@PactBroker` | CI runs: fetch every pact for this provider and report results back | | A fixed URL | `@PactUrl` | Reproducing one specific failing pact by hand | | A local directory | `@PactFolder` | Bootstrapping before a broker exists | Only a pact fetched from a broker carries the link the verifier needs to report results afterwards, so a folder-based run is a local debugging tool and nothing more. In pact-js the same choice is made through verifier options rather than annotations - a broker URL, or an explicit list of pact file locations. ## Starting the provider and aiming the verifier The verifier is an ordinary HTTP client, so something has to make the provider answer on a port first. The usual shape is the provider's own Spring Boot test bootstrap on a random port; the test then tells the run where to send traffic by setting the target on the verification context to that host and port. Nothing about the provider is replaced or stubbed - the point of the run is to exercise the real routing, deserialisation, business code and serialisation. Expansion happens next. Pact-JVM's JUnit 5 integration uses a `@TestTemplate` method plus `PactVerificationInvocationContextProvider` to turn the fetched pacts into **one JUnit test case per interaction**, named after the interaction description and its state. A provider with four consumers and 23 interactions between them reports 23 independently red-or-green tests, which is why a failure names itself instead of collapsing into "the pact failed". ## What replaying one interaction does For each interaction the run performs the same five steps: 1. **Apply the provider states.** Each state named on the interaction is set up - by invoking the matching handler in the test class, or by calling a configured state-change endpoint. This is where the data the request will read comes into existence. 2. **Send the recorded request.** Method, path, query string, headers and body go out exactly as recorded. Pact Specification V3 generators may substitute a value at this moment - a fresh timestamp, or an identifier taken from a state parameter - so the bytes are not always byte-identical to the recording, but nothing else varies. 3. **Capture the real response.** Status, headers and body as the provider actually produced them. 4. **Compare.** The actual response is matched against the expected one using the matching rules stored in the pact, not by string equality. 5. **Tear down**, if the state declares a teardown step. Interactions are independent by design. Nothing guarantees the order they run in, and a suite that only passes in one order is telling you the provider states are leaking into each other. ## The comparison is deliberately asymmetric This is where most of the surprise lives, and it is intentional - the pact records what one consumer needs, not the shape of the whole API. - **Status** must equal the recorded status exactly. - **Headers the pact names** must match; headers the provider adds that the pact never mentioned are ignored. - **Body keys the pact records** must be present and satisfy their matchers; **keys the pact does not mention are ignored**. A provider that grows its response from twelve fields to seventeen does not fail a pact that only ever asked for five of them. - **Arrays are stricter than objects**: element counts matter unless the consumer relaxed them with a minimum-size type matcher. - A recorded value such as `68341` may be asserted as "an integer" rather than as that literal, if the consumer recorded a type matcher instead of an exact one. ## Reading a failure A mismatch reports the JSON path that differed and what was expected there - for instance, that `$.applicant.postcode` was expected to be a string matching a pattern and came back `null`. Two reflexes are wrong. Editing the pact file by hand is pointless: it is generated by the consumer's test and, in CI, re-fetched from the broker on every run. Loosening the provider's response until the message stops is worse, because the message is the contract talking. The real first question is which side moved - a provider regression, or a consumer expectation that nobody has agreed to yet. When one interaction needs isolating during debugging, Pact-JVM exposes filter system properties that restrict the run by consumer name, interaction description or provider state, so a 23-case suite can be narrowed down to the single case that is red. Those filters are a debugging aid only: a filtered run must never be the run that reports results, because it would record an outcome for interactions it never replayed.