This installment of the API Testing series will focus on Postman. While Postman is now an API development suite for individual developers and teams, it got its start as a basic HTTP client for testing APIs. In this article, we'll use Postman to create an API test suite running against the Trello API.
Today in our API Testing Series we'll take a look at Postman. Along the way you'll create an API test suite running against the Trello APITrack this API, which is a real API with formal authentication tokens. You could also use this as a lite version, reading along to get a feel for whether or not Postman is something that you'd like to try. A real follow-through approach will require some setup. You'll need to create an account on Trello.com and generate an application key and a token to use the Trello API. Postman is a standalone tool, and you can download the latest version here.
Start by performing a simple POST command to create a new Trello card. You can see in the Trello API documentation that it has one required argument for the /cards endpoint idList. You can get instructions for finding that information on this page. Search for the header 'Finding a List ID'. Once you have that idList, save it in a text document with your application key and token. You'll need it throughout this exercise.
Select POST from the call type drop list next to the URL field in Postman. Enter the URL for the card's endpoint that includes your developer key and token in the query string that you saved earlier. That URL will look something like:
Your setup should look something like this by now.
Postman setup to POST to /cards in Trello API
Click the Send button. You'll have a response from the Trello server when the POST has completed. The JSON body will contain everything a card might contain, as well as some unique identifiers.
That is your first call in Postman. You'll now build a more substantial CRUD test now and explore collections in Postman. (CRUD stands for Create, Read, Update, and Delete.)
Collections in Postman
Most testers will want to make more than one call to an API at a time. Postman uses a tool called Collections to organize API calls, and also to use data from responses in future calls. For example, within a collection you can make a call to an API endpoint, capture data from the response, and use that in future calls so that your test harness consists of a bunch of calls that are chained together. Select the Collections tab in Postman and click the folder icon with a plus on it to create a new collection. You can name it whatever you like, I used 'Trello /card' to indicate that this is for the Trello API and the /card endpoint. Now you'll want to add calls to your collection. Return to the History tab where you have already performed a POST to /card. Select that call, and click the Save button. This will open a dialog you can use to save that call to your new collection.
In this screenshot you can see a collection called "Trello /card" that contains three requests (note that there's also another collection above that one called "Postman Echo" that consists of 21 requests). Of the three requests, one is a POST to create a new Trello card, one is a PUT that adds description text to that card, and then a DELETE (referred to as "DEL") that removes the card from your Trello board. There are a couple of other important things to note there. In the Tests tab, you'll see this bit of code:
var jsonData = JSON.parse(responseBody); postman.setEnvironmentVariable("trelloCardId", jsonData.id);
If it isn't obvious, the first line declares a variable called jsonData and initializes it with a parsed version of the response to the first of the API requests (the highlighted one on the left that's a POST). Then, you set an environment variable to the value associated with the key "id" (within that JSON response). To use this environment variable, you need to create an environment, and select that for your collection. Then, you'll be using this variable in future calls as a URL parameter. So, your first POST creates a new card and saves the id into the environment variable "trelloCardId." Your next PUT adds description text with a URL that adheres to the following syntax:
The text id inserts your saved Trello card id into the URL you're PUTing to in the second of the three requests:
You can see how easy it is to identify your new Trello card in future calls to the API. You'll also see this:
tests["Status code is 200"] = responseCode.code === 200;
This bit of code verifies that you get an HTTP 200 response status after the API call is made. If you get some other response, such as a HTTP 404, the test will fail. In the collection runner screen, you'll see an indicator by the failing test, along with the number of tests that failed.
You can add this, and other types of tests either by selecting them from what is available in the right sidebar or writing a very small amount of code yourself.
Once you have a collection created and some tests added to each call, you're ready to run it. You can open the collection runner by selecting the collection folder, clicking the arrow, and then clicking the Run button.
Click Start Test to see your three API requests, and all of the tests within each of the steps, and the Run button. The final state should look something like this:
Here you can see each of the calls made, the HTTP response, and each test that passed or failed in the API calls.
Postman also has a command line test runner available as an add-on if you'd like to run your API tests in a Continuous Integration system like Jenkins.
Like other UI-driven (as opposed to coded) API testing tools, Postman has many other embedded features aside from creating API calls and assertions on responses. You can learn about other aspects of the free and paid versions of Postman here.