npm package: @reportportal/agent-js-mocha
Description: Agent to integrate Mocha with ReportPortal.
Author: ReportPortal.io
Latest version: 5.1.0

# @reportportal/agent-js-mocha

Agent to integrate Mocha with ReportPortal.
* More about [Mocha](https://mochajs.org/)
* More about [ReportPortal](http://reportportal.io/)

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

## Installation

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

## Configuration

Fill in the `reporterOptions` in Mocha configuration.
```javascript
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`:
```javascript
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](https://reportportal.io/docs/dev-guides/RerunDevelopersGuide)                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 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 <br/> *'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](https://github.com/axios/axios#request-config). May contain `agent` property for configure [http(s)](https://nodejs.org/api/https.html#https_https_request_url_options_callback) client, and other client options e.g. `proxy`, [`timeout`](https://github.com/reportportal/client-javascript#timeout-30000ms-on-axios-requests). For debugging and displaying logs the `debug: true` option can be used. <br/> Visit [client-javascript](https://github.com/reportportal/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'. <br/> Option could be equal boolean values: <br/> *true* - skipped tests considered as issues and will be marked as 'To Investigate' on reportportal. <br/> *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](https://github.com/reportportal/examples-js/tree/master/example-mocha).

## 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.

```javascript
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.<br/>
*level* shoud be equal to one the following values: *TRACE*, *DEBUG*, *INFO*, *WARN*, *ERROR*, *FATAL*.<br/>
*file* should be an object: <br/>
```javascript
{
  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:**
```javascript
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.</br>
*attributes* is array of pairs of key and value:
```javascript
[{
  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:**
```javascript
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:

```javascript
[{
 "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.</br>

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:**
```javascript
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.</br>

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:**
```javascript
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.<br/>
*status* should be equal to one of the following values: *passed*, *failed*, *stopped*, *skipped*, *interrupted*, *cancelled*, *info*, *warn*.<br/>

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.<br/>
*status* should be equal to one of the following values: *passed*, *failed*, *stopped*, *skipped*, *interrupted*, *cancelled*, *info*, *warn*.<br/>
* 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:**
```javascript
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](LICENSE)