DOCSEARCHbyAlgolia
Submit Docs

Newman Documentation

repository·develop·Indexed 27 days ago

https://github.com/postmanlabs/newman

Newman is a command-line collection runner for Postman (version 6.2.2) that allows developers to run and test Postman collections directly from the command line. It can be installed via NPM or Homebrew, used as a Node.js library, or deployed using official Docker images (alpine and ubuntu). Newman facilitates the integration of API testing into continuous integration (CI) servers and build systems, supporting features such as custom reporters, SSL client certificates, and proxy configuration.

Tokens
10.6K
Snippets
26
Records
68
Agent score
88%

What's inside Newman

  1. Available Newman Docker Images

    develop

    Newman provides two official Docker images for different use cases:

    • postman/newman:alpine: A lightweight version.
    • postman/newman:ubuntu: A standard Ubuntu-based version.

    Both images ship with the current Node LTS (Long Term Support) version.

  2. Migrate Newman Library usage from V2 to V3

    develop

    When using Newman as a library, replace newman.execute() with newman.run(). The configuration object keys have changed to align with the new V3 CLI structure.

    Key Changes:

    • data $\rightarrow$ iterationData
    • number $\rightarrow$ iterationCount
    • delay $\rightarrow$ delayRequest
    • requestTimeout $\rightarrow$ timeoutRequest
    • stopOnError $\rightarrow$ bail
    • avoidRedirects $\rightarrow$ ignoreRedirects
    • exitCode $\rightarrow$ suppressExitCode
    • noTestSymbols is discontinued (use disableUnicode if applicable).

    Reporter Configuration: Instead of top-level keys like outputFile or html, use the reporters array and a reporter object to specify export paths for each reporter type.

    // V3 Library Usage Example
newman.run({
    collection: 'collection.json',
    environment: 'env.json',
    iterationData: 'data.csv',
    globals: 'globals.json',
    iterationCount: 2,
    delayRequest: 10,
    bail: true,
    timeoutRequest: 5000,
    suppressExitCode: true,
    ignoreRedirects: true,
    reporters: ['html', 'junit', 'json'],
    reporter: {
        html: { export: 'htmlOutput.html' },
        junit: { export: 'xmlOut.xml' },
        json: { export: 'jsonOut.json' }
    }
}, callback);

  4. Migrate Newman CLI from V2 to V3

    develop

    When upgrading from Newman V2 to V3, you must switch from using the implicit execution mode to the explicit run command. Many V2 flags are deprecated or discontinued.

    Key Changes:

    • Use newman run <collection-file-or-url> instead of passing flags like --collection or --url.
    • Use --iteration-data instead of --data.
    • Use --iteration-count instead of --number.
    • Use --bail instead of --stopOnError.
    • Use --reporter-<type>-export for output files (e.g., --reporter-json-export instead of --outputFile).
    • Some options like --noTestSymbols, --tls, --whiteScreen, and --outputFileVerbose are discontinued and no longer supported.

  5. Run Newman using the alpine Docker image with local files

    develop

    To use collections, environment files, or save reports from your host machine, you must mount a local directory to the container. The default working directory in the image is /etc/newman.

    Mounting a volume to /etc/newman allows you to reference files directly by name in the newman run command.

    docker --volume="/home/postman/collections:/etc/newman" -t postman/newman:alpine run JSONBlobCoreAPI.json.postman_collection -r json --reporter-json-export newman-report.json

  6. Run Newman using a custom mount location

    develop

    If you mount your files to a directory other than /etc/newman, you have two options:

    1. Pass the full path to the collection and environment files in the run command.
    2. Change the working directory using the -w or --workdir flag to match your mount point.
    docker run --volume="/home/postman/collections:/etc/newman" -t postman/newman:ubuntu run JSONBlobCoreAPI.json.postman_collection -r json --reporter-json-export newman-report.json

  7. Migrate from Newman V4 to V5

    develop

    Newman v5 includes updates to Node.js requirements, URL processing, and CSV parsing:

    • Node.js Requirement: Requires Node.js >= v10.
    • URL Processor: Uses a next-generation URL processing system for improved parsing and encoding.
    • CSV Parser: The default escape character changed from \ (backslash) to " (double quote).

    V5 CSV Example (using double quotes for escaping):

    id, name
"""1""", "foo ""bar"" baz"

  8. Configure Reporters with Newman CLI

    develop

    Reporters format the output of a collection run. Use the -r or --reporters flag to specify which reporters to use.

    Note: The cli reporter is enabled by default in CLI mode. However, if you enable other reporters (like json), the CLI output will be suppressed unless you explicitly include cli in your list of reporters.

  9. Migrate from Newman V2 to V3

    develop

    Newman v3 is a complete rewrite that adopts a 'reporter' model and uses the Postman Runtime for consistency.

    • Reporter Model: Features previously in Newman core (like HTML/XML output) are now handled via reporters. Use --reporter-* options to configure them.
    • Discontinued CLI Options:
      • -S or --noTestSymbols: No longer needed; Newman handles Unicode on Windows automatically.
      • -p or --pretty: No longer needed; Newman v3 always exports in pretty format.

  10. Run collections via Postman API URIs

    develop

    You can run collections and environments directly using their Postman API URIs.

    1. Generate a Postman API key.
    2. Fetch collection/environment UIDs via the Postman API.
    3. Pass the full URIs to the newman run command using the --environment flag.
    newman run "https://api.getpostman.com/collections/$uid?apikey=$apiKey" \
    --environment "https://api.getpostman.com/environments/$uid?apikey=$apiKey"

  12. Install and use external reporters

    develop

    Newman supports external reporters following the newman-reporter-<name> naming convention.

    1. Install: Use npm install -g newman-reporter-<name> (use global installation if Newman is global).
    2. Use: Reference the reporter by its <name> (omit the newman-reporter- prefix) in the --reporters flag or the reporters array in the library API.