@reportportal/agent-js-playwright

Agent to integrate Playwright with ReportPortal.

• More about Playwright
• More about ReportPortal

Example

Look through the example-playwright to check out the integration in action.

Installation

Install the agent in your project:

npm install --save-dev @reportportal/agent-js-playwright

Configuration

1. Create playwright.config.ts or *.config.js file with ReportPoral configuration:

import { PlaywrightTestConfig } from '@playwright/test';

const rpConfig = {
  apiKey: '<API_KEY>',
  endpoint: 'https://your.reportportal.server/api/v2',
  project: 'Your reportportal project name',
  launch: 'Your launch name',
  attributes: [
    {
      key: 'key',
      value: 'value',
    },
    {
      value: 'value',
    },
  ],
  description: 'Your launch description',
};

const config: PlaywrightTestConfig = {
  reporter: [['@reportportal/agent-js-playwright', rpConfig]],
  testDir: './tests',
};
export default config;

The full list of available options presented below.

Authentication Options

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.

OAuth Configuration

The oauth object supports the following properties:

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

OAuth 2.0 configuration example

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
  }
};

General options

The following options can be overridden using ENVIRONMENT variables:

2. Add script to package.json file:

{
  "scripts": {
    "test": "npx playwright test --config=playwright.config.ts"
  }
}

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

When organizing tests, specify titles for test.describe blocks, as this is necessary to build the correct structure of reports.

It is also required to specify playwright project names in playwright.config.ts when running the same tests in different playwright projects.

Attachments

Attachments can be easily added during test run via testInfo.attach according to the Playwright docs.

import { test, expect } from '@playwright/test';

test('basic test', async ({ page }, testInfo) => {
  await page.goto('https://playwright.dev');

  // Capture a screenshot and attach it
  const screenshot = await page.screenshot();
  await testInfo.attach('screenshot', { body: screenshot, contentType: 'image/png' });
});

Note: attachment path can be provided instead of body.

As an alternative to this approach the ReportingAPI methods can be used.

Note: ReportingAPI methods will send attachments to ReportPortal right after their call, unlike attachments provided via testInfo.attach that will be reported only on the test item finish.

Logging

You can use the following console native methods to report logs to tests:

console.log();
console.info();
console.debug();
console.warn();
console.error();

console's log, info,dubug reports as info log.

console's error, warn reports as error log if message contains "error" mention, otherwise as warn log.

As an alternative to this approach the ReportingAPI methods can be used.

Nested steps

ReportPortal supports reportings of native Playwright steps as nested steps.

import { test, expect } from '@playwright/test';

test('test', async ({ page }) => {
  await test.step('Log in', async () => {
    // ...
  });

  await test.step('Outer step', async () => {
    // ...
    // You can nest steps inside each other.
    await test.step('Inner step', async () => {
      // ...
    });
  });
});

To turn on this feature, just set the includeTestSteps config options to true.

Reporting API

This reporter provides Reporting API to use it directly in tests to send some additional data to the report.

To start using the ReportingApi in tests, just import it from '@reportportal/agent-js-playwright':

import { ReportingApi } from '@reportportal/agent-js-playwright';

Reporting API methods

The API provide methods for attaching data (logs, attributes, testCaseId, status).
All ReportingApi methods have an optional suite parameter.
If you want to add a data to the suite, you must pass the suite name as the last parameter.

addAttributes

Add attributes (tags) to the current test. Should be called inside of corresponding test.
ReportingApi.addAttributes(attributes: Array<Attribute>, suite?: string);
required: attributes
optional: suite
Example:

test('should have the correct attributes', () => {
  ReportingApi.addAttributes([
    {
      key: 'testKey',
      value: 'testValue',
    },
    {
      value: 'testValueTwo',
    },
  ]);
  expect(true).toBe(true);
});

setTestCaseId

