Stubs

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

To use the stub:

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:

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

Pact contracts may define multiple overlapping requests, for example, when there are provider states.

If the request matches any interactions, it will return the first response based on the order in the pact file.

If the request does not match, it will return the errors from the interaction with the least number of mismatches, followed by the order in the Pact file.

This matching behaviour may be configured using additional headers sent with a request.

< HTTP/2 500
< content-type: application/json
< content-length: 66
< date: Mon, 03 Feb 2025 02:48:14 GMT
...
<
{
  "mismatches": [
    "Expected query parameter 'from' but was missing"
  ]
}

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:

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.

By default, CORS requests are enabled on all stub APIs. The CORS configuration is as follows: