Implementing Contract Testing with Postman

My original blog on our company website (in Norwegian):
https://www.bouvet.no/bouvet-deler/introduksjon-til-contract-testing

Introduction/Context

In my previous blog, we plunged into the concept of Contract Testing and explored how an API contract is composed. Today, we’ll apply this knowledge practically by implementing a contract test using Postman, a tool widely popular in the API testing community. Our subject for this experiment will be the delightful catfact.ninja API.

Contract testing ensures that services like APIs adhere to their declared contract. In the world of microservices, this form of testing is crucial, verifying that changes in a service don’t rupture the contract and cause detrimental ripple effects on other services. We’ll use Postman and AJV (Another JSON Schema Validator), a swift JSON schema validator, for validating these contracts.

Prerequisites

To follow through this blog post, you’ll need:

1. Basic knowledge of APIs and Postman. If you’re new to Postman, familiarize yourself with the official documentation.
2. Postman installed on your computer. It’s available for download on the official Postman site.
3. A solid understanding of JSON Schema and Contract Testing from my previous blog post.

Explaining the Example API

Our API of choice for this tutorial is the whimsical catfact.ninja API. Specifically, we’ll be using the GET catfact.ninja/fact endpoint, which supplies us with a random cat fact. This API is in no way complex, but it is a good starting point to create a simple contract and get to our test implementation.

A typical response from this endpoint appears as follows:

{
  "fact": "A cat's brain is 90% similar to a human's brain.",
  "length": 50
}

Creating a JSON Schema that can be used with Postman

Based on the API’s response, we can now create a JSON Schema describing the data structure. Here’s an example of what that schema might look like:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "fact": {
      "type": "string"
    },
    "length": {
      "type": "number"
    }
  },
  "required": ["fact", "length"]
}

This schema verifies that the response is an object containing a “fact” string and a “length” number. Both of these properties are required.

Setting up Postman

With our schema ready, let’s delve into setting up Postman.

1. Creating a Request: Open Postman and create a new GET request. Set the request URL to https://catfact.ninja/fact.

1. Adding Tests: Click on the “Tests” tab to add some test scripts.

Adding AJV and Using the Schema for Validation

Here’s where AJV comes into play. AJV allows us to validate JSON data against a JSON schema, ideal for contract testing. Postman’s test scripts can use the AJV library to validate the API response against our schema.

Firstly, we need to create our schema in the Pre-request Script of our Postman collection.

Code snippet below, pasted into the Pre-request Script section

// Define schema
pm.environment.set("catFact_schema", {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "fact": {
      "type": "string"
    },
    "length": {
      "type": "number"
    }
  },
  "required": ["fact", "length"]
});

Then, let’s move to the Tests section:

Below code snippet, pasted into the Tests section

// Initialize AJV
var Ajv = require('ajv');
ajv = new Ajv({logger: console});

// Set schema parameter (the variable we created in pre-request)
var schema = pm.environment.get("catFact_schema");

// Set data parameter (the parsed json response body)
var data = pm.response.json();

// Check validation result
pm.test('CatFact response adheres to schema', function() {
    pm.expect(ajv.validate(schema, data)).to.be.true;
});

In this script, we retrieve the schema created in the pre-request script, initialize AJV, compile the schema using AJV, and validate the response body against the schema. If the validation fails, it logs the errors; if it passes, it logs a success message.

Running the Test

Having set up the test, you’re now ready to run it. Click “Send” to execute the GET request. After the request is completed, you can check the test results in the “Test Results” tab of the response section.

Successful test

Conclusion

And that’s it! You’ve successfully set up and run a contract test using Postman and AJV. Contract testing can be a powerful tool in maintaining the integrity of your APIs, particularly in microservice architectures. It ensures that services continue to interact seamlessly, even as individual services evolve. Armed with tools like Postman and AJV, you can effectively keep your APIs’ contracts intact. Happy testing!

About me

My name is Wessel Braakman and I’m a consultant at Bouvet in Norway. My aim is to share knowledge with others and to get others excited about QA, Low-Code and new technologies. If you have any questions about these topics, don’t hesitate to contact me through e-mail or LinkedIn!