protractor-cucumber-framework

Protractor Cucumber Framework

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 - 8.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:

• Reference implementation with Serenity BDD reports
• Cucumber.js docs
• Protractor docs
• Serenity/JS docs
• Gherkin reference

Installation

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 14, 16, or 18.

Odd-numbered Node.js releases (13, 15, 19, etc.) are not on the LTS line, should be considered experimental, and should not be used in production.

Upgrading from previous versions and backward compatibility

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.

Configuration

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',
        ]
    }
};

Using TypeScript

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', () => {

});

Using Serenity/JS directly

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,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
};

Using Serenity/JS reporting services

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.

Using Serenity/JS console reporter

To use Serenity/JS console reporter, install the following dependencies:

npm install --save-dev @serenity-js/{core,cucumber,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
};

Using Serenity BDD reporter

To use the Serenity BDD reporter, install the following dependencies:

npm install --save-dev @serenity-js/{core,cucumber,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"
    }
}

Configuring Cucumber

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 --require arguments
• rerun - value is passed as an argument; for use with the rerun feature

Formatters when tests are sharded or with multi capabilities

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.

Uncaught Exceptions

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.

Contributing

Pull requests are welcome. Commits should be generated using npm run commit command.

For Contributors

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

Testing

npm test

Your feedback matters!

Do you find Serenity/JS useful? Give it a star! ★

Found a bug? Need a feature? Raise an issue or submit a pull request.

Have feedback? Let me know on Twitter: @JanMolak

If you'd like to chat with fellow users of Serenity/JS, join us on Serenity/JS Community Chat.

New tutorials and videos are coming soon, follow us on LinkedIn and subscribe to Serenity/JS YouTube channel to get notified when they're available!

And if Serenity/JS has made your life a little bit easier, please support its ongoing development.