CodeceptJS Cucumber BDD Framework

5.0.0 · active · verified Sun Apr 19

codeceptjs-cucumber is an E2E testing framework that integrates CodeceptJS with Cucumber, enabling Behavior-Driven Development (BDD) workflows. It facilitates running tests across multiple browsers and offers out-of-the-box integration for Sauce Labs, allowing for efficient parallel test execution in the cloud. The current stable version is 5.0.0, released in late 2023. This package typically follows a major release cadence of approximately one to two years, aligning with updates in its core dependencies like CodeceptJS and Cucumber. It leverages the Should.js assertion library by default. As an opinionated framework, its key differentiator lies in simplifying the setup and configuration required to combine these powerful testing tools, particularly for complex cloud-based, cross-browser test automation scenarios, reducing the boilerplate often associated with such integrations.

Common errors

```
TypeError: I.amOnPage is not a function
```
cause The CodeceptJS helper (e.g., Playwright, WebDriver) is not correctly initialized or the `I` object is not properly injected into your step definitions.

fix Ensure your `codecept.conf.js` has a helper defined (e.g., `Playwright` in the `helpers` section) and that `I` is correctly imported via `const { I } = inject();` in your steps file. Also, verify that `include.I` is set in the `codecept.conf.js`.
```
Undefined step: I am on the Google homepage
```
cause Cucumber cannot find a matching step definition for a Gherkin step defined in your feature file.

fix Verify that your step definition files are correctly linked in `codecept.conf.js` (check `gherkin.steps` and `Cucumber.require` paths). Ensure the regular expression in your step definition exactly matches the Gherkin step text.
```
Error: Cannot find module '@cucumber/cucumber'
```
cause The `@cucumber/cucumber` package is either not installed, or Node.js cannot resolve its path.

fix Run `npm install @cucumber/cucumber` or `yarn add @cucumber/cucumber`. Check your `package.json` for the correct dependency and ensure your `node_modules` directory is up-to-date.
```
Error: Cannot find module 'codeceptjs'
```
cause The `codeceptjs` package is not installed or incorrectly resolved by your system.

fix Run `npm install codeceptjs` or `yarn add codeceptjs`. Confirm it's listed in your `package.json` and `node_modules`.

Warnings

