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:

  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 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).

  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.

dev-console.png

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 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:

  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.

PF_Screenshot_HALExplorer_01.png
Publication date: