@reportportal/agent-js-jasmine

@reportportal/agent-js-jasmine

Agent to integrate Jasmine with ReportPortal.

• More about Jasmine
• More about ReportPortal

Installation

Install the agent in your project:

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

Configuration

1. Create the reportportalConf.js file with ReportPortal configuration:

module.exports = {
  apiKey: "<API_KEY>",
  endpoint: "http://your.reportportal.server/api/v1",
  project: 'Your reportportal project name',
  launch: 'Your launch name',
  attributes: [
      {
          "key": "YourKey",
          "value": "YourValue"
      },
      {
          "value": "YourValue"
      },
  ],
  description: 'Your launch description',
};

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.
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.
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).
attachPicturesToLogs	Optional	false	If set to 'true' then attempts will be made to attach screenshots to the logs.
reportHooks	Optional	false	Determines report before and after hooks or not.
token	Deprecated	Not set	Use apiKey instead.

2. Create the agent and add the reporter it to the Jasmine:

const ReportportalAgent = require('@reportportal/agent-js-jasmine');
const reportportalConfig = require('./reportportalConf');

const agent = new ReportportalAgent(reportportalConfig);

jasmine.addReporter(agent.getJasmineReporter());

3. After the Jasmine completes its work, wait for the agent to finish:

agent.getExitPromise().then(() => {
    console.log('finish work');
})

Reporting

The agent provides an API to extend the functionality of Jasmine.

Add PublicReportingAPI into your test file to use additional reporting features.

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

Report static attributes, description

Inside your suite or spec call PublicReportingAPI.setDescription(), PublicReportingAPI.addAttributes()

setDescription method inside your suite

Parameter	Required	Description	Examples
description	true	"string" - text description for your suite	"Your description"
suite	true	"string" - description of your suite (all suite descriptions must be unique)	"Suite"

addAttributes method inside your suite

Parameter	Required	Description	Examples
attributes	true	attributes, pairs of key and value	[{ "key": "YourKey", "value": "YourValue" }]
suite	true	"string" - description of your suite (all suite descriptions must be unique)	"Suite"

setDescription method inside your spec

Parameter	Required	Description	Examples
description	true	"string" - text description for your suite	"Your description"

addAttributes method inside your spec

Parameter	Required	Description	Examples
attributes	true	attributes, pairs of key and value	[{ "key": "YourKey", "value": "YourValue" }]

To integrate report with Sauce Labs just add attributes:

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

Report logs and attachments

PublicReportingAPI provides the following methods for reporting logs into the current suite/spec.

• log(level, message , file, suite). Reports message and optional file with specified log level as a log of the current suite/spec.
  

level should be equal to one of the following values: TRACE, DEBUG, INFO, WARN, ERROR, FATAL.
suite it's description of your suite (all suite descriptions must be unique) REQUIRED INSIDE OF YOUR SUITE, OPTIONAL FOR SPEC
file should be an object (REQUIRED INSIDE YOUR SUITE, if there is no file object, set NULL) :

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

• trace (message , file, suite). Reports message and optional file as a log of the current suite/spec with trace log level.
• debug (message , file, suite). Reports message and optional file as a log of the current suite/spec with debug log level.
• info (message , file, suite). Reports message and optional file as log of the current suite/spec with info log level.
• warn (message , file, suite). Reports message and optional file as a log of the current suite/spec with warning log level.
• error (message , file, suite). Reports message and optional file as a log of the current suite/spec with error log level.
• fatal (message , file, suite). Reports message and optional file as a log of the current suite/spec 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.

Finish launch/suite/spec with status

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

• setStatus(status, suite). Assign status to the current suite/spec.
  

status should be equal to one of the following values: passed, failed, stopped, skipped, interrupted, cancelled, info, warn.
suite it's description of your suite (all suite descriptions must be unique) REQUIRED INSIDE OF YOUR SUITE, OPTIONAL FOR SPEC

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

PublicReportingAPI provides 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.

• setLaunchStatusWarn(). Assign warn status to the launch.

Report test case id for steps and suites

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

suite it's description of your suite (all suite descriptions must be unique) REQUIRED INSIDE OF YOUR SUITE, OPTIONAL FOR SPEC

Example:

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

describe('A suite', function() {
    const suiteAttachment = {
      name: 'attachment.png',
      type: 'image/png',
      content: data.toString('base64'),
    }
    PublicReportingAPI.addAttributes([{
        key: 'suiteKey',
        value: 'suiteValue',
    }], 'A suite');
    PublicReportingAPI.setDescription('Suite description', 'A suite');
    PublicReportingAPI.debug('Debug log message for suite "suite"', null, 'A suite');
    PublicReportingAPI.info('Info log message for suite "suite"', suiteAttachment, 'A suite');
    PublicReportingAPI.warn('Warning for suite "suite"', null, 'A suite');
    PublicReportingAPI.error('Error log message for suite "suite"', null, 'A suite');
    PublicReportingAPI.fatal('Fatal log message for suite "suite"', suiteAttachment, 'A suite');
    PublicReportingAPI.setLaunchStatusPassed();
    PublicReportingAPI.setStatusPassed('A suite');
    PublicReportingAPI.setTestCaseId('TestCaseIdForSuite', 'A suite');

    it('spec', function() {
        const specAttachment = {
          name: 'attachment.png',
          type: 'image/png',
          content: data.toString('base64'),
        }
        PublicReportingAPI.addAttributes([{
            key: 'specKey',
            value: 'specValue'
        }]);
        PublicReportingAPI.setDescription('Spec description');
        PublicReportingAPI.log('INFO', 'Info log message for spec "spec" with attachment', specAttachment);
        PublicReportingAPI.launchLog('ERROR', 'Error log message for current launch with attachment', specAttachment);
        PublicReportingAPI.trace('Trace log message for spec "spec"', specAttachment);
        PublicReportingAPI.debug('Debug log message for spec "spec"');
        PublicReportingAPI.info('Info log message for spec "spec" with attachment');
        PublicReportingAPI.warn('Warning for spec "spec"');
        PublicReportingAPI.error('Error log message for spec "spec"');
        PublicReportingAPI.fatal('Fatal log message for spec "spec"');
        PublicReportingAPI.setStatusPassed();
        PublicReportingAPI.setTestCaseId('TestCaseIdForSpec');

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

Integrations

Protractor integration

Launch agent in single thread mode.

If you launch protractor in single tread mode, just add agent initialization to the onPrepare function. Add agent.getJasmineReporter to the jasmine.getEnv().addReporter() as an argument. You can see this in the example bellow. Update your configuration file as follows:

const ReportportalAgent = require('@reportportal/agent-js-jasmine');

...
const agent = new ReportportalAgent({
        token: "00000000-0000-0000-0000-000000000000",
        endpoint: "http://your.reportportal.server/api/v1",
        launch: "LAUNCH_NAME",
        project: "PROJECT_NAME",
        attachPicturesToLogs: false,
        attributes: [
            {
                "key": "YourKey",
                "value": "YourValue"
            },
            {
                "value": "YourValue"
            },
        ]
    });
exports.config = {
    ...
    onPrepare: ()=> {
        ...
        jasmine.getEnv().addReporter(agent.getJasmineReporter());
    },
    afterLaunch:() => {
        return agent.getExitPromise();
    }
};

Launch agents in multi thread mode.

For launching agents in multi thread mode firstly parent launch must be created and it ID must be sent to the child launches , so they would send data to the right place, and wouldn't create new launch instances at the Report Portal.

The main problem is that node.js is a single threaded platform. And for providing multi treading launch with browsers protractor generate new processes of node, which can't interact with each other, so Singelton objects or functions can't be created for synchronizing it work. Only primitive types could be sent as args to the new processes before launch. The way of resolving this problem is to create launch file that would generate a Parent Launch and send launch's ID to protractor as argument. Then protractor would launch jasmine-agents with parent ID. Look through example of the Launch File with protractor-flake module at the 'Settings fot the multi threaded launch' section or at the examples folder. Any node runner could be used!

• Install 'protractor-flake':

npm install protractor-flake --save-dev

• Create a config file as in example below:

reportportalConf.js

module.exports = {
    token: "00000000-0000-0000-0000-000000000000",
    endpoint: "http://your.reportportal.server/api/v1",
    launch: "LAUNCH_NAME",
    project: "PROJECT_NAME",
    attachPicturesToLogs: false,
    attributes: [
        {
            "key": "YourKey",
            "value": "YourValue"
        },
        {
            "value": "YourValue"
        },
    ]
}

• Create a main launch file as in example below:

protractorLaunchFile.js

const protractorFlake = require('protractor-flake');
const AgentJasmine = require('@reportportal/agent-js-jasmine');
const reportportalConfig = require('./reportportalConf');
const agent = new AgentJasmine(reportportalConfig);

agent.getLaunchStartPromise().then((launchData) =>{
    protractorFlake({
        maxAttempts: 1,
        protractorArgs: [
            './multiThreadConf.js',
            '--params.id',
            launchData.id
        ]
    }, (status) => {
        agent.getExitPromise().then(() =>{
            process.exit(status);
        });
    });
});

• Then create protractor's spec file as in example below:

multiThreadConf.js file

 const ReportportalAgent = require('@reportportal/agent-js-jasmine');
 const reportportalConfig = require('./reportportalConf');

 exports.config = {
     multiCapabilities: [
         {
             name: 'normal',
             browserName: 'chrome',
             maxInstances: 2,
             shardTestFiles: true,
             chromeOptions: {
                 args: ['--window-size=1024,768', '--disable-infobars']
             }
         }
     ],
     specs: ['testAngularPage.spec.js', 'testGithubPage.spec.js'],
     onPrepare() {
         const config = Object.assign({
             id: browser.params.id
         }, reportportalConfig);
         const agent = new ReportportalAgent(config);
         /*Its a hack. There is an issue since 2015. That Jasmine doesn't wait for report's async functions.
          links to the issues https://github.com/jasmine/jasmine/issues/842
          https://github.com/angular/protractor/issues/1938
          So it needed to wait until requests would be sent to the Report Portal.
          */
         afterAll((done) => agent.getPromiseFinishAllItems(agent.tempLaunchId).then(()=> done()));
         jasmine.getEnv().addReporter(agent.getJasmineReporter());
     }

 };

• Update script section for your package.json:

"scripts": {
    "protractor-multi": "node protractorLaunchFile.js"
 }

• Run your protractor:

npm run protractor-multi

See the detailed example with tests in examples.

Link to the jasmine issue, that it doesn't work well with async functions jasmine issue, protractor's community

Copyright Notice

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

Changelog

[5.2.0] - 2024-10-03

Changed

• Breaking change Drop support of Node.js 12. The version 5.1.0 is the latest that supports it.
• 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.

Security

• Updated versions of vulnerable packages (micromatch).