ReportPortal js client

This Client is to communicate with the ReportPortal on Node.js.

Library is used only for implementors of custom listeners for ReportPortal.

Already implemented listeners:

* Playwright integration
* Cypress integration
* Jest integration
* Mocha integration
* Webdriverio integration
* Postman integration
* Cucumber integration
* Vitest integration
* Jasmine integration
* TestCafe integration
* Codecept integration
* Nightwatch integration

Examples for test framework integrations from the list above described in examples repository.

Installation

The latest version is available on npm:
``cmd
npm install @reportportal/client-javascript
`

Usage example

`javascript
const RPClient = require('@reportportal/client-javascript');

const rpClient = new RPClient({
apiKey: 'reportportalApiKey',
endpoint: 'http://your-instance.com:8080/api/v1',
launch: 'LAUNCH_NAME',
project: 'PROJECT_NAME'
});

rpClient.checkConnect().then(() => {
console.log('You have successfully connected to the server.');
}, (error) => {
console.log('Error connection to server');
console.dir(error);
});
`

Configuration

When creating a client instance, you need to specify the following options.

$3

The client 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 RPClient = require('@reportportal/client-javascript');

const rpClient = new RPClient({
endpoint: 'http://your-instance.com:8080/api/v1',
launch: 'LAUNCH_NAME',
project: 'PROJECT_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
}
});

rpClient.checkConnect().then(() => {
console.log('You have successfully connected to the server.');
}, (error) => {
console.log('Error connection to server');
console.dir(error);
});
`

$3

| Option | Necessity | Default | Description |
|-----------------------|------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| endpoint | Required | | URL of your server. For example, if you visit the page at 'https://server:8080/ui', then endpoint will be equal to 'https://server:8080/api/v1'. |
| launch | Required | | Name of the launch at creation. |
| project | Required | | The name of the project in which the launches will be created. |
| headers | Optional | {} | The object with custom headers for internal http client. |
| debug | Optional | false | This flag allows seeing the logs of the client. Useful for debugging. |
| isLaunchMergeRequired | Optional | false | Allows client to merge launches into one at the end of the run via saving their UUIDs to the temp files at filesystem. At the end of the run launches can be merged using mergeLaunches method. Temp file format: rplaunch-${launch_uuid}.tmp. |
| restClientConfig | Optional | Not set | Check the details in the HTTP client config. |
| 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. |
| token | Deprecated | Not set | Use apiKey or oauth instead. |

$3

axios like http client config.

#### Timeout (30000ms) on axios requests

There is a timeout on axios requests. If for instance the server your making a request to is taking too long to load, then axios timeout will work and you will see the error 'Error: timeout of 30000ms exceeded'.

You can simply change this timeout by adding a timeout property to restClientConfig with your desired numeric value (in _ms_) or 0 to disable it.

#### Debug

Use debug: true for debugging.

#### Agent

Use agent property to provide http(s) agent options.
Use this property in case the direct httpAgent/httpsAgent instance property cannot be used due to config serializations.

#### Retry configuration

The client retries failed HTTP calls up to 6 times with an exponential backoff (starting at 200 ms and capping at 5 s) and resets the axios timeout before each retry. Provide a retry option in restClientConfig to change that behaviour. The value can be either a number (overriding just the retry count) or a full axios-retry configuration object:

`javascript
const axiosRetry = require('axios-retry').default;

const client = new RPClient({
// ... other options
restClientConfig: {
retry: {
retries: 5,
retryDelay: axiosRetry.exponentialDelay,
},
},
});
`

Setting retry: 0 disables automatic retries.

#### Proxy configuration

The client supports comprehensive proxy configuration for both HTTP and HTTPS requests, including ReportPortal API calls and OAuth token requests. Proxy settings can be configured via restClientConfig or environment variables.

##### Basic proxy configuration

###### Via configuration object

`javascript
const RPClient = require('@reportportal/client-javascript');

const rpClient = new RPClient({
apiKey: 'your_api_key',
endpoint: 'http://your-instance.com:8080/api/v1',
launch: 'LAUNCH_NAME',
project: 'PROJECT_NAME',
restClientConfig: {
proxy: {
protocol: 'https', // 'http' or 'https'
host: '127.0.0.1',
port: 8080,
// Optional authentication
auth: {
username: 'proxy-user',
password: 'proxy-password'
}
}
}
});
`

###### Via proxy URL string

`javascript
const rpClient = new RPClient({
// ... other options
restClientConfig: {
proxy: 'https://127.0.0.1:8080'
}
});
`

###### Via environment variables

The client automatically detects and uses proxy environment variables:

