Postman and Newman: A Comprehensive Guide to Command-Line API Testing

Postman has long been a popular tool for creating, testing, and debugging APIs in a user-friendly graphical interface. It is a crucial component of the( Application programming interface ) development lifecycle due to its flexibility and ease of use. 

But Newman, Postman's command-line assistant, takes the lead when it comes to automating API testing in a CI/CD pipeline or performing tests in bulk from the command line.

Newman offers a smooth method of incorporating API tests into automated workflows by allowing API professionals and developers to run Postman collections straight in the terminal with API testing reports in HTML format. 

Teams can validate endpoints, guarantee consistent testing across environments, and track API performance without manual intervention by using Newman.

In this blog, we will see the combination of Newman Postman, outlining how these tools can simplify and help in the development phase and  API testing, improve efficiency, and enhance reliability. 

This blog will walk you through the essentials of setting up, executing, and analyzing API tests with Newman Postman. Embrace this dynamic duo to streamline your API testing process and elevate your development practices.

🚀 What you’ll gain by reading further

📌 Understand how Newman complements Postman in automating API testing in CI/CD workflows.

📌 Learn detailed steps to set up Newman with Jenkins for seamless execution and reporting.

📌 Explore best practices for integrating API testing into pipelines effectively.

📌 Gain insights into Newman’s features, benefits, and comparisons with other command-line testing tools.

What is Newman and How does it Work with Postman? 

Newman is a powerful command-line companion tool for Postman, one of the most widely used REST API testing tools. While Postman simplifies API development and testing with its intuitive interface, Newman extends its capabilities by allowing developers and testers to automate API tests directly from the terminal. Additionally, Newman supports reusable test scripts, which can be incorporated into multiple test runs, reducing redundancy and improving efficiency. This makes Newman an ideal solution for integrating Postman collections into CI/CD pipelines, enhancing the reliability and scalability of API testing while promoting streamlined and consistent test execution.

Postman: A Brief Overview

Postman is a robust API testing app that supports the creation, testing, and debugging of APIs. It's considered one of the top web API testing tools due to its user-friendly interface and versatile features. With Postman, developers can:

• Create and organize collections of API requests.
• Write and execute test scripts.
• Share test cases with team members.
• Debug and monitor APIs efficiently.

However, testing manually through Postman may not always align with automated workflows. That’s where Newman steps in.

Newman: Bridging the Automation Gap

Newman complements Postman by enabling the execution of Postman collections through a command-line interface, supporting the entire API lifecycle. With features like environment variables and seamless integration into CI/CD pipelines, Newman ensures continuous testing across all development processes.

How Does Newman Work with Postman?

Newman executes Postman collections from the command line, enabling automation of API tests. It complements Postman by integrating collections into CI/CD pipelines and providing detailed test reports.

▶️Creating Collections in Postman:
Postman collections are the foundation of testing workflows. They consist of grouped API requests, preconditions, and test scripts. For example, a collection might test endpoints for user authentication, data retrieval, or updates in a RESTful API.

▶️Exporting Collections:
After creating a collection in Postman, export it in JSON format. Alongside the collection, export the environment variables in JSON format as well. These exported files serve as inputs for Newman, allowing dynamic and flexible execution of tests across different environments.

▶️Running Tests with Newman:
Once the collection is exported, you can run it with either CLI tool. For example, if you called your exported collection file “my_collection.json”, then you would run the following commands:

1. In the Postman CLI:
   $ postman collection run my_collection.json
2. In Newman:
   $ newman run my_collection.json

This is ideal for Postman REST API testing, especially in scenarios that require automation.

▶️Integrating with CI/CD

Newman significantly enhances the API testing process by integrating Postman into CI/CD CI/CD ( Continuous integration and continuous deployments ) pipelines. It works seamlessly with tools such as Jenkins, GitLab CI/CD, and GitHub Actions, allowing teams to automate the execution of API tests whenever code is pushed to a repository. 

This automation ensures that the latest version of the code is tested continuously, reducing the risk of introducing bugs and ensuring APIs function correctly throughout the development lifecycle. By running tests automatically after every deployment, developers can catch issues early, enhancing the overall quality and stability of the application. This feature transforms Postman into a powerful, scalable API testing service, capable of handling automated tests in a way that aligns with modern DevOps practices.

▶️Reporting and Analysis

One of the key benefits of using Newman is its ability to generate detailed reports after executing tests. These reports, available in HTML or JSON formats, provide insights into the performance of individual endpoints, including error messages and issues encountered. 

Test results highlight successful and failed requests, offering actionable insights for identifying bottlenecks or failures in the API. Annual reports summarize performance trends over time, helping teams make data-driven decisions and improve API reliability. This ensures that APIs maintain optimal performance and reliability, both during testing and in production.

Installing Newman: Setting Up Your Postman Testing Environment

