Registry /
testing / protractor-cucumber-framework
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Protractor Configuration
✓ exports.config = {
framework: 'custom',
frameworkPath: require.resolve('protractor-cucumber-framework'),
// ... other config
}
✗ import { ProtractorCucumberFramework } from 'protractor-cucumber-framework'; // Direct JS import is not how framework is typically loaded
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.
Cucumber Step Definitions
✓ import { Given, When, Then } from '@cucumber/cucumber';
// ...
✗ import { Given, When, Then } from 'protractor-cucumber-framework'; // Core Cucumber BDD keywords are from @cucumber/cucumber or 'cucumber', not this framework directly.
BDD keywords for step definitions are imported from `@cucumber/cucumber` (or `cucumber` for older versions), not `protractor-cucumber-framework` itself.
TypeScript Integration
✓ exports.config = {
// ...
cucumberOpts: {
require: [
'features/step_definitions/**/*.steps.ts',
'features/support/*.ts',
],
requireModule: ['ts-node/register'],
},
};
✗ exports.config = {
// ...
cucumberOpts: {
require: ['features/step_definitions/**/*.steps.js'], // Will not transpile TypeScript files
},
};
To use TypeScript for step definitions, `ts-node/register` must be specified in `cucumberOpts.requireModule`, and feature files should reference `.ts` files.
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.
/* protractor.conf.ts */
import * as path from 'path';
export const config: import('protractor').Config = {
directConnect: true,
// For testing Angular applications on a non-Angular site, set this to true.
// This will bypass Angular's readiness checks.
ignoreSynchronization: false,
framework: 'custom',
frameworkPath: require.resolve('protractor-cucumber-framework'),
specs: [
path.resolve('./e2e/features/**/*.feature')
],
capabilities: {
browserName: 'chrome'
},
cucumberOpts: {
compiler: [],
require: [
path.resolve('./e2e/steps/**/*.steps.ts'),
path.resolve('./e2e/support/**/*.ts')
],
format: 'json:./e2e/reports/cucumber-results.json',
tags: '',
profile: false,
'no-source': true,
colors: true,
requireModule: ['ts-node/register'],
},
onPrepare: () => {
// Ensure the browser instance is configured to wait for non-Angular elements as needed
browser.waitForAngularEnabled(true);
},
};
/* e2e/features/example.feature */
Feature: Protractor Cucumber Example
As a user
I want to use Protractor with Cucumber
So that I can write BDD tests
Scenario: Basic navigation and title check
Given I open "https://www.angularjs.org/"
Then the title should be "AngularJS — Superheroic JavaScript MVW Framework"
/* e2e/steps/example.steps.ts */
import { Given, Then } from '@cucumber/cucumber';
import { browser, expect } from 'protractor';
Given('I open {string}', async (url: string) => {
await browser.get(url);
});
Then('the title should be {string}', async (expectedTitle: string) => {
const actualTitle = await browser.getTitle();
await expect(actualTitle).toEqual(expectedTitle);
});
Debug
Known issues
breakingProtractor, 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.fixMigrate your existing Protractor tests to a modern E2E testing framework like WebdriverIO or Playwright, potentially using Serenity/JS for a smoother transition.
affects: >=1.0.0 (applies to Protractor itself)
gotchaManaging 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.fixUse `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.
affects: >=1.0.0
breakingProtractor 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.fixRefactor 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`.
affects: >=6.0.0
gotchaWhen 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.fixAdd `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.
affects: >=1.0.0
breakingCucumber.js versions 3.x introduced breaking changes by removing `registerHandler` and `registerListener`, impacting how `protractor-cucumber-framework` and other plugins integrated.fixEnsure `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.
affects: >=3.x of Cucumber.js
Errors
Common errors & fixes
Error: Cannot find module 'protractor-cucumber-framework'
The package is not installed, or `frameworkPath` is pointing to an incorrect location.
fixEnsure `protractor-cucumber-framework` is installed (`npm install --save-dev protractor-cucumber-framework`) and `frameworkPath` in `protractor.conf.js` uses `require.resolve('protractor-cucumber-framework')`. Error: expected #EOF, #Language, #TagLine, #FeatureLine, #Comment, #Empty, got '<your step definition file content>'
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`.
fixVerify 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`.
ReferenceError: browser is not defined
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.
fixEnsure 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).
Error: Cannot find module '@cucumber/cucumber'
The `@cucumber/cucumber` peer dependency is missing or not correctly installed.
fixInstall the required Cucumber.js package: `npm install --save-dev @cucumber/cucumber` (or `cucumber` for older setups) to match the peer dependency range.
Audit
Dependencies
@cucumber/cucumberrequiredRequired for defining and executing BDD tests; supports various major versions.
cucumberrequiredOlder versions of Cucumber.js for backward compatibility.
protractorrequiredThe core end-to-end testing framework this package extends.