To every frontend engineer who integrated APIs in the past, we all, at least once, experienced bugs with unexpected responses from an API call. Detecting those issues during development can be frustrating and time-consuming, especially if a lot of integration work has been done already. It can also be hard to reproduce if the API call causing issues is deep inside the navigation stack of our application.

Through a couple of simple steps, I will show you a great way to solve these problems by writing tests scripts using Postman that are validating the JSON response against an API schema definition.

Step 1 – Get the schema you expect

The first thing you’ll need is a reference to the schema you are expecting the JSON response to match. A schema is a JSON object describing what properties a model should have, their types, if they are optional or not, etc. A tool like Swagger helps a lot documenting your APIs, using schema definitions for the models your APIs return.

If we take the example of Swagger’s Pet Store API, we can see how the schema for a User object looks like:

{
    "type" : "object",
    "properties" : {
      "id" : {
        "type" : "integer",
        "format" : "int64"
      },
      "username" : {
        "type" : "string"
      },
      "firstName" : {
        "type" : "string"
      },
      "lastName" : {
        "type" : "string"
      },
      "email" : {
        "type" : "string"
      },
      "password" : {
        "type" : "string"
      },
      "phone" : {
        "type" : "string"
      },
      "userStatus" : {
        "type" : "integer",
        "format" : "int32",
        "description" : "User Status"
      }
    },
    "xml" : {
      "name" : "User"
    }
}

This schema indicates that a User model has an identifier of type Integer, and several strings for their information (first name, last name, etc.).

The User model looks like the following in JSON format:

{
    "id": 0,
    "username": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "password": "string",
    "phone": "string",
    "userStatus": 0
}

Step 2 – Add a pre-request script to Postman

Postman is a fantastic tool for calling and testing APIs. It allows you to create HTTP requests easily and test the response you are getting.

For the purpose of this article, we will create one request that targets a Swagger mock API I created. The API shown is a GET request to get the user profile.

In the “Pre-Request” tab, you can add scripts that will run before the request gets executed. There, we copy our schema object, and create an environment variable from it.

const schema = {
    "type" : "object",
    "properties" : {
      "id" : {
        "type" : "integer",
        "format" : "int64"
      },
      "username" : {
        "type" : "string"
      },
      "firstName" : {
        "type" : "string"
      },
      "lastName" : {
        "type" : "string"
      },
      "email" : {
        "type" : "string"
      },
      "password" : {
        "type" : "string"
      },
      "phone" : {
        "type" : "string"
      },
      "userStatus" : {
        "type" : "integer",
        "format" : "int32",
        "description" : "User Status"
      }
    },
    "xml" : {
      "name" : "User"
    }
};

pm.environment.set("schema-variable", schema);

You can see that our schema object is now saved into an environment variable:

Step 3 – Add a test script to Postman

Now that we have the request and the schema saved as an environment variable, we can write our script that will test that the JSON response matches the schema.

const response = pm.response.json()
const schema = pm.environment.get("schema-variable");

// Test whether the response matches the schema
tests["Get User is valid"] = tv4.validate(response, schema);

pm.environment.unset("SCHEMA");

The logic relies on a framework called Tiny Validator, a Javascript validation framework embedded with Postman. The validate function takes a schema and a JSON object and validates that they both match in terms of structure.

If we run the request, the test script will be executed after the request was sent. It allows us to parse the response in a JSON object, and compare it with the schema.

We see that the test passed, confirming that the response is matching the expectations.

If we were to modify the schema in the pre-request script, we’ll see that it now makes the test fail.

If a test failed, you can see the error in tv4.error. You can use the Postman console to print the error object:

// Test whether the response matches the schema
tests["Get User is valid"] = tv4.validate(response, schema);
console.log(tv4.error);

Conclusion

Postman scripts are very useful tools to test APIs before doing any integration. They allow you to quickly check that everything is in order, with a low level of effort. It can save a lot of time by quickly detecting issues and communicating them.

Note that these scripts should not replace unit and integration testing for the backend team. I found writing these scripts very useful when I had no control over how the backend team was writing and testing their code.

External Links

• JSON schema
• Swagger
• Postman
• Tiny Validator