Newman - Postman CLI Runner

Common errors

• 'newman' is not recognized as an internal or external command, operable program or batch file.

  cause Newman is either not installed globally, or its npm global bin directory is not in your system's PATH environment variable.
  fix Install Newman globally: `npm install -g newman`. If already installed, ensure `$(npm config get prefix)/bin` (or `C:\Users\<YourUser>\AppData\Roaming\npm` on Windows) is in your system's PATH.

• Cannot find module 'newman' Require stack:

  cause You are trying to use Newman as a library in a Node.js project, but it's not installed as a local dependency or linked correctly.
  fix Install Newman as a local project dependency: `npm install newman`. If using TypeScript, also install types: `npm install @types/newman --save-dev`.

• Error: unable to open collection file "<filename.json>".

  cause The specified collection file path is incorrect, the file does not exist at that location, or there are file permission issues.
  fix Verify the file path and name are correct. Ensure the user running Newman has read permissions for the file. Use absolute paths, especially in CI/CD environments.

• Error: Node.js v<X> is not supported. Please upgrade to Node.js v16 or higher.

  cause You are running Newman v6 or newer on an unsupported Node.js version.
  fix Upgrade your Node.js environment to version 16 or later. For example, use `nvm install 16` and `nvm use 16`, or update your system's Node.js installation.

Warnings

• breaking Newman v6.0 and newer versions require Node.js v16 or higher. Older Node.js versions (e.g., v10, v12, v14) are no longer supported. Attempting to run Newman v6 on an unsupported Node.js version will result in runtime errors.
  Fix: Upgrade your Node.js installation to version 16 or newer. Use `nvm` or your system's package manager for Node.js management.
• breaking Newman v6 includes significant dependency upgrades, particularly for the Postman Runtime and `tough-cookie`. These updates were made to address security vulnerabilities and introduce new features like JWT and NTLMv2 authentication.
  Fix: Ensure your project's dependencies are compatible. Review the official Newman migration guide for any behavioral changes in the Postman Runtime or script execution logic, especially if you relied on older `tough-cookie` behavior.
• gotcha Newman does not natively support OAuth 2.0 authentication directly within collections. While Postman can handle OAuth flows, when running with Newman, you'll need to manually manage and provide access tokens (e.g., via environment variables or pre-request scripts) to your requests.
  Fix: Obtain OAuth 2.0 tokens externally (e.g., through a separate script or Postman's GUI) and pass them to Newman as environment variables (`--env-var 'token=your_token'`) or through a Postman environment file.
• gotcha When running Newman in CI/CD environments, ensure that collection, environment, and data files are accessible via absolute or correct relative paths. Path inconsistencies are a common source of 'file not found' errors, especially when the working directory differs from local development.
  Fix: Use absolute paths for collection, environment, and data files within CI scripts, or explicitly set the working directory for the Newman command. For example, `newman run $(pwd)/path/to/collection.json`.
• gotcha SSL certificate verification can cause issues with self-signed certificates or specific corporate proxies. Newman offers an `--insecure` option to bypass SSL certificate validation, but use it with caution in production environments.
  Fix: For development/testing, use `newman run --insecure ...`. For production, configure proper CA certificates using `--ssl-extra-ca-certs` or ensure your environment trusts the certificates.

Install

• npm install newman npm
• yarn add newman yarn
• pnpm add newman pnpm

Imports

• newman
  wrong:

  import { newman } from 'newman';
  const newman = require('newman').default;

  correct:

  import newman from 'newman';

  Newman is typically imported as a default export for programmatic use. While CommonJS `require` is `const newman = require('newman');`, ESM usage usually involves a default import for CJS interoperability.
• NewmanRunOptions
  wrong:

  import { NewmanRunOptions } from 'newman';
  import type NewmanRunOptions from 'newman';

  correct:

  import type { NewmanRunOptions } from 'newman';

  Type imports should use `import type` for clarity and to avoid bundling issues in TypeScript projects. The types are part of the main package.
• NewmanRunSummary

  import type { NewmanRunSummary } from 'newman';

  Import `NewmanRunSummary` as a type to access the structure of the run result object, useful for programmatic analysis and reporting.

Quickstart

This quickstart demonstrates how to programmatically run a Postman collection using Newman as a Node.js library, including specifying reporters and handling the run summary for success or failure states. It generates a temporary collection file and cleans it up after execution.

import newman from 'newman';
import path from 'path';
import fs from 'fs';

// Create a dummy collection file for demonstration
const dummyCollectionPath = path.resolve(__dirname, 'dummy-collection.json');
const dummyCollectionContent = {
  "info": {
    "_postman_id": "b8c5f2b8-f3d9-4b6a-8b1b-c7e1e4f9b8c2",
    "name": "Dummy API Tests",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Test Get Request",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "https://postman-echo.com/get?foo=bar",
          "protocol": "https",
          "host": ["postman-echo", "com"],
          "path": ["get"],
          "query": [
            {
              "key": "foo",
              "value": "bar"
            }
          ]
        }
      },
      "response": []
    }
  ]
};

fs.writeFileSync(dummyCollectionPath, JSON.stringify(dummyCollectionContent, null, 2));

console.log(`Running collection: ${dummyCollectionPath}`);

newman.run({
  collection: dummyCollectionPath,
  reporters: ['cli', 'json'],
  reporter: {
    json: {
      export: './newman-report.json'
    }
  },
  environment: {  // Example of passing environment variables programmatically
    values: [
      { key: 'baseUrl', value: 'https://postman-echo.com', enabled: true }
    ]
  }
}, (err, summary) => {
  // Clean up dummy file after run
  fs.unlinkSync(dummyCollectionPath);

  if (err) {
    console.error('Collection run encountered an error:', err);
    return;
  }

  if (summary.run.failures.length) {
    console.error('Collection run completed with failures:');
    summary.run.failures.forEach(failure => {
      console.error(`  - ${failure.error.message} in ${failure.source.name}`);
    });
  } else {
    console.log('Collection run completed successfully!');
    console.log(`Total requests: ${summary.run.stats.requests.total}`);
    console.log(`Total assertions: ${summary.run.stats.assertions.total}`);
    console.log(`Assertions failed: ${summary.run.stats.assertions.failed}`);
    console.log('JSON report generated at ./newman-report.json');
  }
});