@reportportal/agent-js-postman

Agent to integrate Postman (based on Newman collection runner) with ReportPortal.
* More about Postman
* More about Newman
* More about ReportPortal

Installation

The installation should be global if newman is installed globally, otherwise - local (replace -g from the command below with -S for a local installation).

``cmd
npm install --save-dev @reportportal/newman-reporter-agent-js-postman
`

Usage

There are two ways to enable this reporter - with command line or programmatically.

$3

To enable this reporter you have to specify agent-js-postman in Newman's -r or --reporters option.

`cmd
newman run https://postman-echo.com/status/200 \
-r @reportportal/agent-js-postman \
--reporter-@reportportal/agent-js-postman-debug=true \
--reporter-@reportportal/agent-js-postman-endpoint=https://your-instance.com:8080/api/v2 \
--reporter-@reportportal/agent-js-postman-api-key=reportportalApiKey \
--reporter-@reportportal/agent-js-postman-launch=LAUNCH_NAME \
--reporter-@reportportal/agent-js-postman-project=PROJECT_NAME \
--reporter-@reportportal/agent-js-postman-description=LAUNCH_DESCRIPTION \
--reporter-@reportportal/agent-js-postman-attributes=launchKey:launchValue;launchValueTwo \
--reporter-@reportportal/agent-js-postman-skipped-issue=false \
-x
`

Pay attention that you must add -x or --suppress-exit-code parameter while running newman using CLI.

$3

`javascript
const newman = require("newman");

newman.run(
{
collection: "./collections/newman-test_collection.json",
reporters: "@reportportal/agent-js-postman",
reporter: {
"@reportportal/agent-js-postman": {
apiKey: "",
endpoint: "https://your.reportportal.server/api/v2",
project: "Your reportportal project name",
launch: "Your launch name",
description: "Your launch description",
attributes: [
{
"key": "launchKey",
"value": "launchValue"
},
{
"value": "launchValue"
},
],
mode: "DEFAULT",
debug: false,
skippedIssue: false
}
}
},
function(err) {
if (err) {
throw err;
}
console.log("collection run complete!");
}
);

