protractor-simple-cucumber-html-reporter-plugin

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 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 [simple-cucumber-html-reporter] as a dependency and use it on the fly to generate beautiful reports.

Supported versions

Installation

npm install protractor-simple-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-simple-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-simple-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-simple-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 simple-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

=====================================================================================================
    single Cucumber HTML report generated in:

    /Users/rahul/protractor-simple-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'},
        {label: 'Execution Start Time', value: 'Nov 19th 2017, 02:31 PM EST'},
        {label: 'Execution End Time', value: 'Nov 19th 2017, 02:56 PM EST'}
    ]
}

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

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.

disableLog

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

This will disable the log so will NOT see this.

=====================================================================================================
    single Cucumber HTML report generated in:

    /Users/rahul/protractor-simple-cucumber-html-reporter-plugin/.tmp/report/index.html
=====================================================================================================

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

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

removeExistingJsonReportFile

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

Setting 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 simple-cucumber-html-reporter.

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 simple-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

simple-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