This framework was originally part of angular/protractor and is now a separate module to decouple cucumber.js.
The project relies on Serenity/JS to enable integration between Protractor and Cucumber 1.x - 10.x and offer support for both Cucumber.js-native and Serenity/JS reporters.
To see Serenity/JS reports in action, check out the reference implementation and the Serenity BDD reports it produces.
Learn more:
- Serenity/JS website
- Reference implementation with Serenity BDD reports
- Cucumber.js docs
- Protractor docs
- Gherkin reference
Serenity/JS offers a smooth transition for your Protractor tests, allowing you to migrate them gradually to WebdriverIO or Playwright while ensuring your test suite continues to work.
Learn more about migrating from Protractor to Serenity/JS and chat with the Serenity/JS community if you have any questions about the migration.
To install this module, run the following command in your computer terminal:
npm install --save-dev protractor-cucumber-framework
Please note that to use protractor-cucumber-framework you'll need a recent Long-Term Support versions of Node.js, so 16, 18, or 20.
Odd-numbered Node.js releases (17, 19, 21, etc.) are not on the LTS line, should be considered experimental, and should not be used in production.
protractor-cucumber-framework is a thin wrapper around
@serenity-js/cucumber and @serenity-js/protractor modules.
Just like Serenity/JS, this module:
- supports all the major versions of Cucumber.js,
- supports both Protractor v5 and v7,
- is backward compatible with previous major versions of
protractor-cucumber-framework.
To stay up to date with the latest features, patches, and security fixes make sure to always use the latest version of protractor-cucumber-framework as this module offers backward compatibility with other dependencies, like cucumber, @cucumber/cucumber, or protractor.
To use protractor-cucumber-framework, configure it as a custom framework
in your protractor.conf.js:
exports.config = {
// set to "custom" instead of cucumber.
framework: 'custom',
// path relative to the current config file
frameworkPath: require.resolve('protractor-cucumber-framework'),
// require feature files
specs: [
'path/to/feature/files/**/*.feature' // accepts a glob
],
cucumberOpts: {
// require step definitions
require: [
'features/step_definitions/**/*.steps.js', // accepts a glob
'features/support/*.ts',
]
}
};Cucumber step definitions can be implemented in TypeScript and transpiled in memory
to JavaScript via ts-node.
To use TypeScript, install the following dependencies:
npm install --save-dev typescript ts-node @types/node
Next, create a tsconfig.json file in the root
directory of your project:
{
"compilerOptions": {
"target": "ES2019",
"lib": [
"ES2019"
],
"module": "commonjs",
"moduleResolution": "node",
"sourceMap": true,
"declaration": false
},
"include": [
"features/**/*.ts"
],
"exclude": [
"node_modules"
]
}Finally, set the cucumberOpts.requireModule option in protractor.conf.js to ts-node/register
and configure Cucumber to load .ts files instead of .js:
exports.config = {
framework: 'custom',
frameworkPath: require.resolve('protractor-cucumber-framework'),
specs: [
'features/**/*.feature'
],
cucumberOpts: {
require: [
'features/step_definitions/**/*.steps.ts', // *.ts instead of *.js
'features/support/*.ts',
],
requireModule: [
'ts-node/register' // use ts-node to transpile TypeScript in memory
],
},
};You can now implement Cucumber step definitions in TypeScript, for example:
// features/step_definitions/example.steps.ts
import { When, Then } from '@cucumber/cucumber'
When('developers like type safety', () => {
});
Then('they should use TypeScript', () => {
});Since protractor-cucumber-framework is just a thin wrapper around Serenity/JS modules,
you can depend on them directly to make sure you always get the latest and greatest features.
To configure your project to use Serenity/JS, remove the dependency on protractor-cucumber-framework and install the following dependencies instead:
npm install --save-dev @serenity-js/{core,cucumber,web,protractor}
Next, configure your protractor.conf.js file as follows:
exports.config = {
framework: 'custom',
frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
serenity: {
runner: 'cucumber',
crew: [
// Serenity/JS reporting services
]
},
cucumberOpts: {
// Cucumber config
}
// other Protractor config
};To use Serenity/JS reporting services, configure your project to depend on Serenity/JS directly as per the previous section to make sure that your Serenity/JS dependencies are up-to-date and compatible.
To use Serenity/JS console reporter, install the following dependencies:
npm install --save-dev @serenity-js/{core,cucumber,web,protractor,console-reporter}
Next, configure your protractor.conf.js as follows:
const { ConsoleReporter } = require('@serenity-js/console-reporter');
exports.config = {
framework: 'custom',
frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
specs: [ 'features/**/*.feature' ],
serenity: {
runner: 'cucumber',
crew: [
ConsoleReporter.forDarkTerminals(),
]
},
// other config
};To use the Serenity BDD reporter, install the following dependencies:
npm install --save-dev @serenity-js/{core,cucumber,web,protractor,serenity-bdd} npm-failsafe rimraf
Next, configure your protractor.conf.js as follows:
const
{ ArtifactArchiver } = require('@serenity-js/core'),
{ SerenityBDDReporter } = require('@serenity-js/serenity-bdd');
exports.config = {
framework: 'custom',
frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
serenity: {
runner: 'cucumber',
crew: [
ArtifactArchiver.storingArtifactsAt('./target/site/serenity'),
new SerenityBDDReporter(),
]
},
// other config
};To automatically download the Serenity BDD reporter CLI when you install your Node modules, add the following postinstall script to your package.json file:
{
"scripts": {
"postinstall": "serenity-bdd update",
}
}To generate Serenity BDD reports when you run your tests, configure your test script to invoke serenity-bdd run when your tests are finished:
{
"scripts": {
"postinstall": "serenity-bdd update",
"clean": "rimraf target",
"test": "failsafe clean test:execute test:report",
"test:execute": "protractor ./protractor.conf.js",
"test:report": "serenity-bdd run --features ./features"
}
}All of the cucumberOpts will be passed to cucumberjs as arguments.
For example, to call Cucumber with the --strict flag and to specify custom formatters:
exports.config = {
framework: 'custom',
frameworkPath: require.resolve('@serenity-js/protractor/adapter'),
specs: [
'features/**/*.feature'
],
cucumberOpts: {
strict: true,
format: [
'progress',
'pretty:output.txt'
],
// ...
}
}The following parameters have special behaviour:
require- globs will be expanded to multiple--requireargumentsrerun- value is passed as an argument; for use with the rerun feature
If you have a formatter that outputs to a path and your tests are sharded or you have multi capabilities then this library will add the PID to the path to make them unique. The reason for this is multiple processes can write to the same path which ends up clobbering each other. You'll end up with 1 file per process that protractor spawns.
exports.config = {
capabilities: {
shardTestFiles: true,
// ...
},
cucumberOpts: {
format: 'json:results.json',
// ...
}
};If there were 2 feature files then you can expect the following output files...
results.11111.json
results.22222.json
...where the numbers will be the actual PIDs.
If your process abruptly stops with an exit code 199 then your steps most likely threw an uncaught
exception. Protractor is capturing these and exiting the process in this situation. The solution is
to upgrade to at least protractor version 7.0.0 and add the following to your protractor conf...
ignoreUncaughtExceptions: true
This allows cucumber to handle the exception and record it appropriately.
Pull requests are welcome. Commits should be generated using npm run commit command.
Ensure that the following dependencies are installed:
- Java Runtime Environment (JRE) 8 or newer
- Node.js LTS
- Google Chrome
Clone the github repository:
git clone https://github.com/protractor-cucumber-framework/protractor-cucumber-framework
cd protractor-cucumber-framework
npm install
npm test
Do you find Serenity/JS useful? Give it a ⭐ star on GitHub and rate it on Openbase!
Found a bug? Need a feature? Raise an issue or submit a pull request.
Have feedback? Let me know on LinkedIn or leave a comment in Serenity/JS discussions on GitHub
If you'd like to chat with fellow users of Serenity/JS, join us on Serenity/JS Community Chat.
Serenity/JS is a free open-source framework, so we rely on our wonderful GitHub sponsors to keep the lights on.
If you appreciate all the effort that goes into making sophisticated tools easy to work with, please support our work and become a Serenity/JS GitHub Sponsor today!