Set test case id to the current test (About test case id). Should be called inside of corresponding test.
ReportingApi.setTestCaseId(id: string, suite?: string);
required: id
optional: suite
If testCaseId not specified, it will be generated automatically based on codeRef.
Example:

test('should have the correct testCaseId', () => {
  ReportingApi.setTestCaseId('itemTestCaseId');
  expect(true).toBe(true);
});

log

Send logs to report portal for the current test. Should be called inside of corresponding test.
ReportingApi.log(level: LOG_LEVELS, message: string, file?: Attachment, suite?: string);
required: level, message
optional: file, suite
where level can be one of the following: TRACE, DEBUG, WARN, INFO, ERROR, FATAL
Example:

test('should contain logs with attachments', () => {
  const fileName = 'test.jpg';
  const fileContent = fs.readFileSync(path.resolve(__dirname, './attachments', fileName));
  const attachment = {
    name: fileName,
    type: 'image/jpg',
    content: fileContent.toString('base64'),
  };
  ReportingApi.log('INFO', 'info log with attachment', attachment);

  expect(true).toBe(true);
});

info, debug, warn, error, trace, fatal

Send logs with corresponding level to report portal for the current test. Should be called inside of corresponding test.
ReportingApi.info(message: string, file?: Attachment, suite?: string);
ReportingApi.debug(message: string, file?: Attachment, suite?: string);
ReportingApi.warn(message: string, file?: Attachment, suite?: string);
ReportingApi.error(message: string, file?: Attachment, suite?: string);
ReportingApi.trace(message: string, file?: Attachment, suite?: string);
ReportingApi.fatal(message: string, file?: Attachment, suite?: string);
required: message
optional: file, suite
Example:

test('should contain logs with attachments', () => {
  ReportingApi.info('Log message');
  ReportingApi.debug('Log message');
  ReportingApi.warn('Log message');
  ReportingApi.error('Log message');
  ReportingApi.trace('Log message');
  ReportingApi.fatal('Log message');

  expect(true).toBe(true);
});

launchLog

Send logs to report portal for the current launch. Should be called inside of the any test or suite.
ReportingApi.launchLog(level: LOG_LEVELS, message: string, file?: Attachment);
required: level, message
optional: file
where level can be one of the following: TRACE, DEBUG, WARN, INFO, ERROR, FATAL
Example:

test('should contain logs with attachments', async () => {
  const fileName = 'test.jpg';
  const fileContent = fs.readFileSync(path.resolve(__dirname, './attachments', fileName));
  const attachment = {
    name: fileName,
    type: 'image/jpg',
    content: fileContent.toString('base64'),
  };
  ReportingApi.launchLog('INFO', 'info log with attachment', attachment);

  await expect(true).toBe(true);
});

launchInfo, launchDebug, launchWarn, launchError, launchTrace, launchFatal

Send logs with corresponding level to report portal for the current launch. Should be called inside of the any test or suite.
ReportingApi.launchInfo(message: string, file?: Attachment);
ReportingApi.launchDebug(message: string, file?: Attachment);
ReportingApi.launchWarn(message: string, file?: Attachment);
ReportingApi.launchError(message: string, file?: Attachment);
ReportingApi.launchTrace(message: string, file?: Attachment);
ReportingApi.launchFatal(message: string, file?: Attachment);
required: message
optional: file
Example:

test('should contain logs with attachments', () => {
  ReportingApi.launchInfo('Log message');
  ReportingApi.launchDebug('Log message');
  ReportingApi.launchWarn('Log message');
  ReportingApi.launchError('Log message');
  ReportingApi.launchTrace('Log message');
  ReportingApi.launchFatal('Log message');

  expect(true).toBe(true);
});

setStatus

Assign corresponding status to the current test item. Should be called inside of corresponding test.
ReportingApi.setStatus(status: string, suite?: string);
required: status
optional: suite
where status must be one of the following: passed, failed, stopped, skipped, interrupted, cancelled
Example:

test('should have status FAILED', () => {
  ReportingApi.setStatus('failed');

  expect(true).toBe(true);
});

setStatusFailed, setStatusPassed, setStatusSkipped, setStatusStopped, setStatusInterrupted, setStatusCancelled

Assign corresponding status to the current test item. Should be called inside of corresponding test.
ReportingApi.setStatusFailed(suite?: string);
ReportingApi.setStatusPassed(suite?: string);
ReportingApi.setStatusSkipped(suite?: string);
ReportingApi.setStatusStopped(suite?: string);
ReportingApi.setStatusInterrupted(suite?: string);
ReportingApi.setStatusCancelled(suite?: string);
optional: suite
Example:

test('should call ReportingApi to set statuses', () => {
  ReportingAPI.setStatusFailed();
  ReportingAPI.setStatusPassed();
  ReportingAPI.setStatusSkipped();
  ReportingAPI.setStatusStopped();
  ReportingAPI.setStatusInterrupted();
  ReportingAPI.setStatusCancelled();
});

setLaunchStatus

Assign corresponding status to the current launch. Should be called inside of the any test or suite.
ReportingApi.setLaunchStatus(status: string);
required: status
where status must be one of the following: passed, failed, stopped, skipped, interrupted, cancelled
Example:

test('launch should have status FAILED', () => {
  ReportingApi.setLaunchStatus('failed');
  expect(true).toBe(true);
});

setLaunchStatusFailed, setLaunchStatusPassed, setLaunchStatusSkipped, setLaunchStatusStopped, setLaunchStatusInterrupted, setLaunchStatusCancelled

Assign corresponding status to the current test item. Should be called inside of the any test or suite.
ReportingApi.setLaunchStatusFailed();
ReportingApi.setLaunchStatusPassed();
ReportingApi.setLaunchStatusSkipped();
ReportingApi.setLaunchStatusStopped();
ReportingApi.setLaunchStatusInterrupted();
ReportingApi.setLaunchStatusCancelled();
Example:

test('should call ReportingApi to set launch statuses', () => {
  ReportingAPI.setLaunchStatusFailed();
  ReportingAPI.setLaunchStatusPassed();
  ReportingAPI.setLaunchStatusSkipped();
  ReportingAPI.setLaunchStatusStopped();
  ReportingAPI.setLaunchStatusInterrupted();
  ReportingAPI.setLaunchStatusCancelled();
});

Integration with Sauce Labs

To integrate with Sauce Labs just add attributes for the test case:

[
  {
    key: 'SLID',
    value: '# of the job in Sauce Labs',
  },
  {
    key: 'SLDC',
    value: 'EU (your job region in Sauce Labs)',
  },
];

Example available in examples repo.

Usage with sharded tests

Playwright supports test sharding on multiple machines. It has its own CLI for merging reports from multiple shards. But the mentioned CLI tool merge-reports is designed to merge local reports represented by files in the file system, so it is not suitable for external reporting systems like ReportPortal, as it requires at least network communication through the right endpoints.

Thus, in order to have a single launch in ReportPortal for sharded tests, additional customization is required. There are several options to achieve this:

• Using the launchId config option
• Merging launches based on the build ID

Note: The @reportportal/client-javascript SDK used here as a reference, but of course the same actions can be performed by sending requests to the ReportPortal API directly.

Using the launchId config option

The complete example of launchId usage with shards can be found for our playwright example with GitHub Actions pipeline, so you can use it as a reference while following this guide.

The agent supports the launchId parameter to specify the ID of the already started launch. This way, you can start the launch using @reportportal/client-javascript before the test run and then specify its ID in the config or via environment variable.

1. Trigger a launch before all tests.

The @reportportal/client-javascript startLaunch method can be used.

/*
 * startLaunch.js
 * */
const rpClient = require('@reportportal/client-javascript');

const rpConfig = {
  // ...
};

