Skip to content

Latest commit

 

History

History
445 lines (364 loc) · 15.3 KB

MIGRATION.md

File metadata and controls

445 lines (364 loc) · 15.3 KB
Raw

Newman

Table of contents

  1. Updating to the latest version
  2. Migrating from V4 to V5
  3. Migrating from V3 to V4
  4. Migrating from V2 to V3

Updating to the latest version

If you're updating from an older version of Newman, make sure you read the rest of this document, to understand the changes.

1. Update Newman

$ npm update -g newman

2. Check Installation

$ newman --version          # Should show the latest version of Newman
$ npm show newman version   # Should show the same version as of above

Migrating from V4 to V5

Newman v5.0 drops support for Node v6 and v8. Also, the inbuilt URL and CSV processor are upgraded.

Upgrading Node.js

Newman v5 requires Node.js >= v10. Install Node.js via package manager.

Next-Generation URL Processor

Newman v5 introduces an improved URL processing system that fixes several limitations of the present URL processor around the aspects of parsing and encoding. Know more about the changes in this GitHub issue and this blog post.

CSV parser

The longstanding disparity between the Newman and Postman app's CSV parser is fixed.

Changed escape character to double-quotes

The default escape character is changed to " (double quote) from \ (backslash).

V4 CSV input
id, name
"\"1\"", "foo \"bar\" baz"
V5 equivalent
id, name
"""1""", "foo ""bar"" baz"

Relaxed parsing

  1. Preserve quotes inside unquoted field
  2. Discard inconsistent columns count
  3. Detect and exclude the byte order mark (BOM)

Migrating from V3 to V4

Newman v4.0 drops support for Node v4 and dropped support for v2 CLI options. Also, the inbuilt HTML reporter has been moved to a standalone reporter.

Upgrading Node.js

Newman v4 requires Node.js >= v6. Install Node.js via package manager.

Discontinued CLI Options

Newman v4 drops support for all the deprecated v2 CLI options, check V2 to V3 Migration Guide.
For the complete list of supported options, see the README

--no-color

This option is dropped because of the changes made to the color option. See the section below for more details.

Using color option

The behaviour of this option is changed in both CLI and Library. Unlike Newman v3.x, this option alone can be used to enable or disable colored CLI output.

CLI

1. Enabling colored output
V3 command
$ newman run collection.json --color
V4 equivalent
$ newman run collection.json --color on
2. Disabling colored output
V3 command
$ newman run collection.json --no-color
V4 equivalent
$ newman run collection.json --color off

Library

1. Enabling colored output
Using V3
newman.run({
    collection: 'collection.json',
    reporters: ['cli'],
    color: true
}, callback);
V4 equivalent
newman.run({
    collection: 'collection.json',
    reporters: ['cli'],
    color: 'on'
}, callback);
2. Disabling colored output
Using V3
newman.run({
    collection: 'collection.json',
    reporters: ['cli'],
    noColor: true
}, callback);
V4 equivalent
newman.run({
    collection: 'collection.json',
    reporters: ['cli'],
    color: 'off'
}, callback);

Note: The default behavior is to detect color support for the terminal and act accordingly. This behavior can be modified by setting the color option to on or off respectively.

Using HTML Reporter

The inbuilt HTML reporter has been moved to a standalone reporter. Install it with:

$ npm install -g newman-reporter-html

Installation should be global if newman is installed globally, local otherwise. (Remove -g flag from the above command for a local installation.)

The complete installation and usage guide is available here: https://github.com/postmanlabs/newman-reporter-html

Deprecated support for the v1 collection format

Newman >= v4 deprecates support for the v1 collection format.
Use the Postman Native app to export collections in the v2 format.

CSV auto parse

A fix has been made to avoid parsing numbers inside quotes.
Example, "000123" will not be parsed to 123 like before.

Fixes issues: #1100, #1215 & #1346

Default timeouts

All timeouts now have the default value of infinity. #1630

Migrating from V2 to V3

Newman v3.0 is a complete rewrite of Newman from the ground up, which works well with other Node libraries, and allows flexibility for future features such as parallel collection runs, or performing parallel requests within the same run. Above all, Newman now uses Postman Runtime in order to provide a consistent experience on Postman Apps and on CLI.

