@reportportal/agent-js-vitest

Agent to integrate Vitest with ReportPortal.

• More about Vitest
• More about ReportPortal

Supported Versions

This agent supports Vitest versions:

• 4.x - recommended. Supported by agent versions from 5.3.0.
• 1.x - 3.x - supported by agent versions 5.0.x - 5.2.x.

Installation

Install the agent in your project:

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

Configuration

1. Create vitest.config.ts file with ReportPortal configuration:

  import { defineConfig } from 'vitest/config';
  import RPReporter from '@reportportal/agent-js-vitest'; // or import { RPReporter } from '@reportportal/agent-js-vitest';

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

  export default defineConfig({
    test: {
      // add setup file to be able to use ReportingApi via `this.ReportingApi` in your tests
      setupFiles: ["@reportportal/agent-js-vitest/setup"],
      reporters: ['default', new RPReporter(rpConfig)],
    },
  });

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.

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

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

Option	Necessity	Default	Description
endpoint	Required		URL of your server. For example 'https://server:8080/api/v2'.
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.
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.
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. Use the retry property (number or axios-retry config) to customise automatic retries. 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).
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.
extendTestDescriptionWithLastError	Optional	true	If set to true the latest error log will be attached to the test case description.

The following options can be overridden using ENVIRONMENT variables:

Option	ENV variable
launchId	RP_LAUNCH_ID

2. Add script to package.json file:

{
  "scripts": {
    "test": "vitest run"
  }
}

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 describe blocks, as this is necessary to build the correct structure of reports.

Logging

You can use the following console native methods to report logs to the 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.

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, you can:

• Add setup file in vitest.config.ts

    import { defineConfig } from 'vitest/config';
  
    export default defineConfig({
      test: {
        ...
        setupFiles: ["@reportportal/agent-js-vitest/setup"],
      },
    });

  ReportingApi will be available in global variables and supports receiving Vitest task from the setup file.

      test('should contain logs with attachments',() => {
        ...
        ReportingApi.attachment({ name, type, content }, 'Description');
        ...
      });

• Import ReportingApi directly from '@reportportal/agent-js-vitest':

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

  In this case you are required to pass Vitest task as the first argument to the ReportingApi methods.

      test('should contain logs with attachments',({ task }) => {
        ...
        ReportingApi.attachment(task, { name, type, content }, 'Description');
        ...
      });

Reporting API methods

The API provides methods for attaching data.

attachment

Send file to ReportPortal for the current test. Should be called inside of corresponding test.
ReportingApi.attachment(task: vitest.RunnerTask, data: Attachment, description?: string);
required: task, data
optional: description
where Attachment type is {name: string; type: string; content: string | Buffer;}
Example:

test('should contain logs with attachments',({ task }) => {
  const fileName = 'test.jpg';
  const fileContent = fs.readFileSync(path.resolve(__dirname, './attachments', fileName));

  ReportingApi.attachment(task, {
    name: fileName,
    type: 'image/png',
    content: fileContent.toString('base64'),
  }, 'Description');

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

testCaseId

Add testCaseId to ReportPortal for the current test. Should be called inside of corresponding test.
ReportingApi.testCaseId(task: vitest.RunnerTask, data: string);
required: task, data
Example:

test('should contain testCaseId',({ task }) => {
  ReportingApi.testCaseId(task, 'C123456');

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

description

Add description to ReportPortal for the current test. In case the user call the method more than one time, the existing description will be extended. Should be called inside of corresponding test.
ReportingApi.description(task: vitest.RunnerTask, data: string);
required: task, data
Example:

test('should contain description',({ task }) => {
  ReportingApi.description(task, 'Test Description');

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

attributes

Send file to ReportPortal for the current test. Should be called inside of corresponding test.
ReportingApi.attributes(task: vitest.RunnerTask, data: Attribute[]);
required: task, data
where Attribute type is { value: string; key?: string; system?: boolean; }
Example:

test('should contain attributes',({ task }) => {
  ReportingApi.attributes(task,
    [
      { key: 'attrKey1', value: 'attrValue1'},
      { value: 'attrValue2'}
    ]);

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

log

Send log message to ReportPortal for the current test with configurable log level. Should be called inside of corresponding test.
ReportingApi.log(task: vitest.RunnerTask, message: string, level?: LOG_LEVELS);
required: task, message
optional: level (default: 'INFO')
where LOG_LEVELS supports predefined levels (TRACE, DEBUG, INFO, WARN, ERROR, FATAL) or custom string.
Example:

import { PREDEFINED_LOG_LEVELS } from '@reportportal/agent-js-vitest';

test('should contain custom logs',({ task }) => {
  ReportingApi.log(task, 'This is an info log');
  ReportingApi.log(task, 'This is a debug log', PREDEFINED_LOG_LEVELS.WARN);
  ReportingApi.log(task, 'This is a debug log', 'custom');
});