protractor-multiple-cucumber-html-reporter-plugin

Important News

Date: 8th of May I decided to stop maintaining this package per today and add the DEPRECATED status to all versions

Date: 16th of January 2020

I will stop maintaining this module per the first of July 2020. If you look at Protractor you can get the feeling that, in spite of all the effort that the Open Source Community is putting in it, it is not being maintained by Google anymore. To be honest, I'm pretty sure about it. If you look at the facts, see image below, you will notice that:

• the amount of issues is increasing
• the amount of PR's is increasing
• the activity in the project is decreasing

This is not giving me a good feeling. As a contributor to the Protractor project in the last years, I also have the feeling that there won't be a big chance that this is going to change.

I'm not the only one who thinks about Protractor like this, please take a look at this great article which might also give you some insights.

I want to thank all contributors for their help in the past 3-4 years and I feel blessed that I was able to help so many people over the last few years.

This plugin will connect Protractor, CucumberJS and protractor-cucumber-framework to generate unique JSON files per feature with only a few lines of code. It will also replace the extra CucumberJS hook you needed to make in CucumberJS 1 and 2 to generate unique JSON report files.

It was born when CucucmberJS 3 removed the registerHandler and registerListener. As of version 3 Protractor and CucumberJS users don't have the possibility to generate and create unique JSON report files. With this module they have.

You will also get multiple-cucumber-html-reporter as a dependency and use it on the fly to generate beautiful reports. A sample can be found here

Supported versions

Node.js	Protractor	CucumberJS	protractor-cucumber-framework	multiple-cucumber-html-reporter
6.x	4.x	1.x	3.1.2 or higher	1.0.0 or higher
7.x	5.x	2.x
		3.x

Installation

npm install protractor-multiple-cucumber-html-reporter-plugin --save-dev

Usage

You need to do 2 things.

1. Add format: 'json:.tmp/results.json' to your cucumberOpts in the config. This will tell CucumbjerJS to generate a JSON-file. As of protractor-cucumber-framework version 3.1.2 you will get unique JSON files, see also here.
2. Add the protractor-multiple-cucumber-html-reporter-plugin in the plugins block inside protractor.config.js.

!!The path that is defined in the format is the path where all files and reports are saved. Advice is not to save the CucumberJS JSON report fil in the root of the project but in for example a .tmp/ folder!!

Here is a short config example of both steps.

const path = require('path');

exports.config = {

    framework: 'custom',
    frameworkPath: require.resolve('protractor-cucumber-framework'),
    cucumberOpts: {
        require: [
            path.resolve(process.cwd(), './**/*.steps.js')
        ],
        // Tell CucumberJS to save the JSON report
        format: 'json:.tmp/results.json',
        strict: true
    },

    specs: [
        '*.feature'
    ],

    multiCapabilities: [{
        browserName: 'chrome',
        shardTestFiles: true,
        maxInstances: 2,
        chromeOptions: {
            args: ['disable-infobars']
        }
    }],

    // Here the magic happens
    plugins: [{
        package: 'protractor-multiple-cucumber-html-reporter-plugin',
        options:{
            // read the options part
        }
    }]
};

Options

If you don't provide options the pluging will use the defaults as mentioned below. Options can be added by creating an object like this:

    plugins: [{
        package: 'protractor-multiple-cucumber-html-reporter-plugin',
        options:{
            // read the options part for more options
            automaticallyGenerateReport: true,
            removeExistingJsonReportFile: true
        }
    }]

automaticallyGenerateReport

• Type: boolean
• Default: false
• Mandatory: No

Setting this option will autimatically generate a new report with multiple-cucumber-html-reporter. It will generate a log at the end of the testexection where you can find the report and looks like this. This means that you don't need to call the report module in a seperate node process. For the options of the report see the options openReportInBrowser, reportPath and saveCollectedJSON

=====================================================================================================
    Multiple Cucumber HTML report generated in:

    /Users/wswebcreation/protractor-multiple-cucumber-html-reporter-plugin/.tmp/report/index.html
=====================================================================================================

customData

• Type: object
• Mandatory: No

You can add a custom data block to the report like this

customData: {
    title: 'Run info',
    data: [
        {label: 'Project', value: 'Custom project'},
        {label: 'Release', value: '1.2.3'},
        {label: 'Cycle', value: 'B11221.34321'}
    ]
}

THIS WILL ONLY WORK WITH automaticallyGenerateReport:true. IF YOU GENERATE THE REPORT LATER PLEASE LOOK AT multiple-cucumber-html-reporter

customMetadata

• Type: boolean
• Mandatory: No

It is possible to provide custom metadata by setting this variable to true. Custom metadata will override the regular metadata completely and potentially have strange formatting bugs if too many (10+) variables are used. The columns will be in the order defined by the order of the list.

Adding the metadata is done in the same way as with normal metadata. The metadata is formed as a list of key-value pairs to preserve order:

metadata: [
        {name: 'Environment v.', value: '12.3'},
        {name: 'Plugin v.', value: '32.1'},
        {name: 'Variable set', value: 'Foo'}
    ]

customStyle

• Type: path
• Mandatory: No

If you need add some custom style to your report. Add it like this customStyle: 'your-path-where/custom.css'

disableLog

• Type: boolean
• Mandatory: No
• Default: false

This will disable the log so will NOT see this.

=====================================================================================================
    Multiple Cucumber HTML report generated in:

    /Users/wswebcreation/protractor-multiple-cucumber-html-reporter-plugin/.tmp/report/index.html