General overview of features

  1. Newman collection runs now happen with the run command. See sections below for more examples.
  2. More informative terminal output with colourful details of what went wrong, and most importantly, where it went wrong.
  3. Ability to load environment, globals, collections as well as iteration data from urls.
  4. Friendlier usage as a library. A lot of use-cases depend on the use of Newman as a Node library, and v3.0 is written with a library-first mindset.
  5. Internally things (by things, we usually mean code) have been better organised to allow faster implementation of features.

Changes since v2.x

Migrating to Newman v3.x for most simple use cases is a trivial affair. We have taken care to support older CLI options. Which means, if you upgrade, it should just work! Having said that, we would soon discontinue the older CLI options and you should start using the new ones. Furthermore, the new features are only available via the new CLI options.

Since Newman 3.x is a complete rewrite, expect it to have subtle behavioural differences when compared with Newman v2.x, your reports will look a bit different, the CLI output is a complete overhaul, your collection runs will inherit all the qualities of the new Postman Runtime (jQuery deprecation, discontinuation of DOM), etc. For a comprehensive list of usage changes across Newman V2 and V3, look at the table provided below.

As such, if there is something specific that not working with respect to v2.x or any workaround that you were doing, we will be glad to chat and find out if they can still be done. You can find us on our Community Forum.

HTML, XML and other outputs are now "reporters"

Newman v3 adopts a "reporter" model and as such features that were previously part of Newman core has now been moved into reporters. Consequently, the CLI options for these features are now accessible via --reporter-* options. You might also notice that some of the functionalities of reporters have been reduced even though the reporter outputs have become more detailed. This is to offload non-essential codebase away from Newman core and be later made pluggable into external reporter plugins.

--no-color is automated

Newman now automatically detects lack of colour support and as such this flag does not need to be explicitly provided any more. However, --no-color is still available to force not to use colors in terminal output.

Discontinued CLI Options

-S --noTestSymbols

This switch no longer has any effect. Newman v3 effectively handles unicode output on Windows Platform.

-p, --pretty

This switch used to render exported JSON files in newman v2 in a pretty format. Newman v3 always exports in pretty format and as such, this switch is now not needed. If you want to use compressed export formats, run the exported files through some JSON minifier.

V2 to V3 Migration Guide

The following tables enumerate the options that have either been deprecated / discontinued, or renamed in Newman V3. The V3 equivalents provided in the second column are intended for use with the run command (described below), and will not work in V2 mode. The original options from V2, still work (without run, of course) however, but will be removed in the next major Newman release.

In the V2 option status column, deprecated implies that the corresponding CLi option has been left for backward compatibility and will be removed in the next major Newman release. A status of discontinued implies that the option is no longer supported, or is implemented by default.

Options missing from the migration tables have been left as they were from Newman V2. For the complete list of supported options, see README.md

CLI

Sample use cases

1. A collection run with all basic options configured, excluding reporter actions
V2 command
newman --collection collection.json --environment env.json --data data.csv --globals globals.json --number 2 --exportGlobals globalOut.json --exportEnvironment envOut.json --delay 10 --requestTimeout 5000 --noTestSymbols --tls --exitCode --whiteScreen --avoidRedirects --stopOnError
V3 equivalent
newman run collection.json --environment env.json --iteration-data data.csv --globals globals.json --iteration-count 2 --export-globals globalOut.json --export-environment envOut.json --delay-request 10 --timeout-request 5000 --disable-unicode --suppress-exit-code --ignore-redirects --bail
2. A collection run with various reporter tasks
V2 command
newman --url https://a.com/collection.json --environment-url https://a.com/env.json --noColor --outputFile jsonOut.json --testReportFile xmlOut.xml --html htmlOutput.html --outputFileVerbose verboseOut.log
V3 equivalent
newman run https://a.com/collection.json --environment https://a.com/env.json --reporters cli,html,json,junit --reporter-json-export jsonOut.json --reporter-junit-export xmlOut.xml --reporter-html-export htmlOutput.html

CLI migration table

