Usage Guide: How to Use Postman Newman

To significantly improve the efficiency of API testing, it's often necessary to use Newman, the command-line tool for Postman. This article provides a comprehensive guide on how to use Newman.

What is Newman?

Newman is a tool used for API testing and documentation in Postman, which is a GUI-based application. In contrast, Newman has a command-line interface, allowing you to do the following:

• Automate API testing and integrate it into CI/CD.
• Analyze test results programmatically
• Execute large volumes of requests via scripts

Developed in Node.js, Newman can run collections and environments created in Postman. It also features reporting capabilities to output test results in JSON or HTML formats.

By combining Postman with Newman, you can achieve the convenience of a GUI with the flexibility of scripting, making it an ideal tool for API test automation.

Installing and Running Newman

To start using Newman, you first need to download and install it on your computer. If you are not familiar with this step, please refer to the following tutorial.

Installing Newman

Newman is developed on the Node.js framework, so it is necessary to have Node.js installed to run it. If you have not installed Node.js yet, please visit the official Node.js website to download it. Ensure that the Node.js version is V4 or higher. Once Node.js is installed on your computer, follow the steps below to install and run Newman.

Use the following NPM command to install Newman globally on your system:

$ npm install -g newman

Running Newman

After installing Newman on your computer, the simplest way to execute it is to run it from a collection file using the following command line:

$ newman run mycollection.json

The collection might be using variables, so to provide a set of accompanying environment variables, you can export a template from Postman and execute it using the -e flag:

$ newman run https://www.postman.com/collections/cb208e7e64056f5294e5 -e dev_environment.json

Test Report Sample

When you run an API collection with Newman, a test report is generated to display the results of the tests. A sample of the test report is as follows:

→ Status Code Test
  GET https://postman-echo.com/status/404 [404 Not Found, 534B, 1551ms]
  1. response code is 200

┌─────────────────────────┬──────────┬──────────┐
│                         │ executed │   failed │
├─────────────────────────┼──────────┼──────────┤
│              iterations │        1 │        0 │
├─────────────────────────┼──────────┼──────────┤
│                requests │        1 │        0 │
├─────────────────────────┼──────────┼──────────┤
│            test-scripts │        1 │        0 │
├─────────────────────────┼──────────┼──────────┤
│      prerequest-scripts │        0 │        0 │
├─────────────────────────┼──────────┼──────────┤
│              assertions │        1 │        1 │
└─────────────────────────┴──────────┴──────────┘
│ total run duration: 1917ms                    │
├───────────────────────────────────────────────┤
│ total data received: 14B (approx)             │
├───────────────────────────────────────────────┤
│ average response time: 1411ms                 │
└───────────────────────────────────────────────┘

  #  failure        detail

  1.  AssertionFai…  response code is 200
                    at assertion:1 in test-script
                    inside "Status Code Test" of "Example Collection with
                    Failing Tests"

This test report displays the execution status of the tests. If any test items fail, the report provides detailed information about the cause of the failure, which is very useful. Additionally, you can export the test report to a JSON file using the following command line:

$ newman run mycollection.json --reporters cli,json --reporter-json-export outputfile.json

Using Newman in CI/CD

By default, if all tests execute successfully, Newman exits the process with a status code of 0. You can use your CI/CD tool to validate Newman’s status code to determine the test results. Additionally, if an error occurs and the status code is 1, you can use the --bail flag to stop Newman. This error can also be detected by your CI tool or build system.

Command Options Available in Newman

Newman offers numerous command options. You can check the available options by using the -h flag.

$ newman run -h

Below is a table listing the command options available in Newman:

EchoAPI:A more comprehensive API management tool

EchoAPI is an ultra-lightweight collaboration tool for API development that supports Scratch Pad. It's a perfect alternative to Postman, offering features like API design, debugging, automated testing, and load testing.

Why Choose EchoAPI?

1. No login required
2. Supports Scratch Pad
3. Ultra lightweight
4. 100% compatible with Postman script syntax

Furthermore, EchoAPI also offers a free online web application and downloadable versions for Mac, Windows, and Linux. Additionally, like Postman's Newman, it provides CLI tool, so no matter what device you want to use EchoAPI on, EchoAPI can accommodate it.

Plus, it comes with plugins for IntelliJ IDEA(EchoAPI for IntelliJ IDEA), extension for VS Code(EchoAPI for VS Code), and a Chrome request capture extension(EchoAPI Interceptor), all without the need to log in.

