@wdio/cucumber-framework

What is @wdio/cucumber-framework?

@wdio/cucumber-framework is a plugin for WebdriverIO that allows you to use the Cucumber testing framework to write and execute feature files written in Gherkin syntax. This integration enables Behavior Driven Development (BDD) by allowing you to define application behavior in plain text and then automate the testing of that behavior.

What are @wdio/cucumber-framework's main functionalities?

Define Feature Files

You can define feature files using Gherkin syntax to describe the behavior of your application. These feature files are written in plain text and can be understood by all stakeholders.

Feature: User login
  Scenario: Successful login with valid credentials
    Given I am on the login page
    When I enter valid credentials
    Then I should be redirected to the dashboard

Step Definitions

Step definitions are used to map the steps in your feature files to actual code that performs the actions. This allows you to automate the testing of the behavior described in your feature files.

const { Given, When, Then } = require('@cucumber/cucumber');

Given('I am on the login page', async () => {
  await browser.url('/login');
});

When('I enter valid credentials', async () => {
  await $('#username').setValue('user');
  await $('#password').setValue('password');
  await $('button[type="submit"]').click();
});

Then('I should be redirected to the dashboard', async () => {
  await expect(browser).toHaveUrl('/dashboard');
});

Hooks

Hooks allow you to run code before and after each scenario or step. This is useful for setting up preconditions or cleaning up after tests.

const { Before, After } = require('@cucumber/cucumber');

Before(async () => {
  // Code to run before each scenario
  await browser.reloadSession();
});

After(async () => {
  // Code to run after each scenario
  await browser.deleteCookies();
});

Other packages similar to @wdio/cucumber-framework

cypress-cucumber-preprocessor

cypress-cucumber-preprocessor is a plugin for Cypress that allows you to use Cucumber with Cypress for BDD testing. It provides similar functionality to @wdio/cucumber-framework but is designed to work with the Cypress testing framework instead of WebdriverIO.

jest-cucumber

jest-cucumber is a library that allows you to use Cucumber with Jest for BDD testing. It provides similar functionality to @wdio/cucumber-framework but is designed to work with the Jest testing framework instead of WebdriverIO.

protractor-cucumber-framework

protractor-cucumber-framework is a plugin for Protractor that allows you to use Cucumber with Protractor for BDD testing. It provides similar functionality to @wdio/cucumber-framework but is designed to work with the Protractor testing framework instead of WebdriverIO.

README

WDIO Cucumber Framework Adapter

A WebdriverIO plugin. Adapter for CucumberJS v5 testing framework.

Installation

The easiest way is to keep @wdio/cucumber-framework as a devDependency in your package.json, via:

npm install @wdio/cucumber-framework --save-dev

Instructions on how to install WebdriverIO can be found here.

Configuration

Following code shows the default wdio test runner configuration...

// wdio.conf.js
module.exports = {
  // ...
  framework: 'cucumber',
  cucumberOpts: {
    timeout: 10000
  }
  // ...
};

cucumberOpts Options

backtrace

Show full backtrace for errors.

Type: Boolean
Default: false

requireModule

Require modules prior to requiring any support files.

Type: String[]
Default: []
Example: ['@babel/register'] or [['@babel/register', { rootMode: 'upward', ignore: ['node_modules'] }]]

failFast

Abort the run on first failure.

Type: Boolean
Default: false

name

Only execute the scenarios with name matching the expression (repeatable).

Type: REGEXP[]
Default: []

require

Require files containing your step definitions before executing features. You can also specify a glob to your step definitions.

Type: String[]
Default: []
Example: [path.join(__dirname, 'step-definitions', 'my-steps.js')]

import

Paths to where your support code is, for ESM.

Type: String[]
Default: []
Example: [path.join(__dirname, 'step-definitions', 'my-steps.js')]

strict

Fail if there are any undefined or pending steps

Type: Boolean
Default: false

tags

Only execute the features or scenarios with tags matching the expression. Note that untagged features will still spawn a Selenium session (see issue webdriverio/webdriverio#1247). Please see the Cucumber documentation for more details. If passing as a command-line argument, compound expressions may need to be enclosed in three sets of double quotes if WebdriverIO is invoked using npx on Windows.

E.g.: npx wdio wdio.config.js --cucumberOpts.tags """@Smoke and not @Pending"""

Type: String
Default: ``

timeout

Timeout in milliseconds for step definitions.

Type: Number
Default: 30000

retry

Specify the number of times to retry failing test cases.

Type: Number
Default: 0

retryTagFilter

Only retries the features or scenarios with tags matching the expression (repeatable). This option requires '--retry' to be specified.

Type: RegExp

tagsInTitle

Add cucumber tags to feature or scenario name

Type: Boolean
Default: false

Please note that this is a @wdio/cucumber-framework specific option and not recognized by cucumber-js itself

ignoreUndefinedDefinitions

Treat undefined definitions as warnings.

Type: Boolean
Default: false

Please note that this is a @wdio/cucumber-framework specific option and not recognized by cucumber-js itself

failAmbiguousDefinitions

Treat ambiguous definitions as errors.

Type: Boolean
Default: false

Please note that this is a @wdio/cucumber-framework specific option and not recognized by cucumber-js itself

tagExpression

Only execute the features or scenarios with tags matching the expression. Note that untagged features will still spawn a Selenium session (see issue webdriverio/webdriverio#1247). Please see the Cucumber documentation for more details. If passing as a command-line argument, compound expressions may need to be enclosed in three sets of double quotes if WebdriverIO is invoked using npx on Windows.

E.g.: npx wdio wdio.config.js --cucumberOpts.tagExpression """@Smoke and not @Pending"""

Type: String
Default: ``

Please note that this option would be deprecated in future. Use tags config property instead

profile

Specify the profile to use.

Type: string[]
Default: []

Kindly take note that only specific values (worldParameters, name, retryTagFilter) are supported within profiles, as cucumberOpts takes precedence. Additionally, when using a profile, make sure that the mentioned values are not declared within cucumberOpts.

For more information on WebdriverIO see the homepage.