{"id":14495,"library":"codeceptjs-cucumber","title":"CodeceptJS Cucumber BDD Framework","description":"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.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/gkushang/codeceptjs-bdd","tags":["javascript","Cucumber","CodeceptJS","Gherkin"],"install":[{"cmd":"npm install codeceptjs-cucumber","lang":"bash","label":"npm"},{"cmd":"yarn add codeceptjs-cucumber","lang":"bash","label":"yarn"},{"cmd":"pnpm add codeceptjs-cucumber","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core E2E testing framework that codeceptjs-cucumber extends and integrates with.","package":"codeceptjs","optional":false},{"reason":"The BDD framework integrated for Gherkin parsing and step execution.","package":"@cucumber/cucumber","optional":false},{"reason":"Default assertion library used within step definitions.","package":"should","optional":false},{"reason":"Optional dependency for integrating with Sauce Labs for cloud-based parallel testing.","package":"saucelabs","optional":true}],"imports":[{"note":"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.","wrong":"    CucumberHelper: { /* ... */ } // Incorrect helper name\n    // Missing Cucumber helper configuration in helpers section","symbol":"Cucumber Helper Configuration","correct":"    Cucumber: {\n      require: './step_definitions',\n      features: './features/*.feature'\n    }"},{"note":"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.","wrong":"      require: './steps.js' // Pointing directly to a file instead of a directory\n      // require: './features' // Incorrect path for step definitions","symbol":"Step Definition File Path Configuration","correct":"      require: './step_definitions'"},{"note":"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.","wrong":"      features: './feature.feature' // Only points to one file, misses glob pattern\n      // features: './steps' // Incorrect path for feature files","symbol":"Feature File Path Configuration","correct":"      features: './features/*.feature'"}],"quickstart":{"code":"/* package.json */\n{\n  \"name\": \"codeceptjs-cucumber-example\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Example usage of codeceptjs-cucumber\",\n  \"scripts\": {\n    \"test\": \"codeceptjs run --steps\"\n  },\n  \"devDependencies\": {\n    \"codeceptjs\": \"^3.0.0\",\n    \"@cucumber/cucumber\": \"^10.0.0\",\n    \"codeceptjs-cucumber\": \"^5.0.0\",\n    \"playwright\": \"^1.0.0\",\n    \"should\": \"^13.0.0\"\n  }\n}\n\n/* codecept.conf.js */\nconst { setWorldConstructor } = require('@cucumber/cucumber');\n\nexports.config = {\n  output: './output',\n  helpers: {\n    Playwright: {\n      url: 'https://www.google.com',\n      show: true,\n      browser: 'chromium'\n    },\n    Cucumber: {\n      require: './step_definitions',\n      features: './features/*.feature'\n    }\n  },\n  include: {\n    I: './steps_file.js'\n  },\n  gherkin: {\n    features: './features/*.feature',\n    steps: ['./step_definitions/steps.js']\n  },\n  plugins: {\n    allure: {\n      enabled: true\n    },\n    retryFailedStep: {\n      enabled: true\n    },\n    screenshotOnFail: {\n      enabled: true\n    }\n  },\n  bootstrap: null,\n  teardown: null,\n  mocha: {},\n  name: 'codeceptjs-cucumber-example'\n};\n\n/* features/search.feature */\nFeature: Google Search Functionality\n  As a user, I want to search on Google\n  So that I can find information\n\n  Scenario: Search for a specific term\n    Given I am on the Google homepage\n    When I search for \"CodeceptJS Cucumber\"\n    Then I should see \"CodeceptJS Cucumber\" in the search results\n\n/* step_definitions/steps.js */\nconst { I } = inject();\nconst { Given, When, Then } = require('@cucumber/cucumber');\n\nGiven('I am on the Google homepage', () => {\n  I.amOnPage('/');\n});\n\nWhen('I search for \"{string}\"', async (searchTerm) => {\n  I.fillField('textarea[name=\"q\"]', searchTerm);\n  I.pressKey('Enter');\n});\n\nThen('I should see \"{string}\" in the search results', async (expectedText) => {\n  I.see(expectedText);\n});","lang":"javascript","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<4.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"The CodeceptJS helper (e.g., Playwright, WebDriver) is not correctly initialized or the `I` object is not properly injected into your step definitions.","error":"TypeError: I.amOnPage is not a function"},{"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.","cause":"Cucumber cannot find a matching step definition for a Gherkin step defined in your feature file.","error":"Undefined step: I am on the Google homepage"},{"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.","cause":"The `@cucumber/cucumber` package is either not installed, or Node.js cannot resolve its path.","error":"Error: Cannot find module '@cucumber/cucumber'"},{"fix":"Run `npm install codeceptjs` or `yarn add codeceptjs`. Confirm it's listed in your `package.json` and `node_modules`.","cause":"The `codeceptjs` package is not installed or incorrectly resolved by your system.","error":"Error: Cannot find module 'codeceptjs'"}],"ecosystem":"npm"}