EchoAPI CLI

EchoAPI-Cli is a command-line tool designed to execute EchoAPI interface cases and test cases. It allows you to easily run and test these cases directly from the command line.

It is built for scalability, making it easy to integrate with continuous integration servers and build systems. This enables the automation of testing and execution of EchoAPI interface cases without manual intervention.

This module is currently open source.

Github: https://github.com/EchoAPI-Team/echoapi-cli

NPM: https://www.npmjs.com/package/echoapi-cli?activeTab=readme

Installing EchoAPI CLI

EchoAPI CLI is the command-line tool for EchoAPI, primarily used for API test automation. EchoAPI CLI depends on Node.js. To use the CLI tool, please ensure that Node.js version 10 or higher is installed.

Installation Command:

npm install -g echoapi-cli

Using the above command, you can install EchoAPI globally on your system.

Tip: If you have an older version of echoapi-cli installed, please uninstall it first.

To list installed npm packages:

npm list -g --depth=0

Uninstall command:

npm uninstall -g echoapi-cli

Running EchoAPI CLI

echoapi run "https://app.echoapi.com/open/ci/automated_testing?ci_id=MTkzMDI0MTEwMDU2ODQ5NDA4OjEyOTMzMDc1MDgzNjc3NzEwOjEzMDcyNjE0MDg3OTQ2Mjcy\u0026token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxODE0NCwiaXNzIjoiYXBpcG9zdCIsImV4cCI6MTcxNzY5MDAxNX0.wNNw0MbsbobhDcAZmiXJQu6lmhWaES6E2y8YFyKkzm8" -n 5 -r cli,json

Options EchoAPI CLI

Usage: echoapi run [options] <url>
Options:
  -r, --reporters            Specify the type of test report, supports cli, html, json  (default: "cli")
  -n, --iteration-count      Set the number of iterations. Default value is 1
  -d, --iteration-data       Set the path of [public] test data for case iteration (JSON or CSV). If set, it will replace the default [public] test data.
  --external-program-path    Specify the file path of the [external program], default is the current execution directory of the command
  --out-dir                  Output test report directory, default directory is: /Users/mhw/echoapi-reports
  --out-file                 Output test report file name, no need to add suffix, default format is echoapi-reports-current YYYY-MM-DD HH:mm:ss
  --ignore-redirects <0/1>   Prevent EchoAPI from automatically redirecting requests that return 3XX status codes. 0 to prevent, 1 not to prevent (default: "0")
  --max-request-loop         Maximum number of redirects for 3XX redirects (default: 5)
  --timeout-request          Specify the timeout for interface requests (default: 0)
  --timeout-script           Specify the timeout for pre-execution/post-execution scripts (default: 5000)
  --delay-request            Specify the interval between requests (default: 0)
  -k, --insecure             Disable SSL verification (1 to disable, 0 to enable. default: 1) (default: 1)
  --ssl-client-cert-list     Path to the client certificate configuration file (JSON). This option takes precedence over sslClientCert, sslClientKey, and sslClientPassphrase.
  --ssl-client-cert          Specify the client certificate path (CRT file)
  --ssl-client-pfx           Specify the client certificate path (PFX file)
  --ssl-client-key           Specify the client certificate private key path (KEY file)
  --ssl-client-passphrase    Specify the client certificate password (for protected key)
  --ssl-extra-ca-certs       Specify additional trusted CA certificates (PEM)
  --web-hook                 Web-hook to send JSON report data to the specified URL (POST) after the task is completed
  -h, --help                 Display help for command

Example of Client Certificate Configuration File (JSON)

{
    "https://wwww.example.com:443": {
        "pfx": {
            "file_url": ""
        },
        "crt": {
            "file_url": ""
        },
        "key": {
            "file_url": ""
        },
        "password": ""
    },
    "https://*.echoapi.com:443": {
        "key": {
            "file_url": ""
        },
        "pfx": {
            "file_url": ""
        },
        "crt": {
            "file_url": ""
        },
        "password": ""
    }
}

Upgrade Version

Use the following command to upgrade the EchoAPI CLI tool:

npm install echoapi-cli@latest -g

Additionally, if necessary, you can use the EchoAPI CLI tool to integrate with CI/CD tools such as Jenkins.