Introduction to Postman

Postman is a Chrome add-on and application which is used to fire requests to an API.

Features:

  • Very lightweight and fast
  • Requests can be organized in groups (called collections) and folders
  • Tests can be created with verifications for certain conditions on the response
  • Share workspaces or collections with other people or teams
  • Publish collections as API documentation
  • Run tests on collections (using the Collection Runner or Newman)
  • Monitor collections
  • Setup mock servers

Download the application here: https://www.getpostman.com/downloads/

Table of Contents

  1. Workspace
  2. Basic Requests
  3. Parameterized Data
  4. Tests
  5. JSON Schema Validation
  6. Collections
  7. Collection Runner
  8. Newman
  9. Monitors
  10. Dynamic Workflows
  11. Mock Servers

Workspace

Basic interface:

  1. New - This is where you will create a new request, collection or environment.
  2. Import - This is used to import a collection or environment. There are options such as import from file, folder, link or paste raw text.
  3. Runner - Automation tests can be executed through the Collection Runner. This will be discussed further in the next lesson.
  4. Open New - Open a new tab, Postman Window or Runner Window by clicking this button.
  5. My Workspace - You can create a new workspace individually or as a team.
  6. Invite - Collaborate on a workspace by inviting team members.
  7. History - Past requests that you have sent will be displayed in History. This makes it easy to track actions that you have done.
  8. Collections - Organize your test suite by creating collections. Each collection may have subfolders and multiple requests. A request or folder can also be duplicated as well.
  9. Request tab - This displays the title of the request you are working on. By default, “Untitled Request” would be displayed for requests without titles.
  10. HTTP Request - Clicking this would display a dropdown list of different requests such as GET, POST, COPY, DELETE, etc. In testing, the most commonly used requests are GET and POST.
  11. Request URL - Also known as an endpoint, this is where you will identify the link to where the API will communicate with.
  12. Save - If there are changes to a request, clicking save is a must so that new changes will not be lost or overwritten.
  13. Params - This is where you will write parameters needed for a request such as key values.
  14. Authorization - In order to access APIs, proper authorization is needed. It may be in the form of a username and password, bearer token, etc.
  15. Headers - You can set headers such as content type JSON depending on the needs of the organization.
  16. Body - This is where one can customize details in a request commonly used in POST request.
  17. Pre-request Script - These are scripts that will be executed before the request. Usually, pre-request scripts for the setting environment are used to ensure that tests will be run in the correct environment.
  18. Tests - These are scripts executed during the request. It is important to have tests as it sets up checkpoints to verify if response status is ok, retrieved data is as expected and other tests.

Basic Requests

The Postman Echo collection is included in your Postman app download. It’s a good way to try out different request types.

https://docs.postman-echo.com/?version=latest

GET Requests

Get requests are used to retrieve information from the given URL.

  1. Set your HTTP request to GET.
  2. In the request URL field, input the link
  3. Click Send
  4. You will see 200 OK Message
  5. The results in the body are shown at the bottom

POST Requests

Post requests are different from Get request as there is data manipulation with the user adding data to the endpoint.

  1. Set your HTTP request to POST.
  2. Input the link in request url. Ex. https://jsonplaceholder.typicode.com/users
  3. Switch to the Body tab

In the Body tab,

  1. Click a content type. If sending JSON data, click “raw”.

    a. Select a content type (Ex. JSON)

Make sure the data that you enter is formatted properly.

  1. Click Send.
  2. For this example, “Status: 201 Created” should be displayed
  3. Posted data shows up in the body

Parameterized Data

Instead of creating the same requests with different data, you can use variables with parameters. These data can be from a data file or an environment variable. Parameterization helps to avoid repetition of the same tests and iterations can be used for automation testing.

There are two types of variables – global and environment. Global variables are for all requests, environment variables are defined per specific environment which can be selected from a drop-down or no environment can be selected.

Parameters are created through the use of double curly brackets: {{sample}}.

Environments

To use the parameter, you need to set the environment:

  1. Click the eye icon
  2. Click edit to set the variable to a global environment which can be used in all collections.

