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 tests 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. This automation brings 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
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:
Note: If you’re not familiar with GraphQL please take a few minutes to read the spec here. (https://graphql.org/)
As a first step start Postman, go to File → Import, and drag and drop the collection and the environment.
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 createUser.
2. Go to the Body tab and add this to the GraphQL variables section on the right
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:
The above code might be difficult to understand at first. Let’s look at the tough bits.
- pm here stands for Postman. It's an object that postman provides with a test method that you can execute.
- Here we check if the response from the API has an error. If there is no error it means that user creation was successful.
- 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.
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:
3 . Go to the Tests tab and add the following:
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 dependency goes in the environment which you can use to test a related API.
This API allows users to create a Todo. Let’s write the test for this
- Select createNote in the mutations folder.
2. Go to the Body tab and add the following
3. Go to the Tests tab and write the test as follows
The above test case checks if the note is created successfully with the right list and user id.
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
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)
- Create a yml file using this command
2. Add the following code to the yml file
Here is the explanation of the above code:
- 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 #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
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!
I hope you enjoyed this tutorial on postman tests. If you have any questions or comments, please join the conversation on twitter.