Newman is a command-line tool for running Postman collections in v2.1 JSON format. It appears in existing API projects and CI systems, so QA benefits from understanding its commands and results. However, as of October 2026, the official documentation marks Newman as deprecated and no longer maintained. It cannot run v3 collections from newer Postman v12 workflows; Postman recommends its own CLI for further development.
What Newman actually runs
Its inputs are a collection, environment parameters, optional iteration data, and run settings. Its outputs are sent requests, executed assertions, errors, and reports. Newman does not turn arbitrary requests into tests: if a collection does not check business values, the runner will not add those checks. A successful process exit means only that execution satisfied the checks provided. A collection without assertions can produce a green result even when product behavior is completely wrong.
When to maintain an existing run
If the team already has a stable v2.1 collection, first establish its behavior and limitations, then plan a migration. Avoid changing the runner, test data, and entire contract simultaneously: discrepancies become difficult to explain. For a new project, evaluate the current Postman CLI or an appropriate testing framework first. The choice depends on execution, data, and maintenance needs; familiarity with the Newman name is not sufficient justification.
Reproducible dependencies and input files
Keep the runner as a project dependency, commit the lockfile, and use an organization-supported Node.js version compatible with the runner. Install dependencies in CI with npm ci. The repository should contain the collection, a safe environment template, test data, and run instructions. Secrets should come from the designated CI store into a temporary configuration file, which must be excluded from artifacts and deleted afterward. Do not put a real token in a public command or example.
The example below assumes Newman is already installed and pinned in the project. The environment.runtime.json file is generated before execution, and the reports folder is created beforehand. Run the commands sequentially. This illustrates an existing pipeline; it is not a recommendation to start a new project with a deprecated runner.
npm ci
npx --no-install newman run collections/orders.v2.1.json \
-e environment.runtime.json \
-d data/orders.json \
--reporters cli,junit \
--reporter-junit-export reports/orders.xmlExercise: API smoke testing in a pipeline
Suppose a collection creates a test order, reads it, then deletes it or marks it for cleanup. Input data includes a known product and quantity, the environment points to a test API, and the build is available at a recorded address. The run aims to detect a broken critical integration quickly after deployment, rather than cover every order scenario.
- 1.Check dependency availability and prepare a unique run marker. Created data should be distinguishable from data belonging to other jobs.
- 2.Execute the collection with checks for statuses, the identifier, amount, and subsequent retrieval. Assertions should confirm a consistent business result.
- 3.Preserve the exit code and JUnit report even on failure. The job should fail with a clear failure location; publishing the report must not conceal an execution error.
- 4.Intentionally change the expected amount on a separate verification branch. Both the assertion and pipeline should fail; then restore the correct value.
- 5.Check cleanup after a partial failure. Test orders should not accumulate even if retrieval fails after successful creation.
Iteration data and isolation
A data file is useful for multiple boundary values, but each row is not necessarily an independent test. If scripts store IDs and tokens in a shared scope, iterations may use another iteration's state. Clear temporary values before creating an object, avoid relying on previous run order, and explicitly specify the expected result for each row. Separating successful and negative scenarios is useful when their setup, assertions, and cleanup rules differ.
Exit codes and the meaning of a green job
Check the process exit code with a failing assertion, a network error, and a missing input file. Do not use --suppress-exit-code if the pipeline must block changes on failure. The --bail option changes stopping behavior, but stopping early may skip final cleanup. An XML file's existence does not establish success: the report may contain failures. Conversely, an artifact publishing error does not always indicate an API defect. Pipeline messages should distinguish these causes.
Postman compatibility
Always check collection format and script features. Newman does not support v3 or scripts from the Postman Package Library; interactive OAuth token acquisition should also not be assumed to carry over from the app to a headless run. Design usable credential acquisition and renewal separately for this scenario. Avoid bypassing compatibility problems by permanently disabling TLS verification or copying a token from an employee's personal session. That conceals the cause and makes nightly results unpredictable.
For network diagnostics, distinguish an inability to connect from a service error response. Check name resolution, proxy settings, and certificates in the job environment, then repeat one safe request. Avoid adding automatic retries to all state-changing operations: after a lost response, the server may already have created the object. When retries are needed, agree on their semantics with the contract and verify them using separate test data. A runner cannot decide independently whether a particular business operation is safe to repeat.
Migrating to Postman CLI
Preserve a reference run of one v2.1 collection: requests, assertion names, final statuses, and created data. Execute the same scenario with the new runner in the same controlled environment. Compare variable handling, scripts, iteration data, exit codes, and reports. Once verified, replace the command in one job and observe several routine runs. Migrate to v3 format separately, preserving an auditable change history and reproduction instructions.
Investigating failures and practical takeaways
Start with the first meaningful error. Later 404 responses may result from failed creation, while a timeout may indicate an unavailable test environment. Include the commit, build, environment, runner version, and sanitized diagnostics in the report; avoid attaching an entire runtime file containing secrets. Common mistakes include accidentally upgrading dependencies, ignoring exit codes, and treating request counts as coverage. Understand Newman as part of an existing stack, and build reliable API checks around explicit data, assertions, and a supported execution tool.