Automated API Tests with Postman and Newman

Postman is an essential tool for any REST API developer, allowing them to craft the most detailed requests to test and validate their API logic. After development is complete, Postman can also be used to create HTTP-based tests much quicker than with traditional code.

Tests can include custom logic that tests any part of the response (body contents, status codes, headers, etc.). Postman’s internal test runner can execute tests simply by selecting “Run collection” from the Collection’s three-dot context menu.

With the Newman add-on, Postman test collections can easily be run from the command-line, providing a simply way to execute them as part of a code build or CI process.

Sample Project Posted on GitHub

I posted a project containing a sample Node.js REST API and Postman tests to GitHub. The project README.md contains instructions on how to run the REST API, and execute the tests from the command-line with Newman.

The remainder of this article will cover the various aspects of creating and executing the Postman Test Collection, which is available as part of the sample project here. This Collection can be imported into Postman locally for reference.

Defining the Tests

Tests created with Postman are centered around Requests. Requests can be used to simulate a possible response/outcome of the REST API. Tests are then created to confirm specific aspects of the response (body contents, status codes, etc.). A single request can have multiple Tests associated with it. The Postman collection featured in the sample project contains six different requests.

Each of the Requests listed above has a set of Tests defined for it, visible on the “Tests” tab. These tests are written with JavaScript, and are used to confirm aspects of the expected response. Check out the Postman documentation for more info on writing Tests.

Using Collection Variables for Connection Information

When working with Postman, Variables are commonly used to store connection information and authentication details. This way, the values only need to be updated in one place if details change or differ between environments. The sample Postman Collection provided defines the API endpoint and authentication information at the Collection level so that all Requests can easily inherit this information.

Building and Running the Sample REST API

The REST API must be running and accessible in order to execute the Postman tests. To build and run the sample REST API, execute the following commands inside the sample project root folder:

npm install
npm start

The REST API should now be available at http://localhost:3000. In the Postman Test Collection, the API endpoint is captured in the API_ENDPOINT variable defined at the Collection level.

Executing Postman Tests from the Command-Line

As mentioned before, the Postman tests can be executed by selecting “Run collection” from the sample Collection’s three-dot context menu. However, these Tests can also be run from the command-line with Newman. Once Newman is available, simply execute:

newman run it/postman/integration_tests.postman_collection.json

The sample Tests will run and produce a summary report similar to the following:

Modifying Connection Information

If running these tests inside of a CI pipeline or other environment, the connection and authentication information may be different. Fortunately in the sample Collection, this information was defined using Variables.

Newman supports defining (or overriding) Variables at execution time using the -e flag and pointing to a JSON file defining the “environment”. The sample project contains an example of an environment JSON file with the following contents/structure:

{
  "values": [
    {
      "key": "API_ENDPOINT",
      "value": "http://localhost:3000",
      "enabled": true,
      "type": "text"
    },
    {
      "key": "API_USER",
      "value": "admin",
      "enabled": true,
      "type": "text"
    },
    {
      "key": "API_PASSWORD",
      "value": "admin",
      "enabled": true,
      "type": "text"
    }
  ]
}

Simply update these values as needed, and make sure the -e flag is included in any subsequent Newman calls:

newman run it/postman/integration_tests.postman_collection.json -e it/postman/localhost-environment.json