V2 CLI option V3 equivalent V2 option Status
-c --collection N.A Deprecated (Pass the collection file path without the collection flag)
-u --url N.A Deprecated (Pass the collection file URL without the collection flag)
--environment-url N.A Deprecated (Pass the environment file URL to -e --environment)
-f --folder --folder Deprecated. The V3 folder option has been reduced to --folder
-d --data -d --iteration-data Deprecated
-n --number -n --iteration-count Deprecated
-i --import N.A Deprecated
-p --pretty N.A Discontinued
-G --exportGlobals --export-globals Deprecated
-E --exportEnvironment --export-environment Deprecated
-y --delay --delay-request Deprecated
-r --requestTimeout --timeout-request Deprecated
-s --stopOnError --bail Deprecated
-j --noSummary --reporter-cli-no-summary Deprecated
-C --noColour --no-color Deprecated
-S --noTestSymbols --disable-unicode Discontinued
-l --tls N.A Discontinued
-x --exitCode -x --suppress-exit-code Deprecated (The V3 option takes no arguments, and forces an exit code of 0)
-w --whiteScreen N.A Discontinued
-o --outputFile --reporter-json-export Deprecated
-t --testReportFile --reporter-junit-export Deprecated
-H --html --reporter-html-export Deprecated
-O --outputFileVerbose N.A Discontinued
-R --avoidRedirects --ignore-redirects Deprecated

Library usage

Sample use cases

1. A collection run with all basic options configured, excluding reporter actions
V2 command
newman.execute({
    collection: 'collection.json',
    environment: 'env.json',
    data: 'data.csv',
    globals: 'globals.json',
    number: 2,
    exportGlobals: 'globalOut.json',
    exportEnvironment: 'envOut.json',
    delay: 10,
    stopOnError: true,
    requestTimeout: 5000,
    noTestSymbols: true,
    tls: true,
    exitCode: true,
    whiteScreen: true,
    avoidRedirects: true
}, callback);
V3 equivalent
newman.run({
    collection: 'collection.json',
    environment: 'env.json',
    iterationData: 'data.csv',
    globals: 'globals.json',
    iterationCount: 2,
    exportGlobals: 'globalOut.json',
    exportEnvironment: 'envOut.json',
    delayRequest: 10,
    bail: true,
    timeoutRequest: 5000,
    disableUnicode: true,
    suppressExitCode: true,
    ignoreRedirects: true
}, callback);
2 A collection run with various reporter tasks
V2 command
newman.execute({
    collection: 'https://a.com/collection.json',
    environment: {
        "id": "my-id",
        "name": "testEnv",
        "values": [
            {
                "key": "env",
                "value": "env2",
            },
            {
                "key": "data",
                "value": "env2",
            }
        ]
    },
    globals: [
        {
            key: "var1",
            value: "/get",
            enabled: true
        },
        {
            key: "var2",
            value: "Global Bar",
        }
    ],
    outputFile: 'jsonOut.json',
    testReportFile: 'xmlOut.xml',
    html: 'htmlOutput.html',
    outputFileVerbose: 'verboseOut.log'
}, callback);
V3 equivalent
newman.run({
    collection: 'https://a.com/collection.json',
    environment: {
        "id": "my-id",
        "name": "testEnv",
        "values": [
            {
             "key": "env",
             "value": "env2",
            },
            {
             "key": "data",
             "value": "env2",
            }
        ]
    },
    iterationData: [ {a: 1}, {a: 2} ],
    globals: [
        {
            key: "var1",
            value: "/get",
            enabled: true
        },
        {
            key: "var2",
            value: "Global Bar",
        }
    ],
    reporters: ['html', 'junit', 'json'],
    reporter: {
        html: {
            export: 'htmlOutput.html'
        },
        junit: {
            export: 'xmlOut.xml'
        },
        json: {
            export: 'jsonOut.json'
        }
    }
}, callback);

Library migration table

V2 options V3 equivalent V2 option Status
data iterationData Deprecated
number iterationCount Deprecated
delay delayRequest Deprecated
requestTimeout timeoutRequest Deprecated
noTestSymbols disableUnicode Discontinued
stopOnError bail Deprecated
exitCode suppressExitCode Deprecated
avoidRedirects ignoreRedirects Deprecated