async function startLaunch() {
  const client = new rpClient(rpConfig);
  // see https://github.com/reportportal/client-javascript?tab=readme-ov-file#startlaunch for the details
  const response = await client.startLaunch({
    name: rpConfig.launch,
    attributes: rpConfig.attributes,
    // etc.
  }).promise;

  return response.id;
}

const launchId = await startLaunch();

Received launchId can be exported e.g. as an environment variable to your CI job.

1. Specify the launch ID for each job. This step depends on your CI provider and the available ways to path some values to the Node.js process. The launch ID can be set directly to the reporter config.

/*
 * playwright.config.js
 * */
const rpConfig = {
  // ...
  launchId: 'receivedLaunchId',
};

or just set as RP_LAUNCH_ID environment variable.

With launch ID provided, the agent will attach all test results to that launch. So it won't be finished by the agent and should be finished separately.

1. As a run post-step (when all tests finished), launch also needs to be finished separately.

The @reportportal/client-javascript finishLaunch method can be used.

/*
 * finishLaunch.js
 * */
const RPClient = require('@reportportal/client-javascript');

const rpConfig = {
  // ...
};

const finishLaunch = async () => {
  const client = new RPClient(rpConfig);
  const launchTempId = client.startLaunch({ id: process.env.RP_LAUNCH_ID }).tempId;
  // see https://github.com/reportportal/client-javascript?tab=readme-ov-file#finishlaunch for the details
  await client.finishLaunch(launchTempId, {}).promise;
};

await finishLaunch();

Merging launches based on the build ID

This approach offers a way to merge several launches reported from different shards into one launch after the entire test execution completed and launches are finished.

• With this option the Auto-analysis, Pattern-analysis and Quality Gates will be triggered for each sharded launch individually.
• The launch numbering will be changed as each sharded launch will have its own number.
• The merged launch will be treated as a new launch with its own number.

This approach is equal to merging launches via ReportPortal UI.

1. Specify a unique CI build ID as a launch attribute, which will be the same for different jobs in the same run (this could be a commit hash or something else). This step depends on your CI provider and the available ways to path some values to the Node.js process.

/*
 * playwright.config.js
 * */
const rpConfig = {
  // ...
  attributes: [
    {
      key: 'CI_BUILD_ID',
      // e.g.
      value: process.env.GITHUB_COMMIT_SHA,
    },
  ],
};

1. Collect the launch IDs and call the merge operation.

The ReportPortal API can be used to filter the required launches by the provided attribute to collect their IDs.

/*
 * mergeRpLaunches.js
 * */
const rpClient = require('@reportportal/client-javascript');

const rpConfig = {
  // ...
};

const client = new rpClient(rpConfig);

async function mergeLaunches() {
  const ciBuildId = process.env.CI_BUILD_ID;
  if (!ciBuildId) {
    console.error('To merge multiple launches, CI_BUILD_ID must not be empty');
    return;
  }
  try {
    // 1. Send request to get all launches with the same CI_BUILD_ID attribute value
    const params = new URLSearchParams({
      'filter.has.attributeValue': ciBuildId,
    });
    const launchSearchUrl = `launch?${params.toString()}`;
    const response = await client.restClient.retrieveSyncAPI(launchSearchUrl);
    // 2. Filter them to find launches that are in progress
    const launchesInProgress = response.content.filter((launch) => launch.status === 'IN_PROGRESS');
    // 3. If exists, just return. The steps can be repeated in some interval if needed
    if (launchesInProgress.length) {
      return;
    }
    // 4. If not, merge all found launches with the same CI_BUILD_ID attribute value
    const launchIds = response.content.map((launch) => launch.id);
    const request = client.getMergeLaunchesRequest(launchIds);
    request.description = rpConfig.description;
    request.extendSuitesDescription = false;
    const mergeURL = 'launch/merge';
    await client.restClient.create(mergeURL, request);
  } catch (err) {
    console.error('Fail to merge launches', err);
  }
}

mergeLaunches();