For global variables

  1. Set the name of the variable and the value (which is https://jsonplaceholder.typicode.com in this example)
  2. Click Save.

Note: Always ensure that your parameters have a source, such as an environment variable or data file, to avoid errors.

Tests

For a lot of people, Postman is synonymous with API testing. For some, that might mean sending and inspecting a response. It could also mean writing assertions to validate that an endpoint is returning the appropriate responses. Or, it can also mean setting up logic to mirror your workflow and automating the tests.

The easiest way to get started with writing tests in Postman is to take a look at the snippets on the right side of the Tests tab. Clicking on a snippet will append the JavaScript code into the editor. You can also write your own test code.

The idea is that in many cases you will need to do something with the response and extract a variable from it in order to use it at a later stage. This can be done in “Tests” tab.

Without good tests, it’s impossible to have full confidence in your API’s behavior, consistency, or backward compatibility. As your codebase grows and changes over time, tests will save you time and frustration by spotting breaking changes.

Writing tests in Postman is easy and uses JavaScript syntax. Testing simple things, like HTTP status codes, response times, and headers can each be done in a single line of code

Many people use Postman Collections to document their APIs, either as a collection of example requests that can be easily shared among team members, or as public API documentation for customers. For both of those use cases, it makes sense for your collection to contain detailed explanations for each of your API endpoints, walkthroughs of common API workflows, authentication requirements, lists of possible error responses, etc.

A solid test suite will include many edge cases, intentional bad inputs (to test error handling), and possibly reveal sensitive information, all of which would be irrelevant or confusing for your API’s consumers.

For all of these reasons, it’s recommended that you keep your API tests in a separate collection from your API documentation.

Postman Tests are JavaScript codes added to requests that help you verify results such as successful or failed status, comparison of expected results, etc. It usually starts with pm.test. It can be compared to asserts, verify commands available in other tools.

  1. Switch to the tests tab. On the right side are snippet codes.
  2. From the snippets section, click on “Status code: Code is 200”.
  3. The example code will appear in the window.

Now click Send. The test result should now be displayed.

To compare the expected result to the actual result:

  1. From the snippets section, click on “Response body:JSON value check”.

Code reuse between requests

It is very convenient for some piece of code to be re-used between a request to prevent having to copy/paste it. It is possible to do it by defining a helper function with verifications which are saved as a global variable in the first request from your test scenario.

Then from other requests, the helpers are taken from global variables and the verification functions can be used.

Setting up helpers:

1
2
3
4
5
6
7
8
9
10
11
12
13
pm.globals.set("loadHelpers", function loadHelpers() {
    let helpers = {};

    helpers.verifyFoo1 = function verifyFoo1(value) {
        var jsonData = JSON.parse(responseBody);
        tests["Foo1 value is: " + value]
            = jsonData.args.foo1 === value;
    }

    // ...additional helpers

    return helpers;
} + '; loadHelpers();');

Using the saved helpers:

1
2
var helpers = eval(globals.loadHelpers);
helpers.verifyFoo1('bar1');

JSON Schema Validation

Many modern APIs use some form of JSON Schema to define the structure of their requests and responses. Postman includes the tv4 library, which makes it easy to write tests to verify that your API responses comply with your JSON Schema definitions.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// Define the JSON Schema
const jsonSchema = {
  "required": ["args"],
  "properties": {
    "args": {
      "type": "object",
      "required": ["foo1", "foo2"],
      "properties": {
        "foo1": {
          "type": "string",
          "enum": ["bar1"]
        },
        "foo2": {
          "type": "string",
          "enum": ["bar2"]
        },
        "foo3": {
          "type": "string",
          "enum": ["bar3"]
        }
      }
    }
  }
};

// Test whether the response matches the schema
var jsonData = JSON.parse(responseBody);
tests["Data is valid"] = tv4.validate(jsonData, jsonSchema);

Of course, you probably wouldn’t want to hard code your JSON Schema in your test script, especially since you may need to use the same schema for many requests in your collection. So, instead, you could store the schema as a JSON string in a Postman environment variable. Then you can simply use the variable in your test script, like this:

1
2
3
4
5
6
7
8
9
10
11
12
var jsonData = JSON.parse(responseBody);

// Load the JSON Schema
const jsonSchema = JSON.parse(globals.jsonSchema);

// Test if the JSON schema was found within the variables
tests["Schema found"] = !!jsonSchema;

if (jsonSchema) {
    // Test whether the response matches the schema
    tests["Data is valid"] = tv4.validate(jsonData, jsonSchema);
}

Resuse code

You can also reuse JavaScript code the same way by leveraging the eval() function.

There’s no limit to the amount of code that can be stored in a variable and reused this way. In fact, you can use this trick to reuse entire JavaScript libraries, including many third-party libraries from NPM, Bower, and GitHub.

First request in the collection:

1
2
3
4
5
6
7
8
9
10
11
12
// Save common tests in a global variable
postman.setGlobalVariable("commonTests", () => {
  // The Content-Type must be JSON
  tests["Content-Type header is set"] = postman.getResponseHeader("Content-Type") === "application/json";

  // The response time must be less than 500 milliseconds
  tests["Response time is acceptable"] = responseTime < 500;

  // The response body must include an "id" property
  var data = JSON.parse(responseBody);
  tests["Response has an ID"] = data.id !== undefined;
});

Other requests in the collection:

1
2
3
4
5
6
Other requests in the collection:
// First, run the common tests
eval(globals.commonTests)();

// Then run any request-specific tests
tests["Status code is 200"] = responseCode.code === 200;

Resources/Tutorials

Postman Tutorial for Beginners with API Testing Example

API testing tips from a Postman professional

Setting up a mock server

Setting up a monitor

Command line integration with Newman