`bash
export HTTPS_PROXY=https://127.0.0.1:8080
export HTTP_PROXY=http://127.0.0.1:8080
export NO_PROXY=localhost,127.0.0.1,.local
`

##### Bypassing proxy for specific domains (noProxy)

Use the noProxy option to exclude specific domains from being proxied. This is useful when some services are accessible directly while others require a proxy.

`javascript
const rpClient = new RPClient({
// ... other options
restClientConfig: {
proxy: {
protocol: 'https',
host: '127.0.0.1',
port: 8080
},
// Bypass proxy for these domains
noProxy: 'localhost,127.0.0.1,internal.company.com,.local.domain'
}
});
`

noProxy format:
- Exact hostname: example.com - matches example.com and sub.example.com
- Leading dot: .example.com - matches only subdomains like sub.example.com (not example.com itself)
- Wildcard: * - bypass proxy for all requests
- Multiple entries: Comma-separated list

Priority: Configuration noProxy takes precedence over NO_PROXY environment variable.

##### Proxy with OAuth authentication

When using OAuth authentication, the proxy configuration is automatically applied to both:
- OAuth token endpoint requests
- ReportPortal API requests

`javascript
const rpClient = new RPClient({
endpoint: 'http://your-instance.com:8080/api/v1',
project: 'PROJECT_NAME',
oauth: {
tokenEndpoint: 'https://login.microsoftonline.com/.../oauth2/v2.0/token',
username: 'your-username',
password: 'your-password',
clientId: 'your-client-id'
},
restClientConfig: {
proxy: {
protocol: 'https',
host: '127.0.0.1',
port: 8080
},
// Example: Use proxy for OAuth, bypass for ReportPortal
noProxy: 'your-instance.com'
}
});
`

##### Advanced proxy scenarios

###### Disable proxy explicitly

`javascript
restClientConfig: {
proxy: false // Disable proxy even if environment variables are set
}
`

###### Debug proxy configuration

Enable debug mode to see detailed proxy decision logs:

`javascript
restClientConfig: {
proxy: { / ... / },
noProxy: 'localhost,.local',
debug: true // See proxy-related logs
}
`

Debug output example:
`
[ProxyHelper] getProxyConfig called:
URL: https://login.microsoftonline.com/oauth2/v2.0/token
Hostname: login.microsoftonline.com
noProxy from config: localhost,.local
Should bypass proxy: false
[ProxyHelper] Creating proxy agent:
URL: https://login.microsoftonline.com/oauth2/v2.0/token
Protocol: https:
Proxy URL: https://127.0.0.1:8080
`

##### Proxy configuration options

| Option | Type | Description |
|---------------------|------------------------------|-------------------------------------------------------------------------------------------------|
| proxy | false \| string \| object | Proxy configuration. Can be false (disable), URL string, or configuration object (see below) |
| proxy.protocol | string | Proxy protocol: 'http' or 'https' |
| proxy.host | string | Proxy host address |
| proxy.port | number | Proxy port number |
| proxy.auth | object | Optional proxy authentication |
| proxy.auth.username | string | Proxy username |
| proxy.auth.password | string | Proxy password |
| noProxy | string | Comma-separated list of domains to bypass proxy |

##### How proxy handling works

1. Per-request proxy decision: Each request (API or OAuth) determines its proxy configuration based on the target URL
2. noProxy checking: URLs matching noProxy patterns bypass the proxy and connect directly
3. Default agents for bypassed URLs: When a URL bypasses proxy, a default HTTP/HTTPS agent is used to prevent automatic proxy detection
4. Environment variable support: HTTP_PROXY, HTTPS_PROXY, and NO_PROXY are automatically detected and used if no explicit configuration is provided
5. Priority: Explicit configuration takes precedence over environment variables

Asynchronous reporting

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.

API

Each method (except checkConnect) returns an object in a specific format:
`javascript
{
tempId: '4ds43fs', // generated by the client id for further work with the created item
promise: Promise // An object indicating the completion of an operation
}
`
The client works synchronously, so it is not necessary to wait for the end of the previous requests to send following ones.

$3

checkConnect - asynchronous method for verifying the correctness of the client connection

`javascript
rpClient.checkConnect().then((response) => {
console.log('You have successfully connected to the server.');
console.log(You are using an account: ${response.fullName});
}, (error) => {
console.log('Error connection to server');
console.dir(error);
});
`

$3

startLaunch - starts a new launch, return temp id that you want to use for the all items within this launch.

