Writing tests

You can write test scripts for your Postman API requests in JavaScript. Tests allow you to ensure that your API is working as expected, to establish that integrations between services are functioning reliably, and to verify that new developments haven't broken any existing functionality. You can also use test code to aid the debugging process when something goes wrong with your API project.

For example, you might write a test to validate your API's error handling by sending a request with incomplete data.

You can add tests to individual requests, folders, and collections. Postman includes code snippets you can click to add, then amend to suit your logic if necessary.

To add tests to a request, open the request and enter your code in the Tests tab. Tests will execute after the request runs. You will be able to see the output in the Test Results tab alongside the response data.

Writing test scripts

Your test scripts can use dynamic variables, carry out test assertions on response data, and pass data between requests. In the Tests tab for a request, you can enter your JavaScript manually or use the Snippets you'll see to the right of the code editor.

Tests will execute after the response is received, so when you click Send, Postman will run your test script when the response data returns from the API.

If you need to execute code before a request runs, use Pre-request Scripts instead. See Intro to scripts for more on the how your scripts execute when your requests run.

To carry out tests in order to validate the data returned by a request, you can use the pm.response object. You can define tests using the pm.test function, providing a name and function that returns a boolean (true or false) value indicating whether the test passed or failed. You can use ChaiJS BDD syntax and pm.expect in your assertions to test the response detail.

The first parameter for the .test function is a text string that will appear in the test result output, so you can use it to identify your tests, and communicate the purpose of a test to anyone viewing the results.

For example, enter the following in the Tests tab for any request to test whether the response status code is 200.

pm.test("Status test", function () {
    pm.response.to.have.status(200);
});

Click Send to run your request and open Test Results in the response section. The tab header displays how many tests passed and how many ran in total. You can also toggle between passed, skipped, and failed test results.

If the request returned a 200 status code, the test will pass—otherwise it will fail. Try changing the expected status code in your test script and running the request again.

Using the pm.expect syntax gives your test result messages a different format—experiment with the alternatives to achieve the output you find most useful.

Use the Run in Postman button in the Intro to writing tests collection to import templates containing some example test scripts into Postman and experiment with the code.

Your code can test the request environment, as in the following example:

pm.test("environment to be production", function () {
    pm.expect(pm.environment.get("env")).to.equal("production");
});

You can use different syntax variants to write your tests in a way that you find readable—and that suits your application and testing logic.

pm.test("response should be okay to process", function () {
    pm.response.to.not.be.error;
    pm.response.to.have.jsonBody("");
    pm.response.to.not.have.jsonBody("error");
});

Your tests can establish validity of request responses using syntax that you tailor to the response data format.

pm.test("response must be valid and have a body", function () {
     pm.response.to.be.ok;
     pm.response.to.be.withBody;
     pm.response.to.be.json;
});

Your scripts can include however many tests you need and will save along with the rest of your request detail when you click Save. If you share a collection, or publish documentation / the Run in Postman button, your test code will be included for anyone who views or imports your templates.

Using snippets

You will see a selection of commonly used test code excerpts in Snippets to the right of the tests editor. Click to add one and it will appear in your editor. Snippets can speed up the process of getting started with your scripts—you can edit snippets after adding them to meet your own testing requirements.

Testing collections and folders

You can add test scripts to a collection, a folder, or a single request within a collection. A test script associated with a collection will run after every request in the collection. A test script associated with a folder will run after every request in the folder. This allows you to reuse commonly executed tests after every request.

Adding scripts to collections and folders allows you to test the workflows in your API project. This helps to ensure that your requests cover typical scenarios, providing a reliable experience for application users.

You can update collection and folder scripts by clicking View more actions (...) next to the collection or folder name, and selecting Edit. Choose the Tests tab to add or update your script. You can also add collection scripts when you first create a collection.

When you run a collection you will see the test results output by the collection runner.

You can write scripts to control the order in which your requests run using branching and looping.

Next steps

Check out some test script examples and the Postman Sandbox API reference for what you can do using the pm object.

Using tests in conjunction with other Postman utilities such as monitoring lets you verify that your API meets performance requirements. You can also automate your testing by integrating collection runs within your CI/CD config.