// To run several collections
// Note, this will create multiple launches, so you can merge into one manually via the UI or API
fs.readdir("./collections_folder_path", (err, files) => {
if (err) {
throw err;
}
files.forEach((file) => {
// setup newman.run()
});
});
`

Options

The full list of available options presented below.

$3

The agent supports two authentication methods:
1. API Key Authentication (default)
2. OAuth 2.0 Password Grant (recommended for enhanced security)

Note:\
If both authentication methods are provided, OAuth 2.0 will be used.\
Either API key or complete OAuth 2.0 configuration is required to connect to ReportPortal.

| Option | Necessity | Default | Description |
|--------|-------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| apiKey | Conditional | | User's ReportPortal API key from which you want to send requests. It can be found on the profile page of this user. *Required only if OAuth is not configured. |
| oauth | Conditional | | OAuth 2.0 configuration object. When provided, OAuth authentication will be used instead of API key. See OAuth Configuration below. |

#### OAuth Configuration

The oauth object supports the following properties:

| Property | Necessity | Default | Description |
|-----------------------|------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| tokenEndpoint | Required | | OAuth 2.0 token endpoint URL for password grant flow. |
| username | Required | | Username for OAuth 2.0 password grant. |
| password | Required | | Password for OAuth 2.0 password grant. |
| clientId | Required | | OAuth 2.0 client ID. |
| clientSecret | Optional | | OAuth 2.0 client secret (optional, depending on your OAuth server configuration). |
| scope | Optional | | OAuth 2.0 scope (optional, space-separated list of scopes). |

Note: The OAuth interceptor automatically handles token refresh when the token is about to expire (1 minute before expiration).

##### OAuth 2.0 configuration example

`javascript
const rpConfig = {
endpoint: 'https://your.reportportal.server/api/v2',
project: 'Your reportportal project name',
launch: 'Your launch name',
oauth: {
tokenEndpoint: 'https://your-oauth-server.com/oauth/token',
username: 'your-username',
password: 'your-password',
clientId: 'your-client-id',
clientSecret: 'your-client-secret', // optional
scope: 'reportportal', // optional
}
};
`

$3

| Option | Necessity | Default | Description |
|-----------------------|------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| endpoint | Required | | URL of your server. For example 'https://server:8080/api/v1'. |
| launch | Required | | Name of launch at creation. |
| project | Required | | The name of the project in which the launches will be created. |
| attributes | Optional | [] | Launch attributes. Programmatically - [{ "key": "YourKey", "value": "YourValue" }]
with CLI - "YourKey:YourValue;YourValueTwo" |
| description | Optional | '' | Launch description. |
| rerun | Optional | false | Enable rerun |
| rerunOf | Optional | Not set | UUID of launch you want to rerun. If not specified, reportportal will update the latest launch with the same name |
| mode | Optional | 'DEFAULT' | Results will be submitted to Launches page
'DEBUG' - Results will be submitted to Debug page. |
| skippedIssue | Optional | true | reportportal provides feature to mark skipped tests as not 'To Investigate'.
Option could be equal boolean values:
true - skipped tests considered as issues and will be marked as 'To Investigate' on reportportal.
false - skipped tests will not be marked as 'To Investigate' on application. |
| debug | Optional | false | This flag allows seeing the logs of the client-javascript. Useful for debugging. |
| launchId | Optional | Not set | The _ID_ of an already existing launch. The launch must be in 'IN_PROGRESS' status while the tests are running. Please note that if this _ID_ is provided, the launch will not be finished at the end of the run and must be finished separately. |
| restClientConfig | Optional | Not set | axios like http client config. May contain agent property for configure http(s) client, and other client options e.g. proxy, timeout. For debugging and displaying logs the debug: true option can be used.
Visit client-javascript for more details. |
| headers | Optional | {} | The object with custom headers for internal http client. |
| launchUuidPrint | Optional | false | Whether to print the current launch UUID. |
| launchUuidPrintOutput | Optional | 'STDOUT' | Launch UUID printing output. Possible values: 'STDOUT', 'STDERR', 'FILE', 'ENVIRONMENT'. Works only if launchUuidPrint set to true. File format: rp-launch-uuid-${launch_uuid}.tmp. Env variable: RP_LAUNCH_UUID, note that the env variable is only available in the reporter process (it cannot be obtained from tests). |

Asynchronous API

The client supports an asynchronous reporting (via the ReportPortal asynchronous API).
If you want the client to report through the asynchronous API, change v1 to v2 in the endpoint address.

Note: It is highly recommended to use the v2 endpoint for reporting, especially for extensive test suites.

Reporting API

$3

* To report attributes for suite you should use collection variables.

| VARIABLE | INITIAL VALUE | CURRENT VALUE |
|---------------|---------------------------|---------------------------|
| rp.attributes | keySuiteOne:valueSuiteOne | keySuiteOne:valueSuiteOne |

* To report attributes for tests inside of Pre-request Script you should use the next method

pm.environment.set

| Parameter | Required | Description | Examples |
|------------|----------|------------------------------------------------------------|------------------------------------------------|
| namespace | true | "string" - namespace, must be equal to the rp.attributes | "rp.attributes" |
| attributes | true | "string" - contains set of pairs key:value | "keyOne:valueOne;valueTwo;keyThree:valueThree" |

`javascript
pm.environment.set("rp.attributes", "keyOne:valueOne;valueTwo;keyThree:valueThree");
`
* Step doesn't support reporting with attributes

$3

Both suites and tests support description. For reporting with description you should click on Edit in your collection
and in the description column enter the text you need

* Step doesn't support reporting with description

$3

status must be equal to one of the following values: passed, failed, stopped, skipped, interrupted, cancelled, info, warn.

* To finish launch/suite with status you should use collection variables

| VARIABLE | INITIAL VALUE | CURRENT VALUE |
|--------------------------------------------------------|---------------|---------------|
| rp.launchStatus (for launch)
rp.status (for suite) | your status | your status |

* To finish tests you should use environment variables inside of Pre-request Script
`javascript
pm.environment.set("rp.status", "status");
`
* To finish steps with statuses you should use local variables
`javascript
pm.variables.set("rp.status", "status");
`
It is important that the code line above has to start from the new line and you shouldn't forget about semicolon after it

For both tests or steps, this is true

| Parameter | Required | Description | Examples |
|-----------|----------|--------------------------------------------------------|-------------|
| namespace | true | "string" - namespace, must be equal to the rp.status | "rp.status" |
| status | true | "string" - status | "passed" |

$3

You can use the following methods to report logs with different log levels:

* console.log("launch/suite/test", "message");
* console.log("launch/suite/test", "message", "level");
* console.error("launch/suite/test", "message");
* console.debug("launch/suite/test", "message");
* console.warn("launch/suite/test", "message");
* console.info("launch/suite/test", "message");

| Parameter | Required | Description | Examples |
|-----------|----------|--------------------------------------------------------------------------------------------------------|----------------|
| namespace | true | "string" - namespace, must be equal to the launch, suite or test depends on where you want to report | "test" |
| message | true | "string" - message | "your message" |
| level | false | "string" - log level. Can be either predefined (trace, debug, info, warn, error, fatal) or any custom string | "info" |

* Step doesn't support logs reporting

$3

* To report suite with test case id you should use collection variables

| VARIABLE | INITIAL VALUE | CURRENT VALUE |
|---------------|---------------------|---------------------|
| rp.testCaseId | yourSuiteTestCaseId | yourSuiteTestCaseId |

* To report tests with test case id you should use environment variables inside of Pre-request Script
`javascript
pm.environment.set("rp.testCaseId", "yourTestCaseId");
`
* To report steps with test case id you should use local variables
`javascript
pm.variables.set("rp.testCaseId", "stepTestCaseId");
``
It is important that the code line above has to start from the new line and you shouldn't forget about semicolon after it

For both tests or steps, this is true

| Parameter | Required | Description | Examples |
|------------|----------|------------------------------------------------------------|------------------|
| namespace | true | "string" - namespace, must be equal to the rp.testCaseId | "rp.testCaseId" |
| testCaseId | true | "string" - test case id value | "yourTestCaseId" |

Copyright Notice

Licensed under the Apache 2.0
license (see the LICENSE.txt file).