Stubs

Stub APIs

Every contract published to PactFlow 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:

1. Replacing end-to-end test environments when running UI testing tools like Cypress or mobile UI tests
2. Using as a dynamic test environment for new feature testing
3. Local development with multiple back-ends
4. 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:

1. You must first publish a contract.
2. Find the path to the pact contract you'd like to stub. (If you're not familiar with the PactFlow 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).
3. 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	/pacts/provider/:provider/consumer/:consumer/latest/stub
Latest for a given tag	/pacts/provider/:provider/consumer/:consumer/latest/:tag/stub
Latest for a consumer version	/pacts/provider/:provider/consumer/:consumer/:version/stub

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
Access-Control-Allow-Origin	Reflects the Origin send in the HTTP pre-flight request	All origins are allowed
Access-Control-Allow-Headers	*	All headers are allowed
Access-Control-Allow-Methods	*	All methods are allowed
Access-Control-Allow-Credentials	true	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 pact dashboard or pact drill-down view 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 dashboard and find the integration you're interested in.

2. Open the API Browser

Open the API Browser by selecting "API" in the header toolbar.

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:

1. Select -> to navigate to the latest version
2. Select -> to navigate to the latest tagged version of the pact
3. Copy the URL at this address to get the path to the pact file. By default, it will link to the version of the pact you were on in step 2