Grunt Cucumberjs
================
***Grunt task to run Cucumber.js. Outputs results in various HTML themes. Runs Cucumber.js in Parallel***
[![v][npm-shield]][npm-link] [![v][license-shield]][license-link]
## Getting Started
If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
```shell
npm install grunt-cucumberjs --save-dev
```
***Note:***
1. Install grunt-cucumberjs@1.0.2 for cucumber version < Cucumber@2
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
```js
grunt.loadNpmTasks('grunt-cucumberjs');
```
## Sample HTML Reports
1. [Bootstrap Theme Reports with Pie Chart][3]
2. [Foundation Theme Reports][4]
3. [Simple Theme Reports][5]
## Snapshot of Bootstrap Report
![Alt text](/test/cucumber-reports/screenshot/cucumber_report_bootstrap_snapshot.png "Snapshot - Bootstrap Report")
## The "cucumberjs" task
### Overview
In your project's Gruntfile, add a section named `cucumberjs` to the data object passed into `grunt.initConfig()`.
```js
grunt.initConfig({
cucumberjs: {
options: {
format: 'html',
output: 'my_report.html',
theme: 'bootstrap'
},
my_features: ['features/feature1.feature', 'features/feature2.feature'],
other_features: {
options: {
output: 'other_report.html'
},
src: ['other_features/feature1.feature', 'other_features/feature2.feature']
}
}
});
```
If all your feature files are located in the default location of ```features/``` then just leave the feature configuation as an empty array. See following:
```
cucumberjs: {
options: {
format: 'html',
output: './public/report.html',
theme: 'foundation'
},
features : []
}
```
## Usage
```bash
#runs all features specified in task
$ grunt cucumberjs
#you can override options via the cli
$ grunt cucumberjs --require=test/functional/step_definitions/ --features=features/myFeature.feature --format=pretty
```
## Options
#### options.steps
Type: `String`
Default: `''`
Passes the value as ```--steps``` parameter to cucumber.
#### options.require
Type: `String`
Default: `''`
Passes the value as ```--require``` parameter to cucumber. If an array, each item is passed as a separate ```--require``` parameter.
Use if step_definitions and hooks are NOT in default location of ```features/step_definitions```
#### options.tags
Type: `String|Array`
Default: `''`
Passes the value as ```--tags``` parameter to cucumber. If an array, each item is passed as a separate ```--tags``` parameter.
We've seen issues in cucumberjs using the old style of negative tag expression such as ```'~@ignore'```. Suggest that you use the expanded syntax ```'not @ignore'``` instead.
[Cucumber Tag Expressions](https://docs.cucumber.io/tag-expressions/)
#### options.theme
Type: `String`
Default: `'foundation'`
Available: `['foundation', 'bootstrap', 'simple']`
Specifies which theme to use for the html report
#### options.templateDir
Type: `String`
Default: `'features/templates'`
Location of your custom templates. Simply name the template the same as the one you are trying to override and
grunt-cucumberjs will use it over the default template
#### options.output
Type: `String`
Default: `'features_report.html'`
#### options.format
Type: `String`
Default: `'html'`
Available: `['pretty', 'progress', 'summary', 'html']`
#### options.formats
Supports multiple formatter.
Type: `Array`
Available: `['pretty', 'progress', 'summary', 'html']`
e.g. `formats: ['html', 'pretty']`
Enable `debug: true` to print pretty console.
Note: `html` formatter will provide Json as well as `html` report. Multiple formatter is supported for cucumber v@0.8.0 or higher.
#### options.executeParallel
Type: `Boolean`
Default: `'undefined'`
Available: `['true', 'false']`
A flag to enable Parallel execution.
```
• You can run Cucumber Features and/or Scenarios Parallel
• `--parallel scenarios` runs scenarios parallel
• By default or `--parallel features` runs features in parallel
```
For more information visit [cucumber-parallel][8] module
#### options.failFast
Type: `Boolean`
Default: `'false'`
Available: `['true', 'false']`
ends the suite after the first failure
it can also be activated without setting `options.failFast` and passing `--fail-fast` as a grunt task option
#### options.noStrict
Type: `Boolean`
Default: `'false'`
Available: `['true', 'false']`
will cause cucumber to succeed even if there are undefined or pending steps.
it can also be activated without setting `options.noStrict` and passing `--no-strict` as a grunt task option
#### options.dryRun
Type: `Boolean`
Default: `'false'`
Available: `['true', 'false']`
dry-run the suite and provides snippets for pending steps
it can also be activated without setting `options.dryRun` and passing `--dry-run` as a grunt task option
#### options.debug
Type: `Boolean`
Default: `'false'`
Available: `['true', 'false']`
A flag to turn console log on or off
#### options.debugger
Type: `Boolean`
Default: `'false'`
Available: `['true', 'false']`
A flag to enabling debugging from IDE like WebStorm. Limitation of this flag is it only does not support the HTML output, yet ;)
#### options.rerun
Type: `String`
Default: `undefined`
Rerun the failed scenarios recorded in the `@rerun.txt` file.
To Re-run failed scenarios:
* Set the cucumber-js task format to `rerun:@rerun.txt`
```
options: {
format: 'rerun:@rerun.txt',
.....
....
}
```
It will record all the failed scenarios to `@rerun.txt`.
Take a look at `options.formats` to generate html report
* Run failed scenarios by passing `--rerun=path/to/@rerun.txt` grunt option
N.B.: If `@rerun.txt` file does not exists or if file is empty, the grunt task will return success.
#### options.compiler
Type: `String`
Sets the Cucumber Compiler options. It can also be set by passing through command line `--compiler`
#### options.reportSuiteAsScenarios
Type: `Boolean`
Default: `'false'`
Available: `['true', 'false']`
Reports total number of failed/passed Scenarios in headers if set to `true`.
Reports total number of failed/passed Features in headers if set to `false` or `undefined`.
#### options.launchReport
Type: `Boolean`
Automatically launch HTML report at the end of test suite
`true`: Launch HTML report in the default browser
`false`: Do not launch HTML report at the end of test suite
#### `metadata`
Type: `JSON` (optional)
Default: `undefined`
Print more data to your report, such as _browser info, platform, app info, environments_ etc. Data can be passed as JSON `key-value` pair. Reporter will parse the JSON and will show the _Key-Value_ under `Metadata` section on HTML report. Checkout the below preview HTML Report with Metadata.
Pass the _Key-Value_ pair as per your need, as shown in below example,
```json
metadata: {
"App Version":"0.3.2",
"Test Environment": "STAGING",
"Browser": "Chrome 54.0.2840.98",
"Platform": "Windows 10",
"Parallel": "Scenarios",
"Executed": "Remote"
}
```
* [HTML Report Preview with Metadata][3]
### Pie Charts
Sample pie chart is available at [Bootstrap Theme Report with Pie Chart][3]
Two pie charts are displayed on report
1. Features: number of passed/failed features
2. Scenarios: number of passed/failed/pending scenarios.
Please note that Pie Charts are available only for Bootstrap Theme.
## Changelog
[changelog][changelog]
### Tips
Take a look at [cucumber-html-reporter][9] for more information on <b> Attaching ScreenShots, Plain Texts, Pretty JSON </b> to the HTML report
[1]: https://code.google.com/p/selenium/wiki/WebDriverJs "WebDriverJS"
[2]: https://github.com/cucumber/cucumber-js "cucumber-js"
[3]: http://htmlpreview.github.io/?https://github.com/gkushang/cucumber-html-reporter/blob/develop/samples/html_reports/cucumber_report_bootstrap.html "Bootstrap Theme Reports"
[4]: http://htmlpreview.github.io/?https://github.com/gkushang/grunt-cucumberjs/blob/cucumber-reports/test/cucumber-reports/cucumber-report-foundation.html "Foundation Theme Reports"
[5]: http://htmlpreview.github.io/?https://github.com/gkushang/grunt-cucumberjs/blob/cucumber-reports/test/cucumber-reports/cucumber-report-simple.html "Simple Theme Reports"
[8]: https://www.npmjs.com/package/cucumber-parallel
[9]: https://www.npmjs.com/package/cucumber-html-reporter
[changelog]: https://github.com/mavdi/grunt-cucumberjs/blob/master/CHANGELOG.md
[npm-shield]: https://img.shields.io/npm/v/grunt-cucumberjs.svg
[npm-link]: https://www.npmjs.com/package/grunt-cucumberjs
[license-shield]: https://img.shields.io/github/license/mashape/apistatus.svg
[license-link]: https://github.com/mavdi/grunt-cucumberjs/