A provider state is a named precondition that prepares provider data or runtime conditions before a contract interaction is verified. It makes an expected response reproducible even when shared data has been deleted, refreshed, or altered between test runs. section 4.1.4 section 6.1.2
Use a provider state when an interaction depends on data that cannot be assumed to exist. A request for `/movie/100`, for example, needs a movie with that ID before verification; otherwise, a failure may reflect missing setup rather than a broken consumer-provider contract. section 6.1.2 section 6.3.2
A state connects the consumer contract to provider-side setup through a shared name:
- Declare the required state on the consumer interaction with `given`, optionally passing parameters such as an ID. section 6.3.2
- Publish or otherwise make the updated contract available for provider verification. section 6.3.2
- Register a provider `stateHandlers` entry with exactly the same state name. section 6.6 section 6.3.2
- Have the handler establish the required data before the verifier replays the interaction against the real provider API. section 6.1.2 section 6.1
Preparing a movie by ID
A consumer records a GET request to `/movie/100` with the state “Has a movie with specific ID” and passes `id: 100`. The provider maps that exact name to a handler that assigns the movie ID, then verification runs the request and checks the contracted response. Parameters let one state describe setup for a requested value without changing the state’s purpose. section 6.3.2 section 6.1.2
...
const EXPECTED_BODY = { id: 1, name: "My movie", year: 1999 };
const testId = 100;
EXPECTED_BODY.id = testId;
...
provider
.given('a movie with specific ID', { #1
id: 100, #1
}) #1
.uponReceiving('a request to a specific movie')
.withRequest({
method: 'GET',
path: '/movie/100',
})
.willRespondWith({
status: 200,
body: {
id: integer(testId),
name: string(EXPECTED_BODY.name),
year: integer(EXPECTED_BODY.year)
}
})
})
...
stateHandlers: { #2
'a movie with specific ID': (parameters) => { #2
movies.getFirstMovie().id = parameters.id; #2
return Promise.resolve({ description: `Movie with ID
${parameters.id} added!` }); #2
} #2
} #2
...
This paired consumer and provider snippet shows the same named state, an ID parameter, and the handler that prepares provider data before verification. section 6.1.2
Provider states support contract verification, not exhaustive provider testing. Keep provider business rules in separate functional tests; use states only to establish the conditions required for a consumer interaction. Compared with integration environments, state handlers can set data directly before a run and verification can target a local provider instance. section 6.6 section 12.3