Using a merge operation for huge launches can increase the load on ReportPortal's API. See the details and other parameters available for merge operation in ReportPortal API docs.

Note: Since the options described require additional effort, the ReportPortal team intends to create a CLI for them to make them easier to use, but with no ETA. Progress can be tracked in this issue.

Issues troubleshooting

Launches stuck in progress on RP side

There is known issue that in some cases launches not finished as expected in ReportPortal while using static annotations (.skip(), .fixme()) that expect the test to be 'SKIPPED'.
This may happen in case of error thrown from before/beforeAll hooks, retries enabled and fullyParallel: false. Associated with #85.
In this case as a workaround we suggest to use .skip() and .fixme() annotations inside the test body:

use

test('example fail', async ({}) => {
  test.fixme();
  expect(1).toBeGreaterThan(2);
});

instead of

test.fixme('example fail', async ({}) => {
  expect(1).toBeGreaterThan(2);
});

[5.3.2] - 2025-10-29

Changed

• @reportportal/client-javascript bumped to version 5.5.2.

[5.3.1] - 2025-10-29

Fixed

• Client errors when the restClientConfig not specified.

  Changed

• @reportportal/client-javascript bumped to version 5.5.1.

[5.3.0] - 2025-10-28

Added

• Full http/https proxy support with noProxy configuration, check Proxy configuration options for more details.

  Changed

• @reportportal/client-javascript bumped to version 5.5.0.

[5.2.4] - 2025-10-20

Added

• OAuth 2.0 Password Grant authentication, check Authentication options for more details.

  Fixed

• Intermittent issue with empty launches.

  Changed

• @reportportal/client-javascript bumped to version 5.4.3.

[5.2.3] - 2025-10-02

Added

• Allow configuring the HTTP retry strategy via restClientConfig.retry and tune the default policy.

  Changed

• @reportportal/client-javascript bumped to version 5.4.2.

  Security

• Updated versions of vulnerable packages (axios).

[5.2.2] - 2025-09-08

Fixed

• #187 Logs being displayed in incorrect order and with identical timestamps.

[5.2.1] - 2025-08-27

Fixed

• #184 Test run failures in case of string static annotations and skipping reasons used.

[5.2.0] - 2025-08-22

Added

• Semantic names for test artefacts based on the test names. Resolves #173.

  Changed