`javascript
const launchObj = rpClient.startLaunch({
name: 'Client test',
startTime: rpClient.helpers.now(),
description: 'description of the launch',
attributes: [
{
'key': 'yourKey',
'value': 'yourValue'
},
{
'value': 'yourValue'
}
],
//this param used only when you need client to send data into the existing launch
id: 'id'
});
console.log(launchObj.tempId);
`
The method takes one argument:
* launch data object:

| Option | Necessity | Default | Description |
|-------------|-----------|----------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| startTime | Optional | rpClient.helpers.now() | Start time of the launch (unix time). |
| name | Optional | parameter 'launch' specified when creating the client instance | Name of the launch. |
| mode | Optional | 'DEFAULT' | 'DEFAULT' - results will be submitted to Launches page, 'DEBUG' - results will be submitted to Debug page. |
| description | Optional | '' | Description of the launch (supports markdown syntax). |
| attributes | Optional | [] | Array of launch attributes (tags). |
| id | Optional | Not set | ID of the existing launch in which tests data would be sent, without this param new launch instance will be created. |

To get the real launch ID (also known as launch UUID from database) wait for the returned promise to finish.

`javascript
const launchObj = rpClient.startLaunch();
launchObj.promise.then((response) => {
console.log(Launch real id: ${response.id});
}, (error) => {
console.dir(Error at the start of launch: ${error});
})
`
As system attributes, this method sends the following data (these data are not for public use):
* client name, version;
* agent name, version (if given);
* browser name, version (if given);
* OS type, architecture;
* RAMSize;
* nodeJS version;

ReportPortal is supporting now integrations with more than 15 test frameworks simultaneously.
In order to define the most popular agents and plan the team workload accordingly, we are using Google Analytics.

ReportPortal collects only information about agent name, version and version of Node.js. This information is sent to Google Analytics on the launch start.
Please help us to make our work effective.
If you still want to switch Off Google Analytics, please change env variable.
'REPORTPORTAL_CLIENT_JS_NO_ANALYTICS=true'

$3

finishLaunch - finish of the launch. After calling this method, you can not add items to the launch.
The request to finish the launch will be sent only after all items within it have finished.

`javascript
// launchObj - object returned by method 'startLaunch'
const launchFinishObj = rpClient.finishLaunch(launchObj.tempId, {
endTime: rpClient.helpers.now()
});
`

The method takes two arguments:
* launch tempId (returned by the method startLaunch)
* data object:

|Option | Necessity | Default | Description |
|--------- |-----------|---------|---------------------------------------------------------------------------------------------------|
|endTime | Optional | rpClient.helpers.now() | End time of the launch. |
|status | Optional | '' | Status of launch, one of '', 'PASSED', 'FAILED', 'STOPPED', 'SKIPPED', 'INTERRUPTED', 'CANCELLED'. |

$3

getPromiseFinishAllItems - returns promise that contains status about all data has been sent to the reportportal.
This method needed when test frameworks don't wait for async methods until finished.

`javascript
// jasmine example. tempLaunchId - tempId of the launch started by the current client process
agent.getPromiseFinishAllItems(agent.tempLaunchId).then(() => done());
`

| Option | Necessity | Default | Description |
|--------------|-----------|---------|----------------------------|
| tempLaunchId | Required | | tempId of the launch started by the current client process |

$3

updateLaunch - updates the launch data. Will send a request to the server only after finishing the launch.

`javascript
// launchObj - object returned by method 'startLaunch'
rpClient.updateLaunch(
launchObj.tempId,
{
description: 'new launch description',
attributes: [
{
key: 'yourKey',
value: 'yourValue'
},
{
value: 'yourValue'
}
],
mode: 'DEBUG'
}
);
`
The method takes two arguments:
* launch tempId (returned by the method 'startLaunch')
* data object - may contain the following fields: description, attributes, mode. These fields can be looked up in the method startLaunch.

$3

startTestItem - starts a new test item.

`javascript
// launchObj - object returned by method 'startLaunch'
const suiteObj = rpClient.startTestItem({
description: makeid(),
name: makeid(),
startTime: rpClient.helpers.now(),
type: 'SUITE'
}, launchObj.tempId);
const stepObj = rpClient.startTestItem({
description: makeid(),
name: makeid(),
startTime: rpClient.helpers.now(),
attributes: [

{
key: 'yourKey',
value: 'yourValue'
},
{
value: 'yourValue'
}
],
type: 'STEP'
}, launchObj.tempId, suiteObj.tempId);

`
The method takes three arguments:
* test item data object:

