Quick Start Guide with Github Actions

export class Product {
  constructor({id, name, type}) {
    if (!id || !name || !type) {
      throw Error("id, name and type are required properties")
    }
    this.id = id
    this.name = name
    this.type = type
  }
}

See full example on GitHub

Here is a version of our API client code. This code is responsible for fetching products from the API, and returning a Product:

const axios = require("axios");
const adapter = require("axios/lib/adapters/http");
const { Product } = require("./product");

axios.defaults.adapter = adapter;

export class ProductAPIClient {
  constructor(url) {
    if (url === undefined || url === "") {
      url = process.env.BASE_URL;
    }
    if (url.endsWith("/")) {
      url = url.substr(0, url.length - 1);
    }
    this.url = url;
  }

  withPath(path) {
    if (!path.startsWith("/")) {
      path = "/" + path;
    }
    return `${this.url}${path}`;
  }

  async getAllProducts() {
    return axios
      .get(this.withPath("/products"))
      .then((r) => r.data.map((p) => new Product(p)));
  }

  async getProduct(id) {
    return axios
      .get(this.withPath("/product/" + id))
      .then((r) => new Product(r.data));
  }
}

See full example on GitHub

This class, and specifically the getProduct() and getAllProducts methods, will be the target of our contract tests.

Ideally, contract tests should be closer to a unit test for your API client class, and they should just focus on ensuring that the request creation and response handling are correct. Running in the context of a unit testing framework (Jest, JUnit, PHPUnit etc.) will give you the most flexible and reliable tests - even if the test is not strictly a unit test by definition.

Usually, your application will be broken down into a number of sub-components, depending on what type of application your consumer is (e.g. a Web application or another API). This is how you might visualise the focus of a consumer contract test:

Here, a Collaborator is a component whose job is to communicate with another system. In our case, this is the API class communicating with the external Product API system. This is what we want our consumer test to inspect.

API Hub for Contract Testing currently supports pact files as a consumer contract format. In order to produce a consumer contract, you need to decide on a testing approach to capture the contract:

Read more on these strategies.

As there are plenty of example projects for how to write Pact tests, we will choose option (2) and use Mountebank to mock our APIs so you have a model to follow for your specific mocking tool.API Hub for Contract Testing Code Demos

Let's dive in! First, let's open up the API spec and go through the key bits: example-bi-directional-consumer-mountebank/src/api.spec.js

The following key libraries and tools are used:

At the start of our test, we configure a few important lifecycle hooks:

const mb = new Mountebank(); // (1)
const api = new ProductAPIClient(`http://localhost:${imposterPort}`); // (2)
const imposter = new Imposter() // (3)
  .withPort(imposterPort)
  .withRecordRequests(true);

beforeAll(() => startAndClearStubs()); // (4)
afterEach(() => writeStubs(mb, imposterPort)); // (5)
afterAll(() => stopStubs()); // (6)

We then have a few lifecycle methods:

Now that we have the infrastructure in place, we can simply write our tests.

describe("retrieving products", () => {
  test("products exists", async () => {
    // (1) Arrange
    imposter.withStub(
      new Stub()
        .withPredicate(
          new EqualPredicate().withMethod(HttpMethod.GET).withPath("/products")
        )
        .withResponse(
          new Response().withStatusCode(200).withJSONBody([expectedProduct])
        )
    );
    await mb.createImposter(imposter);

    // (2) Act
    const products = await api.getAllProducts();

    // (3) Assert that we got the expected response
    expect(products).toStrictEqual([new Product(expectedProduct)]);
  });
});

There's a lot here, so let's break it down a little.

After each test block finishes successfully, the afterEach block will append the new interaction to our contract file.

To generate our pact file, we have created a few helper functions to inspect Mountebank and write the mocks to file

To extract the mock information, we have a few choices (see http://www.mbtest.org/docs/api/mocks). In this case, when we start Mountebank, we actually pass the --debug flag giving us a really important behaviour:

Include a matches array with each stub in the body of a GET imposter response for debugging why a particular stub did or did not match a request. Every time a response from the stub is used, a match will be added containing the request, the response configuration, the actual generated response (even if it is proxied), and the overall processing time.

This means we can inspect this information to only serialise what our API client actually called (i.e. excluding any unused mocks) ensuring the contract we produce is valid and reliable.

This information is retrieved via an API call to Mountebank to retrieve the current Imposter information. Alternatively, Mountebank has a save option which we could also use to transform a file.

This process is essentially same for any mocking tool, such as Wiremock or Cypress.

Read more for detail on how to serialise a pact file.