@reportportal/agent-js-mocha

@reportportal/agent-js-mocha

Agent to integrate Mocha with ReportPortal.

• More about Mocha
• More about ReportPortal

It was designed to work with mocha programmatically, in order to be able to parametrize each test run.

Installation

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

Configuration

Fill in the reporterOptions in Mocha configuration.

const Mocha = require("mocha");
const mochaMain = new Mocha({
  reporter: '@reportportal/agent-js-mocha',
  reporterOptions: {
    "apiKey": "reportportalApiKey",
    "endpoint": "https://your.reportportal.server/api/v1",
    "project": "YourReportPortalProjectName",
    "launch": "YourLauncherName",
    "attributes": [
      {
        "key": "YourKey",
        "value": "YourValue"
      },
      {
        "value": "YourValue"
      },
    ]
  }
});

Using .mocharc.js:

module.exports = {
  'extension': ['js', 'cjs', 'mjs'],
  'package': './package.json',
  reporter: '@reportportal/agent-js-mocha',
  'reporter-option':[
    'endpoint=https://your.reportportal.server/api/v1',
    'apiKey=reportportalApiKey',
    'launch=YourLauncherName',
    'project=YourReportPortalProjectName',
    'attributes=YourKey:YourValue;YourValue',
  ],
  'file': [
    'spec/someTest.spec.js',
  ]
}

Options

The full list of available options presented below.

Option	Necessity	Default	Description
apiKey	Required		User's reportportal token from which you want to send requests. It can be found on the profile page of this user.
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.
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 (values must be upper case).
debug	Optional	false	This flag allows seeing the logs of the client-javascript. Useful for debugging.
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).
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.
reportHooks	Optional	false	Determines report before and after hooks or not.
token	Deprecated	Not set	Use apiKey instead.

Examples

The agent-js-mocha usage example can be found here.

Reporting

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

Import the PublicReportingAPI as shown below to use additional reporting features.

const PublicReportingAPI = require('@reportportal/agent-js-mocha/lib/publicReportingAPI');

Logs and attachments

PublicReportingAPI provides the following methods for reporting logs into the current test/step.

• log(level, message , file). Reports message and optional file with specified log level as a log of the current test. If called outside of the test, reports message as a log of the current suite.
  level shoud be equal to one the following values: TRACE, DEBUG, INFO, WARN, ERROR, FATAL.
  file should be an object:
  

{
  name: "filename",
  type: "image/png",  // media type
  content: data,  // file content represented as 64base string
}

• trace (message , file). Reports message and optional file as a log of the current test/suite with trace log level.
• debug (message , file). Reports message and optional file as a log of the current test/suite with debug log level.
• info (message , file). Reports message and optional file as log of the current test/suite with info log level.
• warn (message , file). Reports message and optional file as a log of the current test/suite with warning log level.
• error (message , file). Reports message and optional file as a log of the current test/suite with error log level.
• fatal (message , file). Reports message and optional file as a log of the current test/suite with fatal log level.

PublicReportingAPI provides the corresponding methods for reporting logs into the launch.

• launchLog (level, message , file). Reports message and optional file with the specified log level as a log of the current launch.
• launchTrace (message , file). Reports message and optional file as a log of the launch with trace log level.
• launchDebug (message , file). Reports message and optional file as a log of the launch with debug log level.
• launchInfo (message , file). Reports message and optional file as log of the launch with info log level.
• launchWarn (message , file). Reports message and optional file as a log of the launch with warning log level.
• launchError (message , file). Reports message and optional file as a log of the launch with error log level.
• launchFatal (message , file). Reports message and optional file as a log of the launch with fatal log level.

Example:

const PublicReportingAPI = require('@reportportal/agent-js-mocha/lib/publicReportingAPI');
...
describe('suite',()=>{
  it('test', () => {
    const attachment = {
      name: 'attachment.png',
      type: 'image/png',
      content: data.toString('base64'),
    }
    PublicReportingAPI.log('INFO', 'Info log message for test "test" with attachment', attachment);
    PublicReportingAPI.launchLog('ERROR', 'Error log message for current launch with attachment', attachment);
    PublicReportingAPI.trace('Trace log message for test "test"', attachment);
    PublicReportingAPI.debug('Debug log message for test "test"');
    PublicReportingAPI.info('Info log message for test "test" with attachment');
    PublicReportingAPI.warn('Warning for test "test"');
    PublicReportingAPI.error('Error log message for test "test"');
    PublicReportingAPI.fatal('Fatal log message for test "test"');
  });
});

Attributes for steps and suites

addAttributes (attributes). Add attributes(tags) to the current test/suite. Should be called inside of corresponding test or suite.
attributes is array of pairs of key and value:

