How to write postman tests and execute them as a part of your CI

Traditionally building, deploying, and testing (white box) the API were done in a decoupled manner. The builder wrote unit tests and ensured the APIs functioned as per spec. The DevOps team handled deployments while the QA team wrote white box test using tools like Chai HTTP, Blue tape, etc.

Postman has become the standard for collaborating, sharing, and documenting APIs. If you're building an API, chances are you are using Postman.

Not many know that Postman also allows you to write tests. This feature allows the backend developer to write tests as part of the collection. These tests can later be run in the continuous integration pipeline. These automations bring certainty to the deployment.

In this tutorial we'll use a todo (https://pyher2ne7raefaz22vgl2pr2ku.appsync-api.ap-south-1.amazonaws.com/graphql) GraphQL API as a starting point and cover the following:

• Writing tests using Postman
• Run tests using Github actions on push to the default branch

Starter Project

Please clone the following repository: https://github.com/wednesday-solutions/postman-tests-starter. The todo API exposes a few endpoints, in this tutorial we will only focus on the following:

• CreateUser
• CreateList
• CreateNote
• QueryNotes

Note: If you're not familiar with GraphQL please take a few minutes to read the spec here.(https://graphql.org/)

Writing Tests

As a first step start Postman, go to File → Import and drag and drop the collection and the environment.

CreateUser Test

This API creates a user. Testing this is simple we just need to ensure a user_id is generated.

Now that you have your collections loaded and ready follow these steps to add a test.

1.Open the mutation folder and select createUsers.

2.Go to the Body tab and add this to the GraphQL variables section on the right

{
  "createUserInput": {
      "name": "Mac",
      "userRef": "mac-123"
  }
}

The above variables will be passed to the API. Feel free to change the values in these to something you prefer.

3.Go to the Tests tab and add the following snippet:

pm.test("if createUser API creates a valid user", function() { // 1
    const response = JSON.parse(responseBody); 
    pm.expect(response.errors).to.be.undefined // 2
    const jsonData = JSON.parse(responseBody)
    postman.setEnvironmentVariable("user_id", jsonData.data.createUser.id) // 3
});

The above code might be difficult to understand at first. Let's look at the tough bits.

1. pm here stands for Postman. It's an object that postman provides with a test method that you can execute.
2. Here we check if the response from the API has an error. If there is no error it means that user creation was successful.
3. Here we set the environment variable to the user_id we received from the API.

At this point select the Send button. The API will return a response, select the preview button and note that the environment variable has the same user_id as was returned by the API.

CreateList Test

This API creates a list of Todos. To test this API we will write a test that will create a list for the user_id we created in the previous test.

1.Select createList from the mutations folder

2.Go to the Body tab and add the following:

{
  "createListInput": {
      "name": "House chores",
      "userId": {{user_id}}
  }
}

3.Go to the Tests tab and add the following:

pm.test("if createList API creates a valid list", function() {
    const response = JSON.parse(responseBody);
    pm.expect(response.errors).to.be.undefined
    const jsonData = JSON.parse(responseBody)

    pm.expect(jsonData.data.createList.userId)
            .to.be.equal(parseInt(pm.environment.get("user_id"), 10));

    postman.setEnvironmentVariable("list_id", 
            jsonData.data.createList.id)
});

The above code should now be easy to understand. We check if the user_id is the same and set the list_id we receive from the API in the environment variable to use further. The drill must be clear by now, any dependancy goes in the environment which you can use to test a related API.

CreateNote Test

This API allows users to create a Todo. Let’s write the test for this
1.Select createNote in the mutations folder.

2.Go to the Body tab and add the following

{
  "createNoteInput": {
      "note": "Mow the lawn",
      "listId": {{list_id}},
      "deadline": "2021-01-01T00:00:00.000Z"
  }
}

3.Go to the Tests tab and write the test as follows

pm.test("if queryNotes API returns the correct note and associated data", function() {
    const response = JSON.parse(responseBody);
    pm.expect(response.errors).to.be.undefined
    const jsonData = JSON.parse(responseBody)
    const notes = jsonData.data.notes;
    pm.expect(notes.items.length).to.be.equal(1);
    pm.expect(notes.items[0].id).to.be.equal(pm.environment.get("note_id"));
    pm.expect(notes.items[0].note).to.be.equal("Mow the lawn");
    pm.expect(notes.items[0].done).to.be.equal(false);
    pm.expect(notes.items[0].deadline).to.be.equal("2021-01-01T00:00:00.000Z");

    pm.expect(notes.items[0].listId)
        .to.be.equal(pm.environment.get("list_id"));
        pm.expect(notes.items[0].list.id)
            .to.be.equal(pm.environment.get("list_id"));    
        pm.expect(notes.items[0].list.user.id)
            .to.be.equal(pm.environment.get("user_id"));
});

The above test case checks if the note is created successfully with the right list and user id.

Notes Test

As the name suggests this API is used to query for notes that are created. Similar to the above you can write a test to check if the created note is stored correctly. I won’t go into the details of how you can write this test and leave this as an exercise for you to do.
You can take a look at the completed test here: https://github.com/wednesday-solutions/postman-tests

Github Actions

Until this point, you should have a working collection of APIs with tests. In this section, you will learn how to set up a Github action to run these tests on a merge to master.
Note: Github actions are out of the scope of this tutorial. If you’d like to know more about them please read this(https://github.com/features/actions)

1. Create a yml file using this command

mkdir -p ./github/workflows

1. Add the following code to the yml file

name: Postman tests
on:
  push:
    branches: [master]
jobs:
  run-and-test:
    runs-on: ubuntu-latest
    steps:
      - name:
        uses: actions/checkout@v2
#1
      - name: Run API Tests
        id: run-newman
        uses: anthonyvscode/newman-action@v1
        with:
          collection: todo-application.postman_collection.json
          environment: todo-application.postman_environment.json
          reporters: cli
#2
      - name: Output summary to console
        run: echo ${{ steps.run-newman.outputs.summary }}

Here is the explanation of the above code:

1.This uses the newman-action github action that will execute the collection runner.

• collection expects the path to the collection file.
• environment expects the path to the environment file.

You can read about all of the different options it supports here: https://github.com/marketplace/actions/newman-action
2.This will print the summary of the #1 to the console

Push the above file to your github repo and watch the actions run on every merge.

Where to go from here

Postman has become the de-facto collaboration platform for API development. Backend developers can write integration tests while they are manually testing their APIs.

In its most nascent form, this is the first step in ensuring that your APIs pass a basic sanity test.

As you add more test cases and emulate various scenarios this can remove the need to use another framework for integration testing.

You can check out the complete working solution
➤here: https://github.com/wednesday-solutions/postman-tests

Now that you know how to write tests and set environment variables dynamically in Postman take a look at the following articles to unlock the full potential of Postman!

• https://learning.postman.com/docs/writing-scripts/test-scripts/
• https://learning.postman.com/docs/writing-scripts/script-references/test-examples/ - https://learning.postman.com/docs/writing-scripts/script-references/postman-sandbox-api-reference/

I hope you enjoyed this tutorial on postman-tests. If you have any questions or comments, please join the forum discussion below.

➤This blog was originally posted on https://wednesday.is To know more about what it’s like to work with Wednesday follow us on: Instagram|Twitter|LinkedIn