• Use Playwright's testInfo.annotations for ReportPortal runtime data for tests. Addresses #113.
• Revert time format back to milliseconds (based on #217). This is also fixing the issue with agents installation on ARM processors #212.
• @reportportal/client-javascript bumped to version 5.4.1.

  Security

• Updated versions of vulnerable packages (axios).

[5.1.11] - 2024-09-23

Changed

• The agent now supports reporting the time for launches, test items and logs with microsecond precision in the ISO string format. For logs, microsecond precision is available on the UI from ReportPortal version 24.2.
• @reportportal/client-javascript bumped to version 5.3.0.

[5.1.10] - 2024-09-17

Changed

• @reportportal/client-javascript bumped to version 5.2.0.

[5.1.9] - 2024-06-26

Changed

• @reportportal/client-javascript bumped to version 5.1.4.

  Security

• Updated versions of vulnerable packages (braces).

[5.1.8] - 2024-04-11

Changed

• @reportportal/client-javascript bumped to version 5.1.3, new launchUuidPrintOutput types introduced: 'FILE', 'ENVIRONMENT'.

[5.1.7] - 2024-02-21

Changed

• @reportportal/client-javascript bumped to version 5.1.2.

  Fixed

• Setting step id in case of existing one, thanks to noacohen1.

[5.1.6] - 2023-12-19

Fixed

• Serial mode execution. Fix invocations calculation for indirect test parents.

[5.1.5] - 2023-12-19

Added

• extendTestDescriptionWithLastError option to the RP config to be able to toggle the last error log attaching to the test description.

  Fixed

• Test results inconsistency while using serial mode.

  Changed

• @reportportal/client-javascript bumped to version 5.0.15. Logging link to the launch on its finish now available by default.

[5.1.4] - 2023-10-05

Changed

• @reportportal/client-javascript bumped to version 5.0.14.

[5.1.3] - 2023-09-07

Fixed

• #111 Test is not finished when expect().toPass() exceed test timeout.

  Changed

• @reportportal/client-javascript bumped to version 5.0.13. launchUuidPrint and launchUuidPrintOutput configuration options introduced.

[5.1.2] - 2023-06-23

Changed

• token configuration option was renamed to apiKey to maintain common convention.
• @reportportal/client-javascript bumped to version 5.0.12.

[5.1.1] - 2023-06-13

Fixed

• Nested steps and launch finishing when includeTestSteps: true. Addressed #76, #97.

[5.1.0] - 2023-06-05

Added

• launchId option to the config to attach run results to an existing launch. Related to parallel execution on one and several machines #86.
• uploadVideo and uploadTrace options to the config to disable auto-attaching the Playwright's video and trace. Addressed #98.

  Changed

• @reportportal/client-javascript bumped to version 5.0.11.

[5.0.11] - 2023-04-13

Fixed

• Errors in case of Playwright doesn't provide the internal _staticAnnotations property to the TestCases.

  Added

• printsToStdio method implemented. Now the Playwright will provide additional output to the terminal to enhance user experience in case of only @reportportal/agent-js-playwright reporter used.

[5.0.10] - 2023-04-12

Fixed

• Issue with suites finishing after run interruption via Playwright globalTimeout.

[5.0.9] - 2023-03-21

Fixed

• Issue #79 with duplicating tests with wrong statuses using testInfo.fail().
• Issue #85 with suites finishing when retrying statically annotated (.fixme() or .skip()) tests. The issue still reproducible in some rare cases, refer Issues troubleshooting for details.

  Changed

• testCase.outcome() used instead of testResult.status to calculate the final status for the test case in RP. Thanks to clouddra.
• testCase.id used instead of full test path to identify the test case.
• engines field in package.json. The agent supports the minimal version of Node.js required by @playwright/test (>=14).
• TypeScript compilation target changed to ES6.
• Docs Attachments section actualized.
• @reportportal/client-javascript bumped to version 5.0.8.

[5.0.8] - 2022-09-28

Fixed

• Issue #46 with suites finishing when retrying skipped tests.
• Issue #69 with wrong logs attaching.

[5.0.7] - 2022-09-15

Fixed

• Suites finishing algorithm bugfixes

[5.0.6] - 2022-09-13

Fixed

• #56 and #57 Error (cannot read property of undefined 'rootSuite').
• Launch finishing for skipped tests with retries.

  Added

• Ability to switch on/off adding Playwright project names to code reference via config property includePlaywrightProjectNameToCodeReference.

[5.0.5] - 2022-07-12

Fixed

• Error with test steps finishing
• Test steps nesting structure
• Launch mode property support

[5.0.4] - 2022-05-30

Fixed

• #42 Error when using same filenames
• Error is related to retries due to which the launch is not finish
• #45 Agent failed when enabled includeTestSteps

[5.0.3] - 2022-04-04

Added

• Ability include test steps to the report on log level via config property includeTestSteps.

  Fixed

• The correct end time for suites is now displayed.

[5.0.2] - 2022-02-04

Added

• Ability to attach logs to items via console.* methods

  Fixed

• #26 Error when value is not allowed for field 'status'

[5.0.1] - 2022-01-17

Added

• Ability to attach screenshots and other files via test info attachments
• TypeScript definitions provided

  Fixed

• Error when reporting tests without describe blocks
• Escape codes removed from error messages and stacktrace

  Changed

• Package size reduced

[5.0.0] - 2021-12-16

Added

• Full compatibility with ReportPortal version 5.* (see reportportal releases)