Stubs
Stub APIs
Every contract published to API Hub for Contract Testing is automatically assigned a hosted API stub URL that you can use for stubbing API backends in your testing.
Hosted API stubs are useful for several use cases, such as:
Replacing end-to-end test environments when running UI testing tools like Cypress or mobile UI tests
Using as a dynamic test environment for new feature testing
Local development with multiple back-ends
Sharing with other teams so they can experiment safely with your API
Supported Pact Specification versions
Version | Supported? |
---|---|
1 | ✅ |
1.1 | ✅ |
2 | ✅ |
3 | ❌ |
4+ | ❌ |
Note
Whilst currently only versions 1 and 2 of the pact specification are currently fully supported. Pacts using the v3 format or beyond may be used, however any matching rules will be ignored.
Basic Use
To use the stub:
You must first publish a contract.
Find the path to the pact contract you'd like to stub. (If you're not familiar with the API Hub for Contract Testing API, the simplest way to get this is to click "View Pact" from the dashboard and select "API Browser" at the top of the screen to see the URL).
Append
/stub/
to the pact file path to get the base path of an instant stub.
Stub URL format
Pacts may be retrieved in several ways, the latest version, the latest with a particular tag, or the latest for a consumer version.
Stub URLs will have one of the following formats:
Description | URL |
---|---|
Latest for integration |
|
Latest for a given tag |
|
Latest for a consumer version |
|
For example, assuming you wanted to use the latest version of a particular contract as your stub, the base URL to configure in your client code would be:
https://<yourdomain>.pactflow.io/pacts/provider/:provider/consumer/:consumer/latest/stub
Stub behaviour
Pact contracts may define multiple overlapping requests - for example when there are provider states.
Where multiple matching interactions are found, the interactions will be sorted by response status, and the first one will be returned. This may lead to non-deterministic behaviour.
Note
Only versions 1 and 2 of the pact specification are currently fully supported. Pacts using the v3 format may be used, however, any matching features added in v3 will currently be ignored.
Example
The following example uses the example projects in our CI/CD workshop
Let's say you have a Product API example-provider
that you want to stub when working with a React consumer example-consumer
.
There are two main endpoints:
GET /products
: Retrieve all products:GET /products/:id
: Retrieve a single product
The (simplified) pact file for this integration looks like this:
{ "consumer": { "name": "example-consumer" }, "provider": { "name": "example-provider" }, "interactions": [ { "description": "a request to get a product", "providerState": "a product with ID 10 exists", "request": { "method": "GET", "path": "/product/10", "headers": { "Authorization": "Bearer 2019-01-14T11:34:18.045Z" } }, "response": { "status": 200, "headers": { "Content-Type": "application/json; charset=utf-8" }, "body": { "id": "10", "type": "CREDIT_CARD", "name": "28 Degrees" } } }, { "description": "a request to get all products", "providerState": "products exists", "request": { "method": "GET", "path": "/products", "headers": { "Authorization": "Bearer 2019-01-14T11:34:18.045Z" } }, "response": { "status": 200, "headers": { "Content-Type": "application/json; charset=utf-8" }, "body": [ { "id": "10", "type": "CREDIT_CARD", "name": "28 Degrees" } ] } } ], "metadata": { "pactSpecification": { "version": "2.0.0" } } }
You want to use the latest pact file for the stub, which is hosted on test.pactflow.io
. In the example app, you can set the base URL of all API calls with the environment variable REACT_APP_API_BASE_URL
.
export REACT_APP_API_BASE_URL=https://test.pactflow.io/pacts/provider/pactflow-example-provider/consumer/pactflow-example-consumer/latest/stub npm start
That's it - if you open the application in your browser, you can navigate around, using the live stub service.
CORS
By default, CORS requests are enabled on all stub APIs. The CORS configuration is as follows:
CORS header | Configuration | Description |
---|---|---|
| Reflects the | All origins are allowed |
|
| All headers are allowed |
|
| All methods are allowed |
|
| Credentials may be sent in CORS requests |
Finding the URL to a pact resource
Via the User Interface
You can copy the stub URL template from the contract details page via the ⫶
drop-down. This is the simplest method and is easily customized as per the URL format described above.
Via the API
Sometimes you need to find the exact version. To do this, you can navigate to the API user the HAL browser (and also directly via the API on the command line).
1. Find the integration
Navigate to the contract details page for a application version of interest. Copy the pact URL using the menu.
2. Open the API Browser
Open the API by selecting in the header toolbar, clicking Open HAL Explorer, and paste the URL into the navigation text box.
3. Find the pact
From here, you will be at the latest integration version. You can navigate from here to the specific version of an integration to get the URL you need:
Select
->
to navigate to the latest version.Select
->
to navigate to the latest tagged version of the pact.Copy the URL at this address to get the path to the pact file.