Writing tests in Postman

Everyone agrees that writing tests is important, but not everyone does it. As you introduce new code, tests ensure that your API is working as intended. You can write and run tests in Postman for each request.

As your codebase grows, you want to make sure you’re not breaking anything that was previously working. The higher your test coverage, the more flexible and bug-resistant your code will be, and the less time you’ll spend debugging hot fixes in production.

How advanced is your team when it comes to testing?

  1. Writing tests – Most people agree that writing tests is important, but writing the first test is sometimes the biggest hurdle to testing. Once you’ve written your first test, every subsequent step becomes infinitely more manageable.
  2. Code snippets – The first step is to use code snippets. These stubs demonstrate how a Postman test runs, how they’re structured, and show test results.
  3. Custom tests – The next step is to write your own custom tests. Use JavaScript to address common user flows and edge cases unique to your endpoints.
  4. Run the collection – Now it’s time to run your requests, along with their respective tests, together as a collection. There are several ways to run your tests – e.g. Postman’s collection runner, Postman’s command line tool Newman, or with a Postman scheduled monitor.
  5. CI / CD integration – If your team is churning out code, the last thing you want to do is manually run these tests every time someone has a bug fix or feature update. When in doubt, automate!

If you haven’t progressed to Step 5, keep reading.


What is a test in Postman?

With Postman, you can add scripts to your request to use dynamic variables, pass data between requests, and write tests. Code added under the Pre-request Script tab will execute before your request is sent, and code added under the Tests tab will execute after your response is received.

Tests are scripts written in JavaScript that are executed after a response is received. Tests can be run as part of a single request or run with a collection of requests.

In the Postman app, the request builder at the top contains the Tests tab where you write your tests. The response viewer at the bottom contains a corresponding Test Results tab where you can view the results of your tests.

To start building test cases quickly, commonly-used snippets are listed next to the test editor. Select a snippet to append the code to the test editor. If needed, update the stub with assertions specific to your endpoint’s expected response. Then, send the request to view the test results at the bottom.

Writing tests

You can also write your own custom tests in JavaScript. In addition to supporting the older style of writing tests, Postman has a newer PM API (known as the pm.* API) which is the more powerful way to write tests.

pm.test()

The pm.test() function is used to write test specifications inside the Postman test sandbox. Writing tests inside this function allows you to name the test accurately, and ensures that the rest of the script is not blocked in case of any errors.

Some things to know about the pm.test() function:

  1. The function accepts 2 parameters, the name of the test (as a string) and a function to return a boolean value.
  2. It can be used only in the Tests tab, after the primary Postman request has been sent.

Here are some examples:

There are also other helpers to use in conjunction with pm.test().

pm.expect()

The pm.expect() assertion function was built on the shoulders of the popular JavaScript test library ChaiJS BDD. Using a similar syntax, pm.expect() makes it easy to write readable tests, and you can deal with assertions of data from a response or variables.

pm.response.to.be.*

The pm.resonse.to.be object provides shorthands for frequently used response based checks. Using this family of assertions streamlines tests for response status types and body variations.

Check out these test examples and the Postman test sandbox to get started writing your own custom tests.

Test results

Now that you’ve written your tests, how do you know if they’re passing or failing?

After you run a request with tests, go to the Tests tab in the response viewer. You will see a list of your tests and whether the test has passed or failed. A boolean that evaluates to true is a passing test, and a boolean that evaluates to false is a failing test.

Running tests

When running a collection using the collection runner in the Postman app, you can view your tests running and the results in real time.

When running a collection using Postman's command line tool Newman, you can view your test results in the terminal.

Testing automation

You can automate your tests by integrating Postman’s command line tool Newman with your favorite Continuous Integration or Continuous Delivery tool, like Jenkins or Travis CI.

You can also automate your tests by scheduling a collection run with a Postman monitor.

And that’s it. If you haven’t progressed all the way to Step 5, then it’s time to get crackin.