|Option | Necessity | Default | Description |
|--------- |-----------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|name | Required | | Test item name |
|type | Required | | Test item type, one of 'SUITE', 'STORY', 'TEST', 'SCENARIO', 'STEP', 'BEFORE_CLASS', 'BEFORE_GROUPS','BEFORE_METHOD', 'BEFORE_SUITE', 'BEFORE_TEST', 'AFTER_CLASS', 'AFTER_GROUPS', 'AFTER_METHOD', 'AFTER_SUITE', 'AFTER_TEST' |
|hasStats | Optional | true | Changes behavior for test item of type 'STEP'. When set to true, step is treaten as a test case (entity containig statistics). When false, step becomes a nested step. |
|description | Optional | '' | Description of the test item (supports markdown syntax). |
|startTime | Optional | rpClient.helpers.now() | Start time of the test item (unix time). |
|attributes | Optional | [] | Array of the test item attributes. |

* launch tempId (returned by the method startLaunch)
parent test item tempId (optional*) (returned by method startTestItem)

$3

finishTestItem - finish of the test item. After calling this method, you can not add items to the test item.
The request to finish the test item will be sent only after all test items within it have finished.

`javascript
// itemObj - object returned by method 'startTestItem'
rpClient.finishTestItem(itemObj.tempId, {
status: 'failed'
})
`
The method takes two arguments:
* test item tempId (returned by the method startTestItem)
* data object:

| Option | Necessity | Default | Description |
|---------|-----------|------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
| issue | Optional | true | Test item issue object. issueType is required, allowable values: 'pb', 'ab', 'si', 'ti', 'nd001'. Where * is locator id |
| status | Optional | 'PASSED' | Test item status, one of '', 'PASSED', 'FAILED', 'STOPPED', 'SKIPPED', 'INTERRUPTED', 'CANCELLED'. |
| endTime | Optional | rpClient.helpers.now() | End time of the launch (unix time). |

Example issue object:
`
{
issueType: 'string',
comment: 'string',
externalSystemIssues: [
{
submitDate: 0,
submitter: 'string',
systemId: 'string',
ticketId: 'string',
url: 'string'
}
]
}
`

$3

sendLog - adds a log to the test item.

`javascript
// stepObj - object returned by method 'startTestItem'
rpClient.sendLog(stepObj.tempId, {
level: 'INFO',
message: 'User clicks login button',
time: rpClient.helpers.now()
})
`
The method takes three arguments:
* test item tempId (returned by method startTestItem)
* data object:

| Option | Necessity | Default | Description |
|---------|-----------|------------------------|----------------------------------------------------------------------|
| message | Optional | '' | The log message. |
| level | Optional | '' | The log level, one of 'trace', 'debug', 'info', 'warn', 'error', ''. |
| time | Optional | rpClient.helpers.now() | The time of the log. |

* file object (optional):

| Option | Necessity | Default | Description |
|---------|-----------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| name | Required | | The name of the file. |
| type | Required | | The file mimeType, example 'image/png' (support types: 'image/*', application/['xml', 'javascript', 'json', 'css', 'php'], other formats will be opened in reportportal in a new browser tab only). |
| content | Required | | base64 encoded file content. |

$3

mergeLaunches - merges already completed runs into one (useful when running tests in multiple threads on the same machine).

Note: Works only if isLaunchMergeRequired option is set to true.

`javascript
rpClient.mergeLaunches({
description: 'Regression tests',
attributes: [
{
key: 'build',
value: '1.0.0'
}
],
endTime: rpClient.helpers.now(),
extendSuitesDescription: false,
launches: [1, 2, 3],
mergeType: 'BASIC',
mode: 'DEFAULT',
name: 'Launch name',
})
``
The method takes one argument:

* merge options object (optional):

| Option | Necessity | Default | Description |
|-------------------------|-----------|-----------------------------------------|------------------------------------------------------------------------------------------------------------|
| description | Optional | config.description or 'Merged launch' | Description of the launch (supports markdown syntax). |
| attributes | Optional | config.attributes or [] | Array of launch attributes (tags). |
| endTime | Optional | rpClient.helpers.now() | End time of the launch (unix time) |
| extendSuitesDescription | Optional | true | Whether to extend suites description or not. |
| launches | Optional | ids of the launches saved to filesystem | The array of the real launch ids, not UUIDs |
| mergeType | Optional | 'BASIC' | The type of the merge operation. Possible values are 'BASIC' or 'DEEP'. |
| mode | Optional | config.mode or 'DEFAULT' | 'DEFAULT' - results will be submitted to Launches page, 'DEBUG' - results will be submitted to Debug page. |
| name | Optional | config.launch or 'Test launch name' | Name of the launch after merge. |

Copyright Notice

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