Hosted API Stubs

Ever wanted an instant backend API stub for something you were working on?

Perhaps you're running automated e2e browser tests using tools like Cypress.io, or maybe you're deploying each PR of your web app to its own unique environment for testing, or using a tool like https://linc.sh/, but you've found that you also want a stable, clean backend available to ensure those tests don't become flakey and unreliable?

You've seen other API mocking tools, but are concerned that they aren't a valid depiction of reality, and so they can't be trusted. You're stuck with the "real" environment.

Managing test environments is one of the biggest challenges for many organisations. According to a recent report, waiting for an environment to be available, managing data or simply maintaining an environment accounts for a significant chunk of time and impact on team performance.

Today, we are releasing a little feature that will enable these workflows, and many others - automated hosted API stubs from any contract.

How to use a stub

Any contract that has been published to Pactflow is automatically assigned a stub resource URL. To use the stub:

• Publish a contract
• 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 the "API Browser" at the top of the screen to see the URL)
• Append /stub/ to the path of the pact file to get the base path of an instant stub

The result will be a URL that has one of the following formats:

/pacts/provider/:provider/consumer/:consumer/latest/stub
/pacts/provider/:provider/consumer/:consumer/latest/:tag/stub
/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

Example

Let's say you have a Product API pactflow-example-provider that you would like to stub when working with a React consumer pactflow-example-consumer.

To retrieve all products, there is a GET /products endpoint and to retrieve a single product, there is a GET /products/:id endpoint.

The (simplified) pact file for this integration looks something like this:

{
  "consumer": {
    "name": "pactflow-example-consumer"
  },
  "provider": {
    "name": "pactflow-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 purposes of 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 up the application in your browser you can navigate around, using the live stub service.

Use Cases

Whilst running it locally can be useful for developers in some situations, we see the benefits in further removing the dependency on expensive, fragile and hard to maintain end-to-end test environments.

• 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
• ...whatever your ❤️ desires

Availability

Hosted stubs are available on all plans, for every pact file, right now.