Newman is a command-line tool that enables you to execute Postman collections directly from your terminal. It’s perfect for automating your Postman API testing and integrating it into CI/CD pipelines. Here’s a step-by-step guide to help you set up Newman and integrate it with Postman for efficient API testing.

Step 1: Install Node.js

Newman is built on Node.js, so the first step is to install it on your system.

1. Go to the Node.js download page.
2. Download the latest stable version based on the operating system.
3. Follow the installation instructions based on your OS (Windows, macOS, Linux).

Install Newman globally so you can run it anywhere on the system. Use the following command:

$ npm install -g newman

Step 2: Export Postman Collection

Before you can use Newman, export your Postman collection.

1. Open Postman and select the collection you want to test.
2. Export the collection by clicking the three dots next to the collection name.
3. Choose the Collection v2.1 format and click Export.

Step 3: Run the Postman Collection with Newman

Now that Newman is installed and the Postman collection is ready, run the collection using the following command:

$ newman run <path-to-your-collection>.json

Replace <path-to-your-collection> with the actual path of the exported collection.

Generating API Test Reports with Newman for Postman Workflows

Newman allows you to generate detailed API testing reports in HTML format for Postman test collections by using the newman-reporter-htmlextra package. 

This improved HTML reporter has several tabs with comprehensive request and test execution information, as well as a dashboard-style summary page. Additionally, Newman supports reusable test scripts, enabling the reuse of common validation logic across different collections or requests. 

This improves efficiency and consistency in testing. The following steps outline how to install and generate an HTML report, integrating reusable test scripts for streamlined testing processes.

Step 1: Install “Newman-reporter-htmlextra”

To generate an enhanced HTML report, install the newman-reporter-htmlextra package globally. This reporter offers a customizable, visually appealing dashboard and provides detailed insights into your API tests.

$ npm install -g newman-reporter-htmlextra

Step 2: Export Postman Collection

Before generating a report, you must export your Postman API collection.

1. Open Postman and locate the collection you want to test.
2. Click the three dots (or ellipsis) next to the collection name.
3. Select Export from the dropdown menu.
4. Choose the Collection v2.1 format (recommended for compatibility with Newman).
5. Save the exported JSON file to a folder on your system where you can easily access it.

Step 3: Run Collection and Generate Report

We can use Newman to run tests on the exported collection and create an HTML report.
Run the following command in the terminal:

$ newman run <path-to-collection-file>.json -r htmlextra

Replace <path-to-collection-file> with the actual path to your JSON file. For instance, if your file is saved in Documents, your command might look like:

$ newman run ~/Documents/my_collection.json -r htmlextra

In the current working folder, Newman will create a directory called ./newman. This directory contains the generated .html report.

Step 4: View the HTML Report

Navigate to the ./newman directory using File Explorer or command prompt. Double-click the .html report file to launch it in your preferred browser after getting it in the current directory.

The HTML report includes:

• A dashboard summary showing the total iterations, assertions, skipped, passed, and failed tests.
• A Total Requests tab, provides details about
  • Request method and URL.
  • Request body and headers.
  • The response body, headers, correct response and status codes.
  • Processing time and size metrics.

• A Failed Tests tab displays details of failed tests, including assertion errors, response information, response codes, the response body, and potential issues like timeouts, incorrect API endpoints, or authentication failures. Comprehensive tests ensure robust validation, while collection run reports provide a detailed overview of all test outcomes. This helps in debugging by offering insights into the root cause of failures, guiding the resolution of common API issues, and enhancing the accuracy of subsequent runs through actionable feedback.

By following these steps, you can seamlessly integrate Newman into your testing workflow, gaining detailed insights into your API’s performance and functionality. The visually appealing HTML reports simplify collaboration, analysis, and decision-making.

Using Newman Command-Line Options for Custom API Testing

Newman offers a robust set of command-line options, enabling users to execute Postman collections and customize their API testing workflows efficiently. By leveraging these options, you can control every aspect of the test run, from environment management to advanced configurations like request delays and timeout settings. Here’s an overview of its key features:

🟦Basic Commands

• -h, --help: Displays available commands and use cases, serving as a starting point for beginners.
• -v, --version: Fetches the currently installed Newman version for version management.

🟦Executing Collections

The command Newman run <collection-file> is the foundation of Newman’s operation. Users can specify environment and global variables or define multiple iterations of a collection:

• -e <source>, --environment: Define an environment file for variable usage.
• -g <source>, --globals: Input global variable files, which can override default settings.
• -n <number>, --iteration-count: Set the number of iterations for testing scalability.

For fine-tuned execution, use:

• --folder <name>: Focus testing on specific folders or requests within a collection.
• --working-dir <path>: Define a directory for files referenced relatively.

🟦File Management and Exporting

Newman supports the export of environment, global, and collection data for enhanced collaboration and debugging:

• --export-environment <path>: Save updated environment variables.
• --export-globals <path>: Archive the final state of global variables.
• --export-collection <path>: Output the modified collection.

Cookie management is simplified with:

• --cookie-jar <path>: Load cookies for session management.
• --export-cookie-jar <path>: Save cookies after a test run.

🟦Timeouts and Customization

• --timeout <ms>: Set a maximum duration for the collection run.
• --timeout-request <ms>: Configure the wait time for individual requests.
• --timeout-script <ms>: Specify time limits for script execution.

To simulate real-world scenarios, Newman offers:

• --delay-request: Introduce delays between requests to mimic actual API usage patterns.

🟦Error Handling and Output Management

• --bail: Stop tests on errors, with optional flags like a folder to manage incomplete runs.
• -x, --suppress-exit-code: Suppress the default exit code, useful in automated pipelines.
• --color: Toggle colored output for better readability.

Verbose mode (--verbose) enhances debugging by showing in-depth details of each request.

Best Practices for Using Newman and Postman in Automated API Testing

Automated API testing is an integral part of modern software development, ensuring the reliability, scalability, and performance of APIs. 

By combining Postman & Newman, you can create a robust testing platform. To maximize efficiency and accuracy, follow these best practices for using Newman and Postman in automated API testing.

1. Organize Your Collections

Organize your Postman collections systematically. Group related APIs in collections and subfolders to make navigation easier. Use descriptive names for collections, folders, and requests to ensure clarity for all team members.

2. Use Environment Variables

Leverage Postman’s environment variables to manage API endpoints, tokens, or parameters. This makes your collections reusable across multiple environments (development, staging, production). Use global variables sparingly to avoid conflicts.

3. Write Clear and Maintainable Tests

Keep your test scripts concise and focused. Use Postman’s built-in testing framework to validate responses. Write tests to check:

• Status codes (e.g., 200 OK, 400 Bad Request).
• Response time.
• JSON schema validation.

For reusable test logic, use pre-request and test scripts.

4. Integrate Newman with CI/CD Pipelines

Automate your testing process by integrating Newman with CI/CD tools like Jenkins, GitHub Actions, or GitHub CI/CD. This ensures API tests run automatically with a dedicated testing environment after code changes, providing immediate feedback.

5. Generate Reports for Analysis

Use Newman’s reporters, like htmlextra, to generate detailed HTML API testing reports for each test run. Reports provide insights into failed tests, performance metrics, and response data, aiding in debugging and performance tuning.

6. Implement Data-Driven Testing

Use Postman’s data file feature to run tests with multiple datasets. This allows you to validate APIs against varied input scenarios, ensuring robustness. Use CSV or JSON files as input for Newman.

7. Monitor API Performance

Track response times and error rates during testing. Postman & Newman can log these metrics, helping you identify bottlenecks or unstable endpoints. Integrate with monitoring tools like New Relic for continuous API performance tracking.

8. Version Control Your Collections

Export and version control your Postman collections using Git. This ensures the team has access to the latest updates and can roll back changes if needed.

9. Use Custom Templates for Reports

Enhance your reporting with custom templates. Newman’s HTML reports can be tailored to include additional metrics or branding, making them suitable for stakeholders.

10. Foster Team Collaboration

Use Postman’s collaboration features to share collections and environments with your team. This ensures consistency in testing and simplifies onboarding for new members.

Comparing Newman with Other Command-Line Testing Tools

Conclusion

Newman, the command-line collection runner for Postman, streamlines API testing in the development process by automating Postman collections. 

With robust features, it supports various scenarios, validates API responses, and generates detailed reports, including custom insights like response bodies and assertion errors.

Seamlessly integrating with CI/CD pipelines, Newman ensures continuous testing and deployment while supporting environment variables for dynamic configurations. 

By complementing Postman’s capabilities, Newman enhances efficiency and scalability across the API lifecycle, making it an essential tool for delivering high-quality APIs and optimizing modern development workflows.

Review Newman’s detailed error logs and the generated reports for issues like invalid endpoints, timeouts, or failed assertions. Use the --verbose flag to get more comprehensive details.

People also asked

👉Can Newman generate detailed reports for my API tests?

‍Yes, Newman generates detailed API testing reports, including formats like HTML, JSON, and CLI summaries. These reports offer insights into passed/failed tests, assertion errors, and performance metrics.

👉Can Newman execute collections hosted on Postman Cloud?

‍Yes, Newman can execute Postman Cloud-hosted collections using the Postman API. You need an API key and the collection's URL to enable seamless execution.

👉What are the advantages of running API tests with Newman?

‍Newman automates API testing via the command line, integrates with CI/CD pipelines, and supports reusable scripts. It also ensures consistency across environments with dynamic configurations using environment variables.

👉How do I handle environment variables in Newman?

‍You can specify environment variables using the --environment option with a JSON file or URL. You can also set individual variables inline using --env-var.

👉How do I troubleshoot errors during collection execution in Newman?

‍Review Newman’s detailed error logs and the generated reports for issues like invalid endpoints, timeouts, or failed assertions. Use the --verbose flag to get more comprehensive details.

‍