{"id":15144,"library":"newman","title":"Newman - Postman CLI Runner","description":"Newman is a powerful command-line collection runner for Postman, enabling users to execute and test Postman collections directly from the command line without the Postman GUI. It is primarily designed for integration into continuous integration and continuous delivery (CI/CD) pipelines and other automated build systems to facilitate automated API testing. The current stable version is 6.2.2. While there isn't a fixed release cadence, the project is actively maintained, with major versions typically introducing Node.js compatibility updates and dependency upgrades (e.g., v6 was released in late 2023). Key differentiators include its seamless integration with Postman collections, support for various output reporters (CLI, JSON, JUnit, HTML), and its capability for programmatic use as a Node.js library, offering a robust solution for automated API testing workflows.","status":"active","version":"6.2.2","language":"javascript","source_language":"en","source_url":"git://github.com/postmanlabs/newman","tags":["javascript","newman","postman","api","testing","ci","rest-client","rest"],"install":[{"cmd":"npm install newman","lang":"bash","label":"npm"},{"cmd":"yarn add newman","lang":"bash","label":"yarn"},{"cmd":"pnpm add newman","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required runtime environment for execution. Newman is a Node.js module.","package":"node","optional":false}],"imports":[{"note":"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.","wrong":"import { newman } from 'newman';\nconst newman = require('newman').default;","symbol":"newman","correct":"import newman from 'newman';"},{"note":"Type imports should use `import type` for clarity and to avoid bundling issues in TypeScript projects. The types are part of the main package.","wrong":"import { NewmanRunOptions } from 'newman';\nimport type NewmanRunOptions from 'newman';","symbol":"NewmanRunOptions","correct":"import type { NewmanRunOptions } from 'newman';"},{"note":"Import `NewmanRunSummary` as a type to access the structure of the run result object, useful for programmatic analysis and reporting.","symbol":"NewmanRunSummary","correct":"import type { NewmanRunSummary } from 'newman';"}],"quickstart":{"code":"import newman from 'newman';\nimport path from 'path';\nimport fs from 'fs';\n\n// Create a dummy collection file for demonstration\nconst dummyCollectionPath = path.resolve(__dirname, 'dummy-collection.json');\nconst dummyCollectionContent = {\n  \"info\": {\n    \"_postman_id\": \"b8c5f2b8-f3d9-4b6a-8b1b-c7e1e4f9b8c2\",\n    \"name\": \"Dummy API Tests\",\n    \"schema\": \"https://schema.getpostman.com/json/collection/v2.1.0/collection.json\"\n  },\n  \"item\": [\n    {\n      \"name\": \"Test Get Request\",\n      \"request\": {\n        \"method\": \"GET\",\n        \"header\": [],\n        \"url\": {\n          \"raw\": \"https://postman-echo.com/get?foo=bar\",\n          \"protocol\": \"https\",\n          \"host\": [\"postman-echo\", \"com\"],\n          \"path\": [\"get\"],\n          \"query\": [\n            {\n              \"key\": \"foo\",\n              \"value\": \"bar\"\n            }\n          ]\n        }\n      },\n      \"response\": []\n    }\n  ]\n};\n\nfs.writeFileSync(dummyCollectionPath, JSON.stringify(dummyCollectionContent, null, 2));\n\nconsole.log(`Running collection: ${dummyCollectionPath}`);\n\nnewman.run({\n  collection: dummyCollectionPath,\n  reporters: ['cli', 'json'],\n  reporter: {\n    json: {\n      export: './newman-report.json'\n    }\n  },\n  environment: {  // Example of passing environment variables programmatically\n    values: [\n      { key: 'baseUrl', value: 'https://postman-echo.com', enabled: true }\n    ]\n  }\n}, (err, summary) => {\n  // Clean up dummy file after run\n  fs.unlinkSync(dummyCollectionPath);\n\n  if (err) {\n    console.error('Collection run encountered an error:', err);\n    return;\n  }\n\n  if (summary.run.failures.length) {\n    console.error('Collection run completed with failures:');\n    summary.run.failures.forEach(failure => {\n      console.error(`  - ${failure.error.message} in ${failure.source.name}`);\n    });\n  } else {\n    console.log('Collection run completed successfully!');\n    console.log(`Total requests: ${summary.run.stats.requests.total}`);\n    console.log(`Total assertions: ${summary.run.stats.assertions.total}`);\n    console.log(`Assertions failed: ${summary.run.stats.assertions.failed}`);\n    console.log('JSON report generated at ./newman-report.json');\n  }\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js installation to version 16 or newer. Use `nvm` or your system's package manager for Node.js management.","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Newman is either not installed globally, or its npm global bin directory is not in your system's PATH environment variable.","error":"'newman' is not recognized as an internal or external command, operable program or batch file."},{"fix":"Install Newman as a local project dependency: `npm install newman`. If using TypeScript, also install types: `npm install @types/newman --save-dev`.","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.","error":"Cannot find module 'newman' Require stack:"},{"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.","cause":"The specified collection file path is incorrect, the file does not exist at that location, or there are file permission issues.","error":"Error: unable to open collection file \"<filename.json>\"."},{"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.","cause":"You are running Newman v6 or newer on an unsupported Node.js version.","error":"Error: Node.js v<X> is not supported. Please upgrade to Node.js v16 or higher."}],"ecosystem":"npm"}