breaking codeceptjs-cucumber v4.0.0 introduced breaking changes by upgrading to CodeceptJS v3 and Cucumber v8. Subsequent versions, including v5.0.0, continue to rely on these newer versions and `@cucumber/cucumber` v10. This requires updates to helper configurations, step definition syntaxes, and potentially project structure.
Fix: Review the official CodeceptJS v3 and Cucumber v8/v10 migration guides. Update `codecept.conf.js` to match the new helper and plugin syntax. Adjust step definitions for any Cucumber API changes. Ensure `@cucumber/cucumber` is at version 8 or higher, and `codeceptjs` is at version 3 or higher.
gotcha Parallel execution with Sauce Labs requires specific configurations in `codecept.conf.js`, including setting up `sauceConnect: true` and defining appropriate capabilities. Incorrect setup will lead to tests running locally or failing to connect to Sauce Labs, often without clear error messages.
Fix: Refer to the `codeceptjs-cucumber` documentation for Sauce Labs integration details. Ensure Sauce Connect Proxy is running if required, and the Sauce Labs helper is correctly configured with valid credentials and desired browser capabilities in `codecept.conf.js`.
gotcha Misconfigured `gherkin.steps` or `Cucumber.require` paths in `codecept.conf.js` will result in 'Undefined step' errors during test execution, even if step definitions exist.
Fix: Double-check that the paths specified in `gherkin.steps` (for CodeceptJS's internal Gherkin plugin) and `Cucumber.require` (for the Cucumber helper) accurately point to your step definition files/directories. Ensure glob patterns (e.g., `./step_definitions/**/*.js`) are correct.
deprecated Older versions of Cucumber (below v8) are deprecated and no longer fully compatible with `codeceptjs-cucumber` v4 and v5. Using an outdated Cucumber version can lead to unexpected behavior, API mismatches, or missing features.
Fix: Upgrade your `@cucumber/cucumber` package to version 8 or newer (e.g., `@cucumber/cucumber: ^10.0.0`) and adjust your step definitions if any API changes are required from Cucumber's side.

Install

npm install codeceptjs-cucumber npm
yarn add codeceptjs-cucumber yarn
pnpm add codeceptjs-cucumber pnpm

Imports

Cucumber Helper Configuration
wrong:
```
    CucumberHelper: { /* ... */ } // Incorrect helper name
    // Missing Cucumber helper configuration in helpers section
```
correct:
```
    Cucumber: {
      require: './step_definitions',
      features: './features/*.feature'
    }
```
This package is primarily consumed as a CodeceptJS helper, configured within `codecept.conf.js` under the `helpers` section, rather than via direct ES module `import` statements. The 'symbol' here refers to the configuration entry that enables the Cucumber integration.
Step Definition File Path Configuration
wrong:
```
      require: './steps.js' // Pointing directly to a file instead of a directory
      // require: './features' // Incorrect path for step definitions
```
correct:
```
      require: './step_definitions'
```
The `require` property within the `Cucumber` helper configuration specifies the directory (or an array of directories) where Cucumber should find your step definition files. It expects a path to a directory, not a single file.
Feature File Path Configuration
wrong:
```
      features: './feature.feature' // Only points to one file, misses glob pattern
      // features: './steps' // Incorrect path for feature files
```
correct:
```
      features: './features/*.feature'
```
The `features` property within the `Cucumber` helper configuration defines the location of your Gherkin feature files. It commonly uses a glob pattern to include all feature files within specified directories.

Quickstart

This quickstart sets up a basic CodeceptJS-Cucumber project to perform a Google search. It demonstrates the `package.json` for dependencies, `codecept.conf.js` to configure the Playwright helper and the Cucumber integration, a Gherkin `.feature` file defining a search scenario, and corresponding JavaScript step definitions. Execute tests using `npm test`.

/* package.json */
{
  "name": "codeceptjs-cucumber-example",
  "version": "1.0.0",
  "description": "Example usage of codeceptjs-cucumber",
  "scripts": {
    "test": "codeceptjs run --steps"
  },
  "devDependencies": {
    "codeceptjs": "^3.0.0",
    "@cucumber/cucumber": "^10.0.0",
    "codeceptjs-cucumber": "^5.0.0",
    "playwright": "^1.0.0",
    "should": "^13.0.0"
  }
}

/* codecept.conf.js */
const { setWorldConstructor } = require('@cucumber/cucumber');

exports.config = {
  output: './output',
  helpers: {
    Playwright: {
      url: 'https://www.google.com',
      show: true,
      browser: 'chromium'
    },
    Cucumber: {
      require: './step_definitions',
      features: './features/*.feature'
    }
  },
  include: {
    I: './steps_file.js'
  },
  gherkin: {
    features: './features/*.feature',
    steps: ['./step_definitions/steps.js']
  },
  plugins: {
    allure: {
      enabled: true
    },
    retryFailedStep: {
      enabled: true
    },
    screenshotOnFail: {
      enabled: true
    }
  },
  bootstrap: null,
  teardown: null,
  mocha: {},
  name: 'codeceptjs-cucumber-example'
};

/* features/search.feature */
Feature: Google Search Functionality
  As a user, I want to search on Google
  So that I can find information

  Scenario: Search for a specific term
    Given I am on the Google homepage
    When I search for "CodeceptJS Cucumber"
    Then I should see "CodeceptJS Cucumber" in the search results

/* step_definitions/steps.js */
const { I } = inject();
const { Given, When, Then } = require('@cucumber/cucumber');

Given('I am on the Google homepage', () => {
  I.amOnPage('/');
});

When('I search for "{string}"', async (searchTerm) => {
  I.fillField('textarea[name="q"]', searchTerm);
  I.pressKey('Enter');
});

Then('I should see "{string}" in the search results', async (expectedText) => {
  I.see(expectedText);
});

view raw JSON →