[{
  key: "attributeKey1",
  value: "attributeValue2",
}]

Key is optional field.

Mocha doesn't allow functional calls directly into describe section. You can call addAttributes inside of before/after hooks to add attributes to the corresponding suite.

Example:

const PublicReportingAPI = require('@reportportal/agent-js-mocha/lib/publicReportingAPI');
...
describe('suite',()=>{
  before(function (){
    PublicReportingAPI.addAttributes([{ key: 'suiteAttr1Key', value: 'suiteAttr1Value' }, { value: 'suiteAttr2' }]);
  });
  it('test', () => {
    PublicReportingAPI.addAttributes([{ key: 'testAttr1Key', value: 'testAttr1Value' }]);
    PublicReportingAPI.addAttributes([{ value: 'testAttr2' }]);
  });
});

Integration with Sauce Labs

To integrate with Sauce Labs just add attributes:

[{
 "key": "SLID",
 "value": "# of the job in Sauce Labs"
}, {
 "key": "SLDC",
 "value": "EU (EU or US)"
}]

Description for steps and suites

setDescription (description). Set text description to the current test/suite. Should be called inside of corresponding test or suite.

Mocha doesn't allow functional calls directly into describe section. You can call setDescription inside of before/after hooks to set description to the corresponding suite.

Example:

const PublicReportingAPI = require('@reportportal/agent-js-mocha/lib/publicReportingAPI');
...
describe('suite',()=>{
  before(function (){
    PublicReportingAPI.setDescription('suite description');
  });
  it('test', () => {
    PublicReportingAPI.setDescription('test description');
  });
});

Test case id for steps and suites

setTestCaseId (testCaseId). Set test case id to the current test/suite. Should be called inside of corresponding test or suite.

Mocha doesn't allow functional calls directly into describe section. You can call setTestCaseId inside of before/after hooks to set test case id to the corresponding suite.

Example:

const PublicReportingAPI = require('@reportportal/agent-js-mocha/lib/publicReportingAPI');
...
describe('suite',()=>{
  before(function (){
    PublicReportingAPI.setTestCaseId('TestCaseIdForTheSuite');
  });
  it('test', () => {
    PublicReportingAPI.setTestCaseId('TestCaseIdForTheTest');
  });
});

Finish launch/test item with explicit status

PublicReportingAPI provides the following methods for setting status to the current suite/spec.

• setStatus(status). Assign status to the current test. If called outside of the test (for example in before/after hooks), status is assigned to the current suite.
  status should be equal to one of the following values: passed, failed, stopped, skipped, interrupted, cancelled, info, warn.
  

You can use the shorthand forms of the setStatus method:

• setStatusPassed(). Assign passed status to the current test or suite.
• setStatusFailed(). Assign failed status to the current test or suite.
• setStatusSkipped(). Assign skipped status to the current test or suite.
• setStatusStopped(). Assign stopped status to the current test or suite.
• setStatusInterrupted(). Assign interrupted status to the current test or suite.
• setStatusCancelled(). Assign cancelled status to the current test or suite.
• setStatusInfo(). Assign info status to the current test or suite.
• setStatusWarn(). Assign warn status to the current test or suite.

There are also the corresponding methods for setting status into the launch:

• setLaunchStatus(status). Assign status to the launch.
  status should be equal to one of the following values: passed, failed, stopped, skipped, interrupted, cancelled, info, warn.
  
• setLaunchStatusPassed(). Assign passed status to the launch.
• setLaunchStatusFailed(). Assign failed status to the launch.
• setLaunchStatusSkipped(). Assign skipped status to the launch.
• setLaunchStatusStopped(). Assign stopped status to the launch.
• setLaunchStatusInterrupted(). Assign interrupted status to the launch.
• setLaunchStatusCancelled(). Assign cancelled status to the launch.
• setLaunchStatusInfo(). Assign info status to the launch.

Example:

const PublicReportingAPI = require('@reportportal/agent-js-mocha/lib/publicReportingAPI');
...
describe('suite',()=>{
  it('test info', function() {
    PublicReportingAPI.setStatusFailed();
    expect(true).to.be.equal(true);
  });
});

Copyright Notice

Licensed under the Apache License v2.0

Changelog

[5.1.0] - 2024-07-29

Changed

• Breaking change Drop support of Node.js 10. The version 5.0.4 is the latest that supports it.
• @reportportal/client-javascript bumped to version 5.1.4, new launchUuidPrintOutput types introduced: 'FILE', 'ENVIRONMENT'.
• mocha bumped to version 10.7.0.

Security

• Updated versions of vulnerable packages (braces).

Deprecated

• Node.js 12 usage. This minor version is the latest that supports Node.js 12.