{"id":14969310,"url":"https://github.com/protractor-cucumber-framework/protractor-cucumber-framework","last_synced_at":"2025-05-14T20:11:00.387Z","repository":{"id":2228934,"uuid":"46014834","full_name":"protractor-cucumber-framework/protractor-cucumber-framework","owner":"protractor-cucumber-framework","description":"Cucumber framework plugin for Protractor","archived":false,"fork":false,"pushed_at":"2025-03-29T16:23:06.000Z","size":3288,"stargazers_count":199,"open_issues_count":5,"forks_count":131,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-05-06T05:03:33.108Z","etag":null,"topics":["angular","cucumber","protractor","protractor-cucumber-framework"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/protractor-cucumber-framework.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-11-11T22:50:55.000Z","updated_at":"2025-03-29T16:43:51.000Z","dependencies_parsed_at":"2023-07-05T16:15:33.921Z","dependency_job_id":"c3570978-2e44-435b-a742-1df0f13f1ba4","html_url":"https://github.com/protractor-cucumber-framework/protractor-cucumber-framework","commit_stats":{"total_commits":193,"total_committers":26,"mean_commits":7.423076923076923,"dds":0.6373056994818653,"last_synced_commit":"d00536aea7d6e5befc3f1c64a1948c595c002091"},"previous_names":[],"tags_count":118,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/protractor-cucumber-framework%2Fprotractor-cucumber-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/protractor-cucumber-framework%2Fprotractor-cucumber-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/protractor-cucumber-framework%2Fprotractor-cucumber-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/protractor-cucumber-framework%2Fprotractor-cucumber-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/protractor-cucumber-framework","download_url":"https://codeload.github.com/protractor-cucumber-framework/protractor-cucumber-framework/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253347070,"owners_count":21894281,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","cucumber","protractor","protractor-cucumber-framework"],"created_at":"2024-09-24T13:41:35.228Z","updated_at":"2025-05-14T20:11:00.367Z","avatar_url":"https://github.com/protractor-cucumber-framework.png","language":"JavaScript","readme":"# Protractor Cucumber Framework\n\n[![Follow Serenity/JS on LinkedIn](https://img.shields.io/badge/Follow-Serenity%2FJS%20-0077B5?logo=linkedin)](https://www.linkedin.com/company/serenity-js)\n[![Watch Serenity/JS on YouTube](https://img.shields.io/badge/Watch-@serenity--js-E62117?logo=youtube)](https://www.youtube.com/@serenity-js)\n[![Join Serenity/JS Community Chat](https://img.shields.io/badge/Chat-Serenity%2FJS%20Community-FBD30B?logo=matrix)](https://matrix.to/#/#serenity-js:gitter.im)\n[![Support Serenity/JS on GitHub](https://img.shields.io/badge/Support-@serenity--js-703EC8?logo=github)](https://github.com/sponsors/serenity-js)\n\n[![NPM Version](https://badge.fury.io/js/protractor-cucumber-framework.svg)](https://badge.fury.io/js/protractor-cucumber-framework)\n[![Known Vulnerabilities](https://snyk.io/test/github/protractor-cucumber-framework/protractor-cucumber-framework/badge.svg)](https://snyk.io/test/github/protractor-cucumber-framework/protractor-cucumber-framework)\n![download-count](https://img.shields.io/npm/dm/protractor-cucumber-framework.svg)\n[![open-issues](https://img.shields.io/github/issues/protractor-cucumber-framework/protractor-cucumber-framework.svg)](https://github.com/protractor-cucumber-framework/protractor-cucumber-framework/issues)\n[![contributors](https://img.shields.io/github/contributors/protractor-cucumber-framework/protractor-cucumber-framework.svg)](https://github.com/protractor-cucumber-framework/protractor-cucumber-framework/graphs/contributors)\n\n[![Build Status](https://github.com/protractor-cucumber-framework/protractor-cucumber-framework/workflows/build/badge.svg)](https://github.com/protractor-cucumber-framework/protractor-cucumber-framework/actions)\n[![Libraries.io dependency status for latest release, scoped npm package](https://img.shields.io/librariesio/release/npm/protractor-cucumber-framework)](https://libraries.io/npm/protractor-cucumber-framework)\n[![Serenity/JS on StackOverflow](https://img.shields.io/badge/stackoverflow-serenity--js-important?logo=stackoverflow)](https://stackoverflow.com/questions/tagged/serenity-js)\n\nThis framework was originally part of [angular/protractor](https://github.com/angular/protractor) and\nis now a separate module to decouple [cucumber.js](https://github.com/cucumber/cucumber-js).\n\nThe project relies on [Serenity/JS](https://serenity-js.org) to enable integration between **Protractor** and **Cucumber\n1.x - 11.x** and offer support for both [Cucumber.js-native](https://cucumber.io/docs/cucumber/reporting/)\nand [Serenity/JS reporters](https://serenity-js.org/handbook/reporting/).\n\nTo see Serenity/JS reports in action, check out\nthe [reference implementation](https://github.com/serenity-js/protractor-cucumber-framework-demo) and\nthe [Serenity BDD reports](https://serenity-js.github.io/protractor-cucumber-framework-demo/) it produces.\n\nLearn more:\n\n- [Serenity/JS website](https://serenity-js.org)\n- [Reference implementation](https://github.com/serenity-js/protractor-cucumber-framework-demo)\n  with [Serenity BDD reports](https://serenity-js.github.io/protractor-cucumber-framework-demo/)\n- [Cucumber.js docs](https://github.com/cucumber/cucumber-js)\n- [Protractor docs](https://www.protractortest.org/#/)\n- [Gherkin reference](https://cucumber.io/docs/gherkin/reference/)\n\n\u003e ### 📣 **Protractor has reached its end-of-life, migrate your tests to Serenity/JS** 💡\n\u003e\n\u003e [Serenity/JS](https://serenity-js.org) offers a smooth transition for your Protractor tests, allowing you to migrate\n\u003e them gradually to WebdriverIO or Playwright while ensuring your test suite continues to work.\n\u003e \n\u003e Learn more about [migrating from Protractor to Serenity/JS](https://serenity-js.org/handbook/getting-started/serenity-js-with-protractor/?pk_campaign=protractor_migration\u0026pk_source=protractor-cucumber-framework#migrating-from-protractor-to-serenityjs)\n\u003e and [chat with the Serenity/JS community](https://matrix.to/#/#serenity-js:gitter.im) if you have any questions about the migration.\n\n## Installation\n\nTo install this module, run the following command in your computer terminal:\n\n```\nnpm install --save-dev protractor-cucumber-framework\n```\n\nPlease note that to use `protractor-cucumber-framework` you'll need a recent [Long-Term Support](https://nodejs.org/en/about/releases/) versions of Node.js, so **16**, **18**, or **20**.\n\nOdd-numbered Node.js releases (17, 19, 21, etc.) are not on the LTS line, should be considered experimental, and should\nnot be used in production.\n\n## Upgrading from previous versions and backward compatibility\n\n`protractor-cucumber-framework` is a thin wrapper around\n[`@serenity-js/cucumber`](https://www.npmjs.com/package/@serenity-js/cucumber) and [`@serenity-js/protractor`](https://www.npmjs.com/package/@serenity-js/protractor) modules.\n\nJust like Serenity/JS, this module:\n- supports **all the major versions** of Cucumber.js,\n- supports both Protractor v5 and v7,\n- is backward compatible with previous major versions of `protractor-cucumber-framework`.\n\nTo stay up to date with the latest features, patches, and security fixes make sure to **always use the latest version** of `protractor-cucumber-framework` as this module offers **backward compatibility** with other dependencies, like  [`cucumber`](https://www.npmjs.com/package/cucumber), [`@cucumber/cucumber`](https://www.npmjs.com/package/@cucumber/cucumber), or [`protractor`](https://www.npmjs.com/package/protractor).\n\n## Configuration\n\nTo use `protractor-cucumber-framework`, configure it as a `custom` framework\nin your `protractor.conf.js`:\n\n```js\nexports.config = {\n    // set to \"custom\" instead of cucumber.\n    framework: 'custom',\n\n    // path relative to the current config file\n    frameworkPath: require.resolve('protractor-cucumber-framework'),\n\n    // require feature files\n    specs: [\n        'path/to/feature/files/**/*.feature' // accepts a glob\n    ],\n\n    cucumberOpts: {\n        // require step definitions\n        require: [\n            'features/step_definitions/**/*.steps.js', // accepts a glob\n            'features/support/*.ts',\n        ]\n    }\n};\n```\n\n### Using TypeScript\n\nCucumber step definitions can be implemented in [TypeScript](https://www.typescriptlang.org/) and transpiled in memory\nto JavaScript via [`ts-node`](https://github.com/TypeStrong/ts-node).\n\nTo use TypeScript, install the following dependencies:\n\n```\nnpm install --save-dev typescript ts-node @types/node\n```\n\nNext, create a [`tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) file in the root\ndirectory of your project:\n\n```json\n{\n  \"compilerOptions\": {\n    \"target\": \"ES2019\",\n    \"lib\": [\n      \"ES2019\"\n    ],\n    \"module\": \"commonjs\",\n    \"moduleResolution\": \"node\",\n    \"sourceMap\": true,\n    \"declaration\": false\n  },\n  \"include\": [\n    \"features/**/*.ts\"\n  ],\n  \"exclude\": [\n    \"node_modules\"\n  ]\n}\n```\n\nFinally, set the `cucumberOpts.requireModule` option in `protractor.conf.js` to `ts-node/register`\nand configure Cucumber to load `.ts` files instead of `.js`:\n\n```js\nexports.config = {\n    framework: 'custom',\n    frameworkPath: require.resolve('protractor-cucumber-framework'),\n\n    specs: [\n        'features/**/*.feature'\n    ],\n\n    cucumberOpts: {\n        require: [\n            'features/step_definitions/**/*.steps.ts',  // *.ts instead of *.js\n            'features/support/*.ts',\n        ],\n        requireModule: [\n            'ts-node/register'  // use ts-node to transpile TypeScript in memory\n        ],\n    },\n};\n```\n\nYou can now implement Cucumber step definitions in TypeScript, for example:\n\n```typescript\n// features/step_definitions/example.steps.ts\nimport { When, Then } from '@cucumber/cucumber'\n\nWhen('developers like type safety', () =\u003e {\n    \n});\n\nThen('they should use TypeScript', () =\u003e {\n\n});\n```\n\n## Using Serenity/JS directly\n\nSince `protractor-cucumber-framework` is just a thin wrapper around Serenity/JS modules,\nyou can depend on them directly to make sure you always get the latest and greatest features.\n\nTo configure your project to use Serenity/JS, remove the dependency on `protractor-cucumber-framework` and install the following dependencies instead:\n\n```\nnpm install --save-dev @serenity-js/{core,cucumber,web,protractor}\n```\n\nNext, configure your `protractor.conf.js` file as follows:\n\n```js\nexports.config = {\n    framework:      'custom',\n    frameworkPath:  require.resolve('@serenity-js/protractor/adapter'),\n\n    serenity: {\n        runner: 'cucumber',\n        crew: [\n            // Serenity/JS reporting services\n        ]\n    },\n\n    cucumberOpts: {\n        // Cucumber config\n    }\n    \n    // other Protractor config\n};\n```\n\n### Using Serenity/JS reporting services\n\nTo use [Serenity/JS reporting services](https://serenity-js.org/handbook/reporting/index.html), configure your project to depend on Serenity/JS directly as per the previous section to make sure that your Serenity/JS dependencies are up-to-date and compatible. \n\n#### Using Serenity/JS console reporter\n\nTo use [Serenity/JS console reporter](https://serenity-js.org/handbook/reporting/console-reporter.html), install the following dependencies:\n```\nnpm install --save-dev @serenity-js/{core,cucumber,web,protractor,console-reporter}\n```\n\nNext, configure your `protractor.conf.js` as follows:\n\n```js\nconst { ConsoleReporter } = require('@serenity-js/console-reporter');\n\nexports.config = {\n    framework:      'custom',\n    frameworkPath:  require.resolve('@serenity-js/protractor/adapter'),\n\n    specs: [ 'features/**/*.feature' ],\n\n    serenity: {\n        runner: 'cucumber',\n        crew: [\n            ConsoleReporter.forDarkTerminals(),\n        ]\n    },\n    \n    // other config\n};\n```\n\n#### Using Serenity BDD reporter\n\nTo use the [Serenity BDD reporter](https://serenity-js.org/handbook/reporting/serenity-bdd-reporter.html), install the following dependencies:\n\n```\nnpm install --save-dev @serenity-js/{core,cucumber,web,protractor,serenity-bdd} npm-failsafe rimraf\n```\n\nNext, configure your `protractor.conf.js` as follows:\n\n```js\nconst\n    { ArtifactArchiver } = require('@serenity-js/core'),\n    { SerenityBDDReporter } = require('@serenity-js/serenity-bdd');\n\nexports.config = {\n    framework:      'custom',\n    frameworkPath:  require.resolve('@serenity-js/protractor/adapter'),\n\n    serenity: {\n        runner: 'cucumber',\n        crew: [\n            ArtifactArchiver.storingArtifactsAt('./target/site/serenity'),\n            new SerenityBDDReporter(),\n        ]\n    },\n\n    // other config\n};\n```\n\nTo automatically download the Serenity BDD reporter CLI when you install your Node modules, add the following [`postinstall` script](https://docs.npmjs.com/cli/v9/using-npm/scripts) to your `package.json` file:\n\n```json\n{\n  \"scripts\": {\n    \"postinstall\": \"serenity-bdd update\",\n  } \n}\n```\nTo generate Serenity BDD reports when you run your tests, configure your `test` script to invoke `serenity-bdd run` when your tests are finished:\n\n\n```json\n{\n    \"scripts\": {\n        \"postinstall\": \"serenity-bdd update\",\n        \"clean\": \"rimraf target\",\n        \"test\": \"failsafe clean test:execute test:report\",\n        \"test:execute\": \"protractor ./protractor.conf.js\",\n        \"test:report\": \"serenity-bdd run --features ./features\"\n    }\n}\n```\n\n### Configuring Cucumber\n\nAll of the `cucumberOpts` will be passed to `cucumberjs` as arguments.\n\nFor example, to call Cucumber with the `--strict` flag and to specify custom formatters:\n\n```js\nexports.config = {\n    framework: 'custom',\n    frameworkPath: require.resolve('@serenity-js/protractor/adapter'),\n\n    specs: [\n        'features/**/*.feature'\n    ],\n    \n    cucumberOpts: {\n        strict: true,\n        format: [\n            'progress', \n            'pretty:output.txt'\n        ],\n        // ...\n    }\n}\n```\n\nThe following parameters have special behaviour:\n\n* `require` - globs will be expanded to multiple `--require` arguments\n* `rerun` - value is passed as an argument; for use with\n  the [rerun feature](https://github.com/cucumber/cucumber-js/blob/master/features/rerun_formatter.feature)\n\n#### Formatters when tests are sharded or with multi capabilities\n\nIf you have a formatter that outputs to a path and your tests are sharded or you have multi\ncapabilities then this library will add the PID to the path to make them unique. The reason for\nthis is multiple processes can write to the same path which ends up clobbering each other.\nYou'll end up with 1 file per process that protractor spawns.\n\n```js\nexports.config = {\n    capabilities: {\n        shardTestFiles: true,\n        // ...\n    },\n\n    cucumberOpts: {\n        format: 'json:results.json',\n        // ...\n    }\n};\n```\n\nIf there were 2 feature files then you can expect the following output files...\n\n```\n  results.11111.json\n  results.22222.json\n```\n\n...where the numbers will be the actual PIDs.\n\n#### Uncaught Exceptions\n\nIf your process abruptly stops with an exit code `199` then your steps most likely threw an uncaught\nexception. Protractor is capturing these and exiting the process in this situation. The solution is\nto upgrade to at least protractor version 7.0.0 and add the following to your protractor conf...\n\n```\n  ignoreUncaughtExceptions: true\n```\n\nThis allows cucumber to handle the exception and record it appropriately.\n\nContributing\n------------\n\nPull requests are welcome. Commits should be generated using `npm run commit` command.\n\nFor Contributors\n----------------\nEnsure that the following dependencies are installed:\n\n* Java Runtime Environment (JRE) 8 or newer\n* Node.js LTS\n* Google Chrome\n\nClone the github repository:\n\n```\ngit clone https://github.com/protractor-cucumber-framework/protractor-cucumber-framework\ncd protractor-cucumber-framework\nnpm install\n```\n\n#### Testing\n\n```\nnpm test\n```\n\n## Your feedback matters!\n\nDo you find Serenity/JS useful? Give it a ⭐ star on GitHub and rate it on Openbase!\n\n[![GitHub stars](https://img.shields.io/github/stars/serenity-js/serenity-js)](https://github.com/serenity-js/serenity-js) [![Rate on Openbase](https://badges.openbase.io/js/rating/@serenity-js/core.svg)](https://openbase.io/js/@serenity-js/core?utm_source=embedded\u0026utm_medium=badge\u0026utm_campaign=rate-badge)\n\nFound a bug? Need a feature? Raise [an issue](https://github.com/serenity-js/serenity-js/issues?state=open)\nor submit a pull request.\n\nHave feedback? Let me know on [LinkedIn](https://www.linkedin.com/in/janmolak/) or leave a comment in [Serenity/JS discussions on GitHub](/serenity-js/serenity-js/discussions/categories/comments)\n\nIf you'd like to chat with fellow users of Serenity/JS, join us on [Serenity/JS Community Chat](https://matrix.to/#/#serenity-js:gitter.im).\n\n## Support Serenity/JS\n\nSerenity/JS is a free open-source framework, so we rely on our [wonderful GitHub sponsors](https://github.com/sponsors/serenity-js) to keep the lights on.\n\nIf you appreciate all the effort that goes into making sophisticated tools easy to work with, please support our work and become a Serenity/JS GitHub Sponsor today!\n\n[![GitHub Sponsors](https://img.shields.io/badge/Support%20@serenity%2FJS-703EC8?style=for-the-badge\u0026logo=github\u0026logoColor=white)](https://github.com/sponsors/serenity-js)\n","funding_links":["https://github.com/sponsors/serenity-js"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprotractor-cucumber-framework%2Fprotractor-cucumber-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprotractor-cucumber-framework%2Fprotractor-cucumber-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprotractor-cucumber-framework%2Fprotractor-cucumber-framework/lists"}