{"id":13823,"library":"protractor-cucumber-framework","title":"Protractor Cucumber Framework","description":"The `protractor-cucumber-framework` package provides the integration layer to run Cucumber.js tests within the Protractor end-to-end testing framework, primarily for Angular applications. Currently at version `9.19.0`, this framework is actively maintained to support recent versions of Cucumber.js (up to `v12.0.0`) and Serenity/JS (up to `v3.42.1`), even though Protractor itself has reached its official end-of-life. Originally bundled with `angular/protractor`, it was later extracted as a separate module to allow independent development and broader support for various Cucumber.js versions. A key differentiator is its deep integration with Serenity/JS, which enhances reporting capabilities beyond Cucumber.js-native reporters, offering rich, highly detailed BDD reports and living documentation. While the project ensures compatibility with a broad range of its peer dependencies, users should be aware that Protractor's deprecation means new projects are advised to migrate to modern alternatives like WebdriverIO or Playwright with Serenity/JS for continued test automation.","status":"deprecated","version":"9.19.0","language":"javascript","source_language":"en","source_url":"https://github.com/protractor-cucumber-framework/protractor-cucumber-framework","tags":["javascript","angular","test","testing","webdriver","webdriverjs","selenium","protractor","protractor-framework"],"install":[{"cmd":"npm install protractor-cucumber-framework","lang":"bash","label":"npm"},{"cmd":"yarn add protractor-cucumber-framework","lang":"bash","label":"yarn"},{"cmd":"pnpm add protractor-cucumber-framework","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for defining and executing BDD tests; supports various major versions.","package":"@cucumber/cucumber","optional":false},{"reason":"Older versions of Cucumber.js for backward compatibility.","package":"cucumber","optional":false},{"reason":"The core end-to-end testing framework this package extends.","package":"protractor","optional":false}],"imports":[{"note":"This package is a Protractor framework plugin; it's referenced in `protractor.conf.js` via `frameworkPath` rather than direct ES Module or CommonJS imports in application code.","wrong":"import { ProtractorCucumberFramework } from 'protractor-cucumber-framework'; // Direct JS import is not how framework is typically loaded","symbol":"Protractor Configuration","correct":"exports.config = {\n  framework: 'custom',\n  frameworkPath: require.resolve('protractor-cucumber-framework'),\n  // ... other config\n}"},{"note":"BDD keywords for step definitions are imported from `@cucumber/cucumber` (or `cucumber` for older versions), not `protractor-cucumber-framework` itself.","wrong":"import { Given, When, Then } from 'protractor-cucumber-framework'; // Core Cucumber BDD keywords are from @cucumber/cucumber or 'cucumber', not this framework directly.","symbol":"Cucumber Step Definitions","correct":"import { Given, When, Then } from '@cucumber/cucumber';\n// ..."},{"note":"To use TypeScript for step definitions, `ts-node/register` must be specified in `cucumberOpts.requireModule`, and feature files should reference `.ts` files.","wrong":"exports.config = {\n  // ...\n  cucumberOpts: {\n    require: ['features/step_definitions/**/*.steps.js'], // Will not transpile TypeScript files\n  },\n};","symbol":"TypeScript Integration","correct":"exports.config = {\n  // ...\n  cucumberOpts: {\n    require: [\n      'features/step_definitions/**/*.steps.ts',\n      'features/support/*.ts',\n    ],\n    requireModule: ['ts-node/register'],\n  },\n};"}],"quickstart":{"code":"/* protractor.conf.ts */\nimport * as path from 'path';\n\nexport const config: import('protractor').Config = {\n  directConnect: true,\n  // For testing Angular applications on a non-Angular site, set this to true.\n  // This will bypass Angular's readiness checks.\n  ignoreSynchronization: false,\n\n  framework: 'custom',\n  frameworkPath: require.resolve('protractor-cucumber-framework'),\n\n  specs: [\n    path.resolve('./e2e/features/**/*.feature')\n  ],\n\n  capabilities: {\n    browserName: 'chrome'\n  },\n\n  cucumberOpts: {\n    compiler: [],\n    require: [\n      path.resolve('./e2e/steps/**/*.steps.ts'),\n      path.resolve('./e2e/support/**/*.ts')\n    ],\n    format: 'json:./e2e/reports/cucumber-results.json',\n    tags: '',\n    profile: false,\n    'no-source': true,\n    colors: true,\n    requireModule: ['ts-node/register'],\n  },\n\n  onPrepare: () => {\n    // Ensure the browser instance is configured to wait for non-Angular elements as needed\n    browser.waitForAngularEnabled(true);\n  },\n};\n\n/* e2e/features/example.feature */\nFeature: Protractor Cucumber Example\n  As a user\n  I want to use Protractor with Cucumber\n  So that I can write BDD tests\n\n  Scenario: Basic navigation and title check\n    Given I open \"https://www.angularjs.org/\"\n    Then the title should be \"AngularJS — Superheroic JavaScript MVW Framework\"\n\n/* e2e/steps/example.steps.ts */\nimport { Given, Then } from '@cucumber/cucumber';\nimport { browser, expect } from 'protractor';\n\nGiven('I open {string}', async (url: string) => {\n  await browser.get(url);\n});\n\nThen('the title should be {string}', async (expectedTitle: string) => {\n  const actualTitle = await browser.getTitle();\n  await expect(actualTitle).toEqual(expectedTitle);\n});","lang":"typescript","description":"This quickstart demonstrates setting up `protractor-cucumber-framework` with TypeScript. It includes a `protractor.conf.ts` for configuration, an example Gherkin feature file, and corresponding TypeScript step definitions to navigate to a URL and verify its title. It showcases how to integrate `ts-node` for in-memory transpilation of TypeScript step files and configures Cucumber.js output."},"warnings":[{"fix":"Migrate your existing Protractor tests to a modern E2E testing framework like WebdriverIO or Playwright, potentially using Serenity/JS for a smoother transition.","message":"Protractor, the core framework `protractor-cucumber-framework` relies on, has reached its official end-of-life and is no longer actively developed or maintained by the Angular team. New projects should consider modern alternatives.","severity":"breaking","affected_versions":">=1.0.0 (applies to Protractor itself)"},{"fix":"Use `npm install` or `yarn install` and carefully address any peer dependency warnings. Consider using `npm install --legacy-peer-deps` for older setups if encountering stubborn dependency resolution issues, though this is not recommended long-term.","message":"Managing peer dependencies for `protractor`, `@cucumber/cucumber`, and `cucumber` can be challenging due to their wide version ranges and potential conflicts. Always check the `peerDependencies` in `package.json` for compatibility.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refactor all asynchronous test code (e.g., `browser.get()`, `element.click()`, `expect().to.eventually.equal()`) to explicitly use `async/await` syntax and ensure step definitions are marked `async`.","message":"Protractor v6.0.0 removed the control flow, requiring the use of `async/await` for all asynchronous operations in tests. Older tests written with the control flow will break.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Add `requireModule: ['ts-node/register']` to `cucumberOpts` and update `cucumberOpts.require` paths to use `**/*.ts` instead of `**/*.js`. Ensure `typescript` and `ts-node` are installed as dev dependencies.","message":"When using TypeScript for step definitions, you must correctly configure `cucumberOpts.requireModule` to include `ts-node/register` and ensure `cucumberOpts.require` points to `.ts` files. Failing to do so will result in `Cannot find module` or compilation errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `protractor-cucumber-framework` is at a compatible version (e.g., `3.1.2` or higher for Cucumber 3.x support) and update any custom plugins that relied on these removed Cucumber.js APIs.","message":"Cucumber.js versions 3.x introduced breaking changes by removing `registerHandler` and `registerListener`, impacting how `protractor-cucumber-framework` and other plugins integrated.","severity":"breaking","affected_versions":">=3.x of Cucumber.js"}],"env_vars":null,"search_vec":"'9.19.0':34 'activ':38 'advis':140 'allow':79 'altern':145 'angular':29,157 'angular/protractor':69 'applic':30 'autom':155 'awar':131 'bdd':110 'beyond':102 'broad':122 'broader':83 'bundl':67 'capabl':101 'compat':119 'continu':153 'cucumb':2,7 'cucumber.js':16,45,87,103 'current':31 'deep':94 'depend':127 'deprec':135 'detail':109 'develop':81 'differenti':91 'document':114 'end':22,24,63 'end-of-lif':62 'end-to-end':21 'enhanc':99 'ensur':118 'even':54 'extract':73 'framework':3,8,26,36,166 'high':108 'independ':80 'integr':12,95 'javascript':156 'key':90 'later':72 'layer':13 'life':65 'like':146 'live':113 'maintain':39 'mean':136 'migrat':142 'modern':144 'modul':77 'nativ':104 'new':137 'offer':106 'offici':61 'origin':66 'packag':9 'peer':126 'playwright':149 'primarili':27 'project':117,138 'protractor':1,6,20,56,133,163,165 'protractor-cucumber-framework':5 'protractor-framework':164 'provid':10 'rang':123 'reach':59 'recent':42 'report':100,105,111 'rich':107 'run':15 'selenium':162 'separ':76 'serenity/js':50,97,151 'support':41,84 'test':17,25,154,158,159 'though':55 'user':128 'v12.0.0':48 'v3.42.1':53 'various':86 'version':33,43,88 'webdriv':160 'webdriverio':147 'webdriverj':161 'within':18","created_at":"2026-04-20T01:56:29.683276+00:00","updated_at":"2026-04-20T01:56:29.683276+00:00","problems":[{"fix":"Ensure `protractor-cucumber-framework` is installed (`npm install --save-dev protractor-cucumber-framework`) and `frameworkPath` in `protractor.conf.js` uses `require.resolve('protractor-cucumber-framework')`.","cause":"The package is not installed, or `frameworkPath` is pointing to an incorrect location.","error":"Error: Cannot find module 'protractor-cucumber-framework'"},{"fix":"Verify that only `.feature` files are listed in the `specs` array in `protractor.conf.js`, and `.js` or `.ts` step definition files are listed in `cucumberOpts.require`.","cause":"Cucumber is trying to parse a step definition file as a feature file, usually because it's incorrectly listed in `specs` instead of `cucumberOpts.require`.","error":"Error: expected #EOF, #Language, #TagLine, #FeatureLine, #Comment, #Empty, got '<your step definition file content>'"},{"fix":"Ensure your step definitions are correctly defined and, if using `await`, the function is marked `async`. Also, check if Protractor's global variables are correctly exposed (which they usually are by default).","cause":"The `browser` global from Protractor is not available in the context where the step definition is being executed, often due to incorrect setup or missing `async` keyword for `await` calls.","error":"ReferenceError: browser is not defined"},{"fix":"Install the required Cucumber.js package: `npm install --save-dev @cucumber/cucumber` (or `cucumber` for older setups) to match the peer dependency range.","cause":"The `@cucumber/cucumber` peer dependency is missing or not correctly installed.","error":"Error: Cannot find module '@cucumber/cucumber'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/protractor-cucumber-framework/protractor-cucumber-framework","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/protractor-cucumber-framework","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}