Pact – Contract testing made (almost) easy

late Middle English: from Old French, from Latin pactum ‘something agreed’, neuter past participle (used as a noun) of paciscere ‘agree’.

Pact from Pact Foundation is designed to be a dependable testing method for integration points, such as API’s and microservices, for development teams concerned with message conformity. In the past, teams would ensure conformity with integration tests (a loaded term with many different meanings). These tests were expensive to create, and often unwieldy.

Pact aims to make it easier to ensure conformity with contract tests that make it possible to ensure a contract is being followed without having to wire everything to everything else and deploy it all first.

There is an hilarious analogy on the https://docs.pact.io website: “do you set fire to your house to test your smoke alarm? No, you test the contract it holds with your ears by using the testing button”. – (https://docs.pact.io)

In order to provide this sort of contract testing, Pact checks each application in isolation checking the messages it sends out, and how it behaves to certain expected messages coming in, and documenting all of this in a ‘pact file’ – the contract.

If you have application (A) providing a service to application (B), think of application (A) as the provider and application (B) as the consumer. This is the simplest way to look at it, although of course you can/will have multiple providers and consumers. Pact is a code-first ‘consumer-driven’ contract test tool. That means that any part of the providing service your consumer doesn’t use can change without an impact, as only the parts your consumer cares about are tested. This makes the contract test far less brittle than traditional integration tests. Pact is ‘contract by example’.

Personally, I found it a little hard to get my head around the design of Pact at first. I even doubted the value of a consumer-driven contract. I was more used to the idea of provider-driven integration testing. There are also quite a few moving parts involved, which takes some time to pin down in an abstract image in your mind – at least, my mind. It’s one of those tools that you really get to grips with once you create your first meaty test.

Having said that, the documentation is really very good.

The first thing to do is to get to grips with the terminology:

• consumer – an application that uses either data or functionality from another application. For example: if your application uses HTTP and is the consumer of another application, your consumer initiates the HTTP request. It doesn’t matter what direction data flows. You can also have applications that utilise queues, if your application falls into this category, your consumer is the application that reads the message from the queue.
• provider – otherwise known as a service, that serves either data or functionality to other applications. So for example, if your application uses HTTP, the provider is the application that responds to your application. If you use queues, the provider is the application that puts messages on the queue.
• pact – the contract between the two entities described above. This is described through a batch of interactions. For HTTP, the interaction consists of an expected request (i.e. what is the minimal expected request from this consumer) and a minimal expected response (the very least that the consumer wants back from the provider). For queues it would be a description of the minimum expected message or pieces of a message that the consumer needs.

Given the above description, the consumer needs to run its test first, as it needs to generate the pact file / contract. Once that pact file is generated, the provider has something to verify against.

Overview of how it works

Essentially, the consumer uses a mock provider, and the provider uses a mock consumer.

Consumer test

So, for HTTP for example, in the first instance, the consumer defines an interaction (expected request/minimal expected response).
e.g.

import { GOOD_LOGIN_REQ, GOOD_LOGIN_RESP } '../test-data/login-req-resp.json';

describe('Login service', () => {
    const mockProvider = new Pact({
        host: 'localhost',
        port: '4444',
        consumer: 'mymadeupsite',
        provider: 'myloginservice',
        dir: resolve(__dirname, pathToWherePactFileGoes),
        logLevel: 'error',
        log: resolve(__dirname, 'logs', 'mylogintest.log'),
    });

    beforeAll(() => mockProvider.setup());
    afterAll(() => mockProvider.finalize());

    describe('a successful login interaction', () => {
        const successfulLoginInteraction: InteractionObject = {
            uponReceiving: 'a good login request',
            withRequest: GOOD_LOGIN_REQ,
            willRespondWith: GOOD_LOGIN_RESP,
        } as InteractionObject();

    beforeAll(() => {
        return mockProvider.addInteraction(successfulLoginInteraction);
    });

.... // here then you have your tests that call a real service
.... // the net result of which is Pact captures the request

where the GOOD_LOGIN_REQ might look something like:

export const GOOD_LOGIN_REQ = {
    method: 'POST',
    path: '/login',
    body: {
        username: 'fakename',
        password: 'fakepwd',
    },
    headers: {
        Accept: 'application/json',
    },
};

and the GOOD_LOGIN_RESP might look something like:

export const GOOD_LOGIN_RESP = {
    status: 200,
    body: {
        customer: mockCustomer,
    },
};

It then sends a real request to the mock provider which Pact compares to the expected request. The mock provider then replies with the minimal expected response if it liked the request. The consumer code confirms that it liked the response. If entirely happy, the consumer test will pass.

For provider testing, a mock consumer sends an expected request (defined in the interaction) to a real provider. This elicits a real response. That real response is then compared by Pact to the minimal expected response defined in the interaction. If each response to the provided request(s) matches the minimal expected response, then Pact is happy.

The provider test is really all about defining where the pact file can be found, setting up any state handlers, and running the verifier. You may have extra setup depending on your application; such as Inversify containers and mocks and stubs etc… but that is a separate issue.
e.g.

describe('Provider test for login', function() {
    before(done => {
        // ... container setup
    });

    it('should verify the contract', function() {
        const opts: VerifierOptions = {
            provider: 'loginservice',
            providerBaseUrl: PROVIDER_BASE_URL,
            providerVersion: '1.0.0',
            pactBrokerUrl: PATH_TO_PACT_BROKER,
            publishVerificationResult: true,
            logLevel: 'debug',
            stateHandlers: {
                'login is successful': () Promise => {
                    return mockAdapter.onPost(`/usercheck`).reply(200, {'userOk': true });
                },
            },
    };

    return new Verifier(opts).verifyProvider()
        .then(() => {
            console.log('Pact verification complete');
    });
});

Now, it’s important at this point to understand something fundamental to the design of Pact. The contract test must be data independent. Pact shouldn’t care about specific data, it cares about the ‘nature’ of data. So for instance, you wouldn’t ask Pact to verify that a response that contains say, a persons age, was precisely 44. You would ask Pact to verify the response contains an age field which has a number as its value. Which brings us on to….

For expected requests, it’s advisable to make it as explicit as possible, as specific as possible – since you are in charge of the request. Pact allows for extra headers but not for unexpected values.
e.g.

export const SESSION = {
    method: 'HEAD',
    path: '/session',
    headers: {
    },
    cookies: [
        '__session_cookie=mock_session;',
    ],
};

As for responses, Pact allows loose matching. Remember I mentioned Pact shouldn’t care about specific data? Well for responses it enables you to declare the shape and flavour of data without getting stuck on specifics, through matchers. In the example I gave above where the response should contain a field with a persons age in it, we are interested in the field being a number, not precisely 44. In that case, we can use the ‘like’ matcher. In the response, we can say the age field should be ‘like’ 44, “like(44)”, and if the response comes back with the age field holding a value of, say, 65, well that’s just fine. Next time if the provider responds with say, 19, that’s also fine.

To be fair, you can better use ‘integer(44)’ for this. You’ll probably end up using the ‘like’ keyword for strings,
e.g. ‘id: like(‘FDJKJ3849SUSHS’),’.You can use the ‘like’ matcher on single fields or block objects in the JSON. e.g.

customer: like({
    username: string('username'),
    password: string('password'),
}),

You can use the ‘matcher’ er, matcher… and benefit from using regular expressions for fields in the response.
e.g.

customerState: regex({
    current: 'ACTIVE',
    matcher: 'ACTIVE|UNSUBSCRIBED',
}),