=====================================================================================================

displayDuration

• Type: boolean
• Mandatory: No

If set to true the duration of steps, scenarios and features is displayed on the Features overview and single feature page in an easily readable format. This expects the durations in the report to be in nanoseconds, which might result in incorrect durations when using a version of Cucumber(JS 2 and 3) that does not report in nanoseconds but in milliseconds. This can be changed to milliseconds by adding the parameter durationInMS: true, see below

NOTE: Only the duration of a feature can be shown in the features overview. A total duration over all features CAN NOT be given because the module doesn't know if all features have been run in parallel

durationInMS

• Type: boolean
• Default: false
• Mandatory: No

If set to true the duration of steps will be expected to be in milliseconds, which might result in incorrect durations when using a version of Cucumber(JS 1 or 4) that does report in nanaseconds. This parameter relies on displayDuration: true

jsonOutputPath

• Type: string
• Default: json-output-folder
• Mandatory: No

The directory that will hold all the unique generated JSON files, relative from where the script is started.

N.B.: If you use a npm script from the command line, like for example npm run generate-report the jsonOutputPath will be relative from the path where the script is executed. Executing it from the root of your project will also search for the jsonOutputPath from the root of you project.

If you DON'T provide this it will generate a json-output-folder-folder in the path that it defined the cucumberOpts.format.

metadataKey

• Type: string
• Default: metadata
• Mandatory: No

This will be the key reference in the capabilities or multiCapabilities that will refer to where the instance specific data is saved. The metadata is used for the report that will be generated, see also metadata.

If for example all the metadata is already present in the capabilities but with the key called deviceProperties you can add the option metadataKey: 'deviceProperties' and the plugin will automatically copy the deviceProperties-object to the metadata of the report.

openReportInBrowser

• Type: boolean
• Default: false
• Mandatory: No

Settign this option will automatically open the generated report in the default browser of the operating system. See also here.

overrideStyle

• Type: path
• Mandatory: No

If you need replace default style for your report. Add it like this overrideStyle: 'your-path-where/custom.css'

pageFooter

• Type: string
• Mandatory: No

You can customise Page Footer if required. You just need to provide a html string like <div><p>A custom footer in html</p></div>

pageTitle

• Type: string
• Mandatory: No
• Default: Multiple Cucumber HTML Reporter

You can change the report title in the HTML head Tag

removeExistingJsonReportFile

• Type: boolean
• Default: false
• Mandatory: No

Settign this option will remove the previous unique JSON report file if it exists. It will prevent double reports of 1 feature + browser execution combination when generating te report with multiple-cucumber-html-reporter. This may come in handy when you rerun your flakey features with for example protractor-flake

removeOriginalJsonReportFile

• Type: boolean
• Default: false
• Mandatory: No

Setting this option will remove the original json report file, defined in the cucumberOpts.format. It will clean up the folder where you save all your results and may be needed if you have a lot of JSON-files with screenshots in it.

reportName

• Type: string
• Mandatory: No

You can change the report name to a name you want.

THIS WILL ONLY WORK WITH automaticallyGenerateReport:true. IF YOU GENERATE THE REPORT LATER PLEASE LOOK AT multiple-cucumber-html-reporter

reportPath

• Type: string
• Default: report
• Mandatory: No

The directory in which the report needs to be saved, relative from where the script is started. See also here. If you DON'T provide this it will generate a report-folder in the path that it defined the cucumberOpts.format.

N.B.: If you use a npm script from the command line, like for example npm run generate-report the reportPath will be relative from the path where the script is executed. Executing it from the root of your project will also save the report in the reportPath in the root of you project.

saveCollectedJSON

• Type: boolean
• Default: false
• Mandatory: No

multiple-cucumber-html-reporter will first merge all the JSON-files to 1 file and then enrich it with data that is used for the report. If saveCollectedJSON :true the merged JSON AND the enriched JSON will be saved in the reportPath. They will be saved as:

• merged-output.json
• enriched-output.json

See also here

Metadata

The report can also show on which browser / device a feature has been executed. It is shown on the featurs overview in the table as well as on the feature overview in a container. You can add this by adding the following object to your capabilities or multiCapabilities

    capabilities: {
        browserName: 'chrome',
        chromeOptions: {
            args: ['disable-infobars']
        },
        // Add this
        metadata: {
            browser: {
                name: 'chrome',
                version: '58'
            },
            device: 'MacBook Pro 15',
            platform: {
                name: 'OSX',
                version: '10.12.6'
            }
        }
    }

    // Or
    multiCapabilities: [{
        browserName: 'chrome',
        chromeOptions: {
            args: ['disable-infobars']
        },
        // Add this
        metadata: {
            browser: {
                name: 'chrome',
                version: '58'
            },
            device: 'MacBook Pro 15',
            platform: {
                name: 'OSX',
                version: '10.12.6'
            }
        }
    }

See the metadata information here for the correct values.

If you don't provide a browser.name or a browser.version the module will try to determine this automatically. The rest will be shown as questionmarks in the report

FAQ

• Multiple HTML files generated in the in report/features-folder, but they are not shown in the overview-page: See the answer in issue 13

Changelog/Releases

The Changelog/Releases can be found here

Contributing

How to contribute can be found here

Credits

When creating this plugin I got a lot of inspiration from:

• protractor-cucumber-framework
• cucumber-js
• Protractor plugin-page

Thanks

If this plugin was helpful for you, please give it a ★ Star on Github and npm