@gnuechtel/nx-cucumber 1.4.1 → 2.0.0-13776525992

package/README.md

@@ -5,8 +5,8 @@ Plugin to use Cucumber within Nx workspaces
 <!-- TOC -->
 
 - [Introduction](#introduction)
+- [What changed in 2.x](#what-changed-in-2x)
 - [Prerequisites](#prerequisites)
-- [Cucumber JavaScript API](#cucumber-javascript-api)
 - [Quick start](#quick-start)
 - [Install Nx](#install-nx)
 - [Install dependencies](#install-dependencies)
@@ -14,17 +14,19 @@ Plugin to use Cucumber within Nx workspaces
   - [Basic project generator usage](#basic-project-generator-usage)
   - [Additional project generator options](#additional-project-generator-options)
 - [Execute Cucumber projects](#execute-cucumber-projects)
-  - [Basic executor usage](#basic-executor-usage)
-  - [Additional executor options](#additional-executor-options)
-  - [Custom Cucumber configuration](#custom-cucumber-configuration)
-  - [Custom Playwright configuration](#custom-playwright-configuration)
-  - [Multiple dev server targets](#multiple-dev-server-targets)
-  - [Skip dev server](#skip-dev-server)
+  - [Inferred tasks](#inferred-tasks)
+  - [Plugin registration](#plugin-registration)
+  - [Cucumber configuration](#cucumber-configuration)
+  - [World parameters](#world-parameters)
   - [Enable videos](#enable-videos)
   - [Change screenshot options](#change-screenshot-options)
   - [Custom Cucumber world](#custom-cucumber-world)
     - [Playwright world](#playwright-world)
     - [Core world](#core-world)
+- [Reports](#reports)
+  - [Built-in HTML report](#built-in-html-report)
+  - [Beautiful HTML report](#beautiful-html-report)
+  - [JSON and XML reports](#json-and-xml-reports)
 - [Code coverage](#code-coverage)
 - [Example projects](#example-projects)
   - [Main examples](#main-examples)
@@ -44,25 +46,27 @@ Plugin to use Cucumber within Nx workspaces
 - [Logging](#logging)
 - [Contribution](#contribution)
 - [Troubleshooting](#troubleshooting)
-  - [Known limitations in 1.x](#known-limitations-in-1x)
-  - [Dev server does not shutdown properly](#dev-server-does-not-shutdown-properly)
-  - [Wrong line numbers when using Playwright inspector](#wrong-line-numbers-when-using-playwright-inspector)
-  - [A tag is not found](#a-tag-is-not-found)
-  - [Some Cucumber product feature does not work with nx-cucumber](#some-cucumber-product-feature-does-not-work-with-nx-cucumber)
+- [Migration from 1.x](#migration-from-1x)
 
 <!-- /TOC -->
 
 ## Introduction
 
-This is nx-cucumber, a plugin for Nx which integrates Cucumber to create the best possible connection between these two essential tools for quality software. The main purpose is to provide generators and executors for multiple Cucumber implementations within Nx workspaces. We have just started with [Cucumber for JavaScript](https://github.com/cucumber/cucumber-js) plus optional [Playwright](https://playwright.dev/docs/library) support and there is already more on the [roadmap](https://gitlab.com/gnuechtel/open-source/-/issues/13).
+This is nx-cucumber, a plugin for Nx which integrates Cucumber to create the best possible connection between these two essential tools for quality software. The plugin provides generators and inferred tasks for [Cucumber for JavaScript](https://github.com/cucumber/cucumber-js) within Nx workspaces, with optional [Playwright](https://playwright.dev/docs/library) support.
 
-## Prerequisites
+## What changed in 2.x
+
+Version 2.x is a deliberate breaking release that simplifies the plugin architecture:
 
-The only prerequisite for this software is [Node.js](https://nodejs.org/). In our [continuous delivery pipeline](#continuous-delivery-pipeline), we test against the latest Node.js LTS version. Other versions are expected to work, but there is no guarantee. Since this is an [Nx](https://nx.dev/) plugin for [Cucumber](https://github.com/cucumber/cucumber-js), these tools are required too. To provide the best experience for browser automation, the [Playwright library](https://playwright.dev/docs/library) is supported out-of-the-box, but is completely optional and must be enabled explicitly. The npm package supports Nx versions `>=20 <23`. CI coverage focuses on `latest` and `next` Nx versions with the latest Cucumber and Playwright dependencies.
+- **Inferred tasks replace explicit executors.** The `@gnuechtel/nx-cucumber:cucumber-api` executor has been removed. Projects are discovered via `cucumber.js` config files and targets are inferred automatically using [Nx Project Crystal](https://nx.dev/concepts/inferred-tasks).
+- **Framework-native execution.** Tests run via `npx cucumber-js` directly instead of an in-process Cucumber API. This unlocks full Cucumber CLI capabilities without plugin-specific wrappers.
+- **Less configuration.** Generated projects include a `cucumber.js` config file and a minimal `project.json`. All Cucumber and Playwright options are configured through standard Cucumber and Playwright mechanisms.
+- **Nx >=22 only.** The 2.x line requires Nx 22 or later.
+- **Adapter-oriented architecture.** The plugin uses an adapter contract to support multiple executable-spec frameworks. See [docs/adapters/contract.md](https://gitlab.com/gnuechtel/open-source/-/blob/main/docs/adapters/contract.md) for details.
 
-## Cucumber JavaScript API
+## Prerequisites
 
-This plugin uses the [Cucumber JavaScript API](https://github.com/cucumber/cucumber-js/blob/main/docs/javascript_api.md). That means, Cucumber is used in-process and _not_ on the command-line. By using this great piece of software, we achieve optimal performance, stability and testing for executing Cucumber scenarios with Nx.
+The only prerequisite for this software is [Node.js](https://nodejs.org/). In our [continuous delivery pipeline](#continuous-delivery-pipeline), we test against the latest Node.js LTS version. Other versions are expected to work, but there is no guarantee. Since this is an [Nx](https://nx.dev/) plugin for [Cucumber](https://github.com/cucumber/cucumber-js), these tools are required too. To provide the best experience for browser automation, the [Playwright library](https://playwright.dev/docs/library) is supported out-of-the-box, but is completely optional and must be enabled explicitly. The npm package supports Nx versions `>=22`. CI coverage focuses on `latest` and `next` Nx versions with the latest Cucumber and Playwright dependencies.
 
 ## Quick start
 
@@ -83,14 +87,14 @@ npm i -D @cucumber/cucumber @playwright/test
 # install this plugin
 npm i -D @gnuechtel/nx-cucumber
 
+# register the plugin in nx.json (enables inferred tasks)
+# add "@gnuechtel/nx-cucumber" to the "plugins" array in nx.json
+
 # create a cucumber project for gnu-app
 npx nx g @gnuechtel/nx-cucumber:project --project=gnu-app --test-runner=playwright
 
-# run cucumber scenarios (implicitly starts gnu-app)
+# run cucumber scenarios (uses inferred e2e target)
 npx nx e2e gnu-app-e2e
-
-# display generated cucumber HTML report
-open ./dist/cucumber-js/apps/gnu-app-e2e/reports/html/cucumber-test-report.html
 ```
 
 ## Install Nx
@@ -100,7 +104,7 @@ There are two feasible options to [install Nx](https://nx.dev/getting-started/in
 - either via `npx create-nx-workspace@latest` to setup a fresh Nx repo or
 - via `npx nx@latest init` to convert an existing Node.js project into an Nx workspace.
 
-It is never recommended to install all those Nx [dependencies](https://www.npmjs.com/org/nx) manually.  
+It is never recommended to install all those Nx [dependencies](https://www.npmjs.com/org/nx) manually.
 It would just cause too much unnecessary work.
 
 ## Install dependencies
@@ -115,12 +119,11 @@ If we want to use the Playwright test runner, we should also install one of the
 - [playwright](https://www.npmjs.com/package/playwright) (Playwright library) _or_
 - [@playwright/test](https://www.npmjs.com/package/@playwright/test) (Playwright Test framework)
 
-Since Cucumber is our executor, we are using the [Playwright library](https://playwright.dev/docs/library), not the complete _Playwright Test_ framework. However, Playwright Test also provides very useful [expect](https://playwright.dev/docs/test-assertions) extensions which are usable standalone with the library. So we recommend using `@playwright/test`, which also includes the `playwright` dependency.
+We recommend using `@playwright/test`, which also includes the `playwright` dependency and provides very useful [expect](https://playwright.dev/docs/test-assertions) extensions.
 
 Optional dependencies:
 
-- [cucumber-html-reporter](https://www.npmjs.com/package/cucumber-html-reporter) is only required when report option `html-beautiful` is enabled.
-- [nyc](https://www.npmjs.com/package/nyc) is only required when code coverage instrumentation is enabled.
+- [cucumber-html-reporter](https://www.npmjs.com/package/cucumber-html-reporter) is required for the [beautiful HTML report](#beautiful-html-report).
 
 ## Generate Cucumber projects
 
@@ -139,126 +142,136 @@ npx nx g @gnuechtel/nx-cucumber:project --project=my-project --test-runner=playw
 
 # playwright test runner with custom e2e project name (generates an app 'my-project-foo-e2e')
 npx nx g @gnuechtel/nx-cucumber:project --project=my-project --name my-project-foo-e2e --test-runner=playwright
-
-# playwright test runner with custom base URL
-npx nx g @gnuechtel/nx-cucumber:project --project=my-project --test-runner=playwright --base-url=http://localhost:8765
 ```
 
+The generator creates:
+
+- A `cucumber.js` config file with paths, formatters, and TypeScript support
+- A minimal `project.json` with lint target and implicit dependencies
+- Feature files, step definitions, and TypeScript configuration
+
+The `e2e` target is **not** defined in `project.json`. It is inferred by the plugin from the `cucumber.js` config file.
+
 ### Additional project generator options
 
 All possible project generator options may be passed as command-line parameters and are stored in the related [schema file](https://gitlab.com/gnuechtel/open-source/-/blob/main/libs/nx-cucumber/src/generators/project/schema.json). They can also be displayed on the command-line with the following command: `npx nx g @gnuechtel/nx-cucumber:project --help`.
 
 ## Execute Cucumber projects
 
-### Basic executor usage
+### Inferred tasks
 
-After the Cucumber project was generated, we are able to execute it with nx:
+In 2.x, the `e2e` target is automatically inferred when the plugin detects a `cucumber.js` config file in a project directory. No executor configuration is needed:
 
 ```bash
 npx nx e2e my-project-e2e
 ```
 
-The project generator created a `project.json` with a default configuration which works out-of-the-box for hello-world projects as described in the quick start.
-
-### Additional executor options
-
-To change the default configuration, we manually edit the `project.json` of the Cucumber project. All available options are stored in the [executor schema file](https://gitlab.com/gnuechtel/open-source/-/blob/main/libs/nx-cucumber/src/executors/cucumber-api/schema.json). Additionally, a `cucumber.js` file can be stored beside the `project.json` to tweak Cucumber configuration by custom code (see next section).
-
-### Custom Cucumber configuration
-
-Some Cucumber properties are accessible via `project.json`.  
-But not all properties are supported by nx-cucumber and sometimes, we even want to customize the supported ones.
-
-For example, we want to set tags based on environment variables.  
-To achieve such a custom Cucumber configuration:
-
-1. We remove the related property from `project.json`: ~~"tags": "not @ignore"~~.
-
-2. We create a `cucumber.js` file next to `project.json`. For example:
-
-   ```javascript
-   const tagsFilter =
-     process.env['CI_STAGE'] !== 'qa' // Some custom logic based on an example stage variable
-       ? 'and not @qa-stage-only' // Exclude all 'qa-stage-only' scenarios
-       : 'and (@qa-stage or @qa-stage-only)'; // Only include 'qa-stage' or 'qa-stage-only' scenarios
-
-   module.exports = {
-     default: { tags: `not @ignore ${tagsFilter}` }, // Combine default filter with stage filter
-   };
-   ```
-
-In this example, we used a Cucumber configuration file in CommonJS format, but [other formats](https://github.com/cucumber/cucumber-js/blob/main/docs/configuration.md#files) are supported too. Also we would be able to set all advanced Cucumber [options](https://github.com/cucumber/cucumber-js/blob/main/docs/configuration.md#options) in the `cucumber.js` file which are not yet supported in `project.json`.
-
-### Custom Playwright configuration
-
-Custom Playwright options which are passed to a [new browser context](https://playwright.dev/docs/api/class-browser#browser-new-context) may be customized with nx-cucumber. By default, the project generator already creates custom Playwright options in `project.json`:
-
-```json
-"additionalPlaywrightConfiguration": { "acceptDownloads": true }
-```
-
-By adding more properties to `additionalPlaywrightConfiguration` we are able to customize the Playwright behavior.
+### Plugin registration
 
-By default, Playwright scenarios run in Chromium. To execute them in another Playwright browser, set `browser` in `project.json`:
+To enable inferred tasks, register the plugin in `nx.json`:
 
 ```json
-"browser": "firefox"
+{
+  "plugins": ["@gnuechtel/nx-cucumber"]
+}
 ```
 
-Possible values are `chromium`, `firefox`, and `webkit`.
-
-### Multiple dev server targets
-
-By default, the project generator creates a dev server target and a base URL in `project.json`:
+Target names can be customized:
 
 ```json
 {
-  "devServerTarget": "my-project:serve",
-  "baseUrl": "http://localhost:4200"
+  "plugins": [
+    {
+      "plugin": "@gnuechtel/nx-cucumber",
+      "options": {
+        "e2eTargetName": "integration"
+      }
+    }
+  ]
 }
 ```
 
-This will start a dev server with the defined nx target and waits until the `baseUrl` is ready with HTTP status code 200.  
-After the execution of the Cucumber scenarios, the dev server process will be terminated.
-
-For some projects it is also util to start more than one dev server, so nx-cucumber supports this:
+### Cucumber configuration
 
-```json
-"devServerTargets": ["some-dependent-service:serve", "my-project:serve"]
-```
+All Cucumber options are configured in the `cucumber.js` file. The generator creates a default configuration. For example, to customize tags based on environment variables:
 
-Here, two dev server targets will be started before Cucumber execution and terminated afterwards in reverse order.  
-To wait for additional URLs there is also another useful configuration:
+```javascript
+const tagsFilter =
+  process.env['CI_STAGE'] !== 'qa'
+    ? 'and not @qa-stage-only'
+    : 'and (@qa-stage or @qa-stage-only)';
 
-```json
-"additionalDevServerUrls": ["http://localhost:9999/status"]
+module.exports = {
+  default: {
+    tags: `not @ignore ${tagsFilter}`,
+  },
+};
 ```
 
-Here we additionally wait for the Cucumber execution until the URL `http://localhost:9999/status` is ready (also with HTTP status code 200).
+All advanced Cucumber [options](https://github.com/cucumber/cucumber-js/blob/main/docs/configuration.md#options) can be set in the `cucumber.js` file.
 
-### Skip dev server
+### World parameters
 
-Sometimes it is not desired to use the dev server facilities of this plugin. For example, the server was started by another script and we just want to execute the Cucumber scenarios. For those use cases, we can skip the dev server in `project.json`:
+Playwright-related options that were previously set in `project.json` executor options are now configured via `worldParameters` in `cucumber.js`:
 
-```json
-"skipServe": true
+```javascript
+module.exports = {
+  default: {
+    // ... paths, require, etc.
+    worldParameters: {
+      headed: false,
+      browser: 'chromium',
+      disableVideoFiles: true,
+      disableVideoAttachments: true,
+      disableScreenshotFiles: false,
+      disableScreenshotAttachments: false,
+      disableJavaScript: false,
+      disableCoverage: false,
+    },
+  },
+};
 ```
 
 ### Enable videos
 
-By default, the project generator disables video files and attachments. To enable video files, we remove the `disableVideoFiles` option from `project.json` or set it to `false`. Removing that option, would store video files with scenario names in the Cucumber output directory (`dist/cucumber-js/application-path/videos` by default). If we also want to include the video files in Cucumber reports as attachments, there is a `disableVideoAttachments` option in `project.json`. Again, we can remove it or set to `false`.
+By default, video files and attachments are disabled. To enable them, set the world parameters in `cucumber.js`:
+
+```javascript
+module.exports = {
+  default: {
+    // ... paths, require, etc.
+    worldParameters: {
+      disableVideoFiles: false,
+      disableVideoAttachments: false,
+    },
+  },
+};
+```
 
 ### Change screenshot options
 
-Also by default, screenshots are attached to every scenario which runs with Playwright. We will see them in the Cucumber reports for successful and erroneous scenarios. On the other hand, screenshot _files_ will be created only in case of error. They will also be stored in the Cucumber output directory (`dist/cucumber-js/application-path/screenshots` by default). To change the default behavior and create screenshot files for successful scenario too, we set `enableSuccessfulScreenshotFiles` to `true`. But we can also change the screenshot options in the other direction by setting `disableScreenshotFiles` and `disableScreenshotAttachments` to `true` to disable screenshots completely.
+By default, screenshots are attached to every Playwright scenario. Screenshot _files_ are created only on error. To change this:
+
+```javascript
+module.exports = {
+  default: {
+    // ... paths, require, etc.
+    worldParameters: {
+      enableSuccessfulScreenshotFiles: true, // also create files for passing scenarios
+      // disableScreenshotFiles: true,       // disable screenshot files entirely
+      // disableScreenshotAttachments: true,  // disable screenshot attachments in reports
+    },
+  },
+};
+```
 
 ### Custom Cucumber world
 
-For the Playwright and the core test runner, an additional custom [world](https://github.com/cucumber/cucumber-js/blob/main/docs/support_files/world.md) may be created to extend the default behavior. To achieve this, we add the `--custom-world` parameter to the project generator. Currently, the custom world for the core test runner is always generated, even if the parameter is omitted. We are [aware](https://gitlab.com/gnuechtel/open-source/-/issues/30) of this and will change it in the future. An example path for a generated custom world would be `apps/my-project-e2e/src/shared/my-project-world.ts`. The name is the same for both test runners, but there are differences in the implementation.
+For the Playwright and the core test runner, an additional custom [world](https://github.com/cucumber/cucumber-js/blob/main/docs/support_files/world.md) may be created to extend the default behavior. To achieve this, we add the `--custom-world` parameter to the project generator.
 
 #### Playwright world
 
-A custom Playwright world must be derived from the `PlaywrightWorld` class of nx-cucumber since a lot of default behavior for the Playwright test runner is implemented there. In theory, it is possible to write an own Playwright world from scratch, but it is absolutely not recommended. To enable a custom Playwright world, it is also required, to set `customWorld` to `true` in `project.json` and to register that world via `setWorldConstructor`. The project generator will create this required code for us.
+A custom Playwright world must be derived from the `PlaywrightWorld` class of nx-cucumber since a lot of default behavior for the Playwright test runner is implemented there. To enable a custom Playwright world, it is also required to register that world via `setWorldConstructor`. The project generator will create this required code for us.
 
 An example Playwright world, which extends the built-in clean-up method looks like this:
 
@@ -302,9 +315,48 @@ export class CustomWorld extends World {
 }
 ```
 
+## Reports
+
+### Built-in HTML report
+
+The generator configures the Cucumber built-in `html` formatter by default. The report is generated at `dist/e2e/<project-root>/reports/html/cucumber-test-report-builtin.html`.
+
+### Beautiful HTML report
+
+For a richer HTML report with metadata and screenshots, install `cucumber-html-reporter` and use the exported `createBeautifulHtmlReport` utility:
+
+```bash
+npm i -D cucumber-html-reporter
+```
+
+The utility generates a beautiful HTML report from the Cucumber JSON output:
+
+```typescript
+import { createBeautifulHtmlReport } from '@gnuechtel/nx-cucumber';
+
+createBeautifulHtmlReport({
+  jsonDir: 'dist/e2e/apps/my-project-e2e/reports/cucumber-json',
+  outputDir: 'dist/e2e/apps/my-project-e2e/reports/html',
+  reportTitle: 'My Project E2E Tests',
+});
+```
+
+### JSON and XML reports
+
+The generator configures `json` and `junit` formatters by default:
+
+- JSON: `dist/e2e/<project-root>/reports/cucumber-json/cucumber-test-report.json`
+- XML (JUnit): `dist/e2e/<project-root>/reports/test-results/cucumber-test-report.xml`
+
 ## Code coverage
 
-Code coverage is an important part for all kinds of testing, so nx-cucumber supports it for the Playwright and core test runner. All [example projects](#example-projects) are configured for code coverage. Playwright code coverage will be enabled by proper application configuration as done in the [example react project](https://gitlab.com/gnuechtel/open-source/-/commit/9b74724b). Core code coverage will be enabled with the `--instrument-test-runner` project generator parameter as done in the [example Node.js project](https://gitlab.com/gnuechtel/open-source/-/commit/cdbd6a00).
+Code coverage is supported for the Playwright test runner through the `PlaywrightWorld` hooks, which collect Istanbul coverage automatically. To enable code coverage for a Playwright project:
+
+1. Install the Vite Istanbul plugin: `npm i -D vite-plugin-istanbul`
+2. Configure the plugin in the application's `vite.config.ts`
+3. The `PlaywrightWorld` hooks will automatically collect and report coverage
+
+All [example projects](#example-projects) demonstrate code coverage configuration.
 
 ## Example projects
 
@@ -312,43 +364,19 @@ Code coverage is an important part for all kinds of testing, so nx-cucumber supp
 
 This repository contains [example projects](https://gitlab.com/gnuechtel/open-source/-/tree/main/apps/example) that can be used directly to see nx-cucumber in action.
 
-In the following table, we will see the following information:
-
-- the examples that are split into two projects in each case: one main application project and one cucumber project,
-- the Nx commands to create these projects, where the cucumber projects are generated with nx-cucumber,
-- the configured code coverage for each project,
-- the execution of the cucumber specifications with nx-cucumber (via `nx e2e`),
-- the Cucumber and coverage reports used.
-
-|                              | example react application and cucumber project                                                                                                                                                             | example Node.js app and cucumber project                                                                                                                                                                  |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Execute cucumber project** | `npx nx e2e example-react-app-e2e`                                                                                                                                                                         | `npx nx e2e example-node-app-e2e`                                                                                                                                                                         |
-| **Source cucumber project**  | [apps/example/react-app-e2e](https://gitlab.com/gnuechtel/open-source/-/tree/main/apps/example/react-app-e2e)                                                                                              | [apps/example/node-app-e2e](https://gitlab.com/gnuechtel/open-source/-/tree/main/apps/example/node-app-e2e)                                                                                               |
-| **Cucumber project file**    | [react-app-e2e/project.json](https://gitlab.com/gnuechtel/open-source/-/blob/main/apps/example/react-app-e2e/project.json)                                                                                 | [node-app-e2e/project.json](https://gitlab.com/gnuechtel/open-source/-/tree/main/apps/example/node-app-e2e/project.json)                                                                                  |
-| **Source main project**      | [apps/example/react-app](https://gitlab.com/gnuechtel/open-source/-/tree/main/apps/example/react-app)                                                                                                      | [apps/example/node-app](https://gitlab.com/gnuechtel/open-source/-/tree/main/apps/example/node-app)                                                                                                       |
-| **Create main project**      | `npx nx g @nx/react:application example/react-app --bundler=vite --style=css --e2e-test-runner=none --routing`                                                                                             | `npx nx g @gnuechtel/nx-cucumber:project --project=example-node-app --directory=example/node-app-e2e --instrument-test-runner`                                                                            |
-| **Create cucumber project**  | `npx nx g @gnuechtel/nx-cucumber:project --project=example-react-app --directory=example/react-app-e2e --test-runner=playwright`                                                                           | `npx nx g @gnuechtel/nx-cucumber:project --project=example-node-app --directory=example/node-app-e2e --instrument-test-runner`                                                                            |
-| **Code coverage**            | [configured](https://gitlab.com/gnuechtel/open-source/-/commit/9b74724b) with the vite istanbul plugin                                                                                                     | `--instrument-test-runner` parameter and [optimizations](https://gitlab.com/gnuechtel/open-source/-/commit/cdbd6a00)                                                                                      |
-| **Cucumber report**          | [cucumber-test-report.html](https://gitlab.com/gnuechtel/open-source/-/jobs/artifacts/main/file/dist/cucumber-js/apps/example/react-app-e2e/reports/html/cucumber-test-report.html?job=e2e-examples:linux) | [cucumber-test-report.html](https://gitlab.com/gnuechtel/open-source/-/jobs/artifacts/main/file/dist/cucumber-js/apps/example/node-app-e2e/reports/html/cucumber-test-report.html?job=e2e-examples:linux) |
-| **Coverage report**          | [lcov-report/index.html](https://gitlab.com/gnuechtel/open-source/-/jobs/artifacts/main/file/dist/coverage/apps/example/react-app-e2e/lcov-report/index.html?job=e2e-examples:linux)                       | [lcov-report/index.html](https://gitlab.com/gnuechtel/open-source/-/jobs/artifacts/main/file/dist/coverage/apps/example/node-app-e2e/lcov-report/index.html?job=e2e-examples:linux)                       |
+|                              | example react application and cucumber project                                                                | example Node.js app and cucumber project                                                                    |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **Execute cucumber project** | `npx nx e2e example-react-app-e2e`                                                                            | `npx nx e2e example-node-app-e2e`                                                                           |
+| **Source cucumber project**  | [apps/example/react-app-e2e](https://gitlab.com/gnuechtel/open-source/-/tree/main/apps/example/react-app-e2e) | [apps/example/node-app-e2e](https://gitlab.com/gnuechtel/open-source/-/tree/main/apps/example/node-app-e2e) |
 
 ### More examples
 
-If we have executed our nx-cucumber [end-to-end tests](#end-to-end-tests-of-this-project), we got a lot of more [example projects](https://gitlab.com/gnuechtel/open-source/-/jobs/artifacts/main/browse/tmp/test-project/apps/?job=e2e-nx-cucumber:linux:%20[latest,%20latest,%20latest]), their [Cucumber](https://gitlab.com/gnuechtel/open-source/-/jobs/artifacts/main/browse/tmp/test-project/dist/cucumber-js/apps/?job=e2e-nx-cucumber:linux:%20[latest,%20latest,%20latest]) output and [coverage](https://gitlab.com/gnuechtel/open-source/-/jobs/artifacts/main/browse/tmp/test-project/dist/coverage/apps/?job=e2e-nx-cucumber:linux:%20[latest,%20latest,%20latest]) reports for free. For example:
-
-- [multimedia-playwright](https://gitlab.com/gnuechtel/open-source/-/jobs/artifacts/main/browse/tmp/test-project/apps/gnu-app-multimedia-playwright-e2e/?job=e2e-nx-cucumber:linux:%20[latest,%20latest,%20latest])
-- [custom-world-playwright](https://gitlab.com/gnuechtel/open-source/-/jobs/artifacts/main/browse/tmp/test-project/apps/gnu-app-custom-world-playwright-e2e/?job=e2e-nx-cucumber:linux:%20[latest,%20latest,%20latest])
-- [covered-playwright](https://gitlab.com/gnuechtel/open-source/-/jobs/artifacts/main/browse/tmp/test-project/apps/gnu-app-covered-playwright-e2e/?job=e2e-nx-cucumber:linux:%20[latest,%20latest,%20latest])
-- [covered-core](https://gitlab.com/gnuechtel/open-source/-/jobs/artifacts/main/browse/tmp/test-project/apps/gnu-app-covered-core-e2e/?job=e2e-nx-cucumber:linux:%20[latest,%20latest,%20latest])
+If we have executed our nx-cucumber [end-to-end tests](#end-to-end-tests-of-this-project), we got a lot of more example projects and their Cucumber output for free.
 
 ## End-to-end tests of this project
 
 We support Cucumber with this plugin, and it would be a shame if we used anything other than Cucumber for our own end to end tests. So, we [just do it](https://gitlab.com/gnuechtel/open-source/-/blob/main/apps/nx-cucumber-e2e/features/nx-cucumber.feature)!
 
-And we are not only using Cucumber alone, we are also using nx-cucumber for our end-to-end tests! This is possible, since nx-cucumber is also usable inside this repository. So we can use nx-cucumber for our tests and example projects.
-
-A great side effect of using nx-cucumber internally is also, that we will be our own and first consumer. So we will always got the first integration test for free after code changes.
-
 To run our own end-to-end tests we simply execute them by:
 
 ```bash
@@ -361,96 +389,76 @@ Our [continuous delivery pipeline](https://gitlab.com/gnuechtel/open-source/-/pi
 
 The end-to-end tests in the continuous delivery pipeline run on combinations of:
 
-- [latest](https://gitlab.com/gnuechtel/open-source/-/jobs/artifacts/main/file/tmp/test-project/dist/cucumber-js/apps/gnu-app-multimedia-playwright-e2e/reports/html/cucumber-test-report.html?job=e2e-nx-cucumber:linux:%20[latest,%20latest,%20latest]) and [next](https://gitlab.com/gnuechtel/open-source/-/jobs/artifacts/main/file/tmp/test-project/dist/cucumber-js/apps/gnu-app-multimedia-playwright-e2e/reports/html/cucumber-test-report.html?job=e2e-nx-cucumber:linux:%20[next,%20latest,%20latest]) Nx version
+- latest and next Nx version
 - the latest Cucumber version
-- the latest and [next](https://gitlab.com/gnuechtel/open-source/-/jobs/artifacts/main/file/tmp/test-project/dist/cucumber-js/apps/gnu-app-multimedia-playwright-e2e/reports/html/cucumber-test-report.html?job=e2e-nx-cucumber:linux:%20[latest,%20latest,%20next]) Playwright version
+- the latest and next Playwright version
 
-So we currently run 4 Linux matrix combinations. Windows and macOS end-to-end tests run only with the latest versions.
-
-![continuous delivery pipeline with selected e2e jobs](https://gitlab.com/gnuechtel/open-source/-/raw/a5efc3dab283ca70da0d2f335df65c7081fbdfac/libs/nx-cucumber/assets/pipeline-jobs.png)
+Linux runs the full test suite. macOS and Windows run `@core` tagged scenarios for faster feedback.
 
 ## Debugging and watching scenarios
 
-During the development of Cucumber scenarios, it can be useful to use debugging and watching.  
-Debugging means, that we can go to the Cucumber scenarios step by step.  
+During the development of Cucumber scenarios, it can be useful to use debugging and watching.
+Debugging means, that we can go to the Cucumber scenarios step by step.
 Watching means, that scenarios will be executed automatically after file changes.
 
 ### Debugging
 
-Debugging is available for the Playwright test runner only.  
-It enables the Playwright inspector with paused execution in a headed browser.  
-We achieve debugging by the following command:
+Debugging is available for the Playwright test runner only.
+It enables the Playwright inspector with paused execution in a headed browser.
+Set the `PWDEBUG` environment variable:
 
 ```bash
-npx nx e2e my-project-e2e --debug
+PWDEBUG=1 npx nx e2e my-project-e2e
 ```
 
-In the following screenshot, we can see the debug mode in action:
-
-![debug Playwright](https://gitlab.com/gnuechtel/open-source/-/raw/f3d4938292fb6fef4c8d6ddcc13bd9c31b05db29/libs/nx-cucumber/assets/debug-playwright.png)
-
 ### Watching
 
-To watch Cucumber tests, we can use nx [workspace watching](https://nx.dev/recipes/running-tasks/workspace-watching). By convenience, the project generator creates an `e2e-watch` target (see [example react app](https://gitlab.com/gnuechtel/open-source/-/blob/a4a012089ce5db916f9b2bdb00dad4266b65df3d/apps/example/react-app-e2e/project.json#L28)) which we can use with the following command:
-
-```bash
-npx nx e2e-watch example-react-app-e2e
-```
-
-We can combine watching with other parameters:
+To watch Cucumber tests, we can use nx [workspace watching](https://nx.dev/recipes/running-tasks/workspace-watching):
 
 ```bash
-npx nx e2e-watch example-react-app-e2e --debug
-npx nx e2e-watch example-react-app-e2e --debug --tags=@focus
+npx nx watch --projects=my-project-e2e -- npx nx e2e my-project-e2e
 ```
 
 ## Filter Cucumber scenarios
 
-While development of Cucumber scenarios, we often want to execute only selected scenarios. We can achieve this by using the filter capabilities of Cucumber.
+While development of Cucumber scenarios, we often want to execute only selected scenarios. We can achieve this by using the filter capabilities of Cucumber in the `cucumber.js` config or via CLI arguments.
 
 ### Filter by tags
 
-- Add some tag to some scenario or feature, like `@focus`:
-
-  ```gherkin
-  @focus
-  Scenario: a user wants to get project information
+Add a tag to a scenario and filter:
 
-  Given any user has found our project home page
-  When the user requests project information
-  Then some advices will be shown
-  ```
-
-- Run scenarios with tag parameter:
+```gherkin
+@focus
+Scenario: a user wants to get project information
 
-  ```bash
-  # Run one-time ...
-  npx nx e2e my-project-e2e --tag=@focus
+Given any user has found our project home page
+When the user requests project information
+Then some advices will be shown
+```
 
-  # ... or in combination with watch to continuously run scenarios while development
-  npx nx e2e-watch my-project-e2e --tag=@focus
-  ```
+```bash
+npx nx e2e my-project-e2e -- --tags "@focus"
+```
 
 ### Filter by name
 
-We can filter scenarios by name with regular expressions. Simple expressions are good to include scenarios (like in the first example). More [sophisticated](https://regex101.com/r/Lko9Iv/1) expressions are used when we want to exclude some scenarios (like in the second example).
+We can filter scenarios by name with regular expressions:
 
 ```bash
 # execute all scenarios where the name contains 'payment'
-npx nx e2e my-project-e2e --name "payment"
+npx nx e2e my-project-e2e -- --name "payment"
 
 # execute all scenarios where the name does not contain 'mobile' nor something like 'top secret'
-npx nx e2e my-project-e2e --name '^((?!mobile|top.?secret).)*$'
+npx nx e2e my-project-e2e -- --name '^((?!mobile|top.?secret).)*$'
 ```
 
 ## Special tags
 
-As seen in the last chapter, Cucumber tags can be used for scenario filtering. Another purpose is to control some technical behavior.
-Nx-cucumber provides some technical built-in tags which are described here.
+Cucumber tags can be used for scenario filtering and to control technical behavior. Nx-cucumber provides some technical built-in tags which are described here.
 
 ### Tags `@javascript` and `@noscript`
 
-In `project.json` we can set `disableJavaScript` to `true`. With that setting, we would disable javascript for all Cucumber scenarios with the Playwright test runner. However, we can enable javascript again for selected scenarios in such a case, by using the `@javascript` tag for single scenarios or complete features:
+In `cucumber.js` we can set `worldParameters.disableJavaScript` to `true`. With that setting, we would disable javascript for all Cucumber scenarios with the Playwright test runner. However, we can enable javascript again for selected scenarios by using the `@javascript` tag:
 
 ```gherkin
 @javascript
@@ -473,9 +481,7 @@ Then a welcome message will be shown
 
 ### Tag @headed
 
-By default, all Cucumber scenarios with Playwright run in a headless browser. Some actions like copy-and-paste do not work headless. In such cases, we can add the `@headed` tag to scenarios to use a headed browser. When a headless browser is currently running, it will be closed and a headed one will be started and vice versa. Existing headless/headed browser instances will be reused, when the previous scenario also used the same browser mode.
-
-A headed example scenario could be written like this:
+By default, all Cucumber scenarios with Playwright run in a headless browser. Some actions like copy-and-paste do not work headless. In such cases, we can add the `@headed` tag to scenarios to use a headed browser.
 
 ```gherkin
 @headed
@@ -486,190 +492,117 @@ When the users copies the search
 Then the search data is stored in the clipboard
 ```
 
-The following example implementation of the Cucumber steps reads data from the clipboard.  
-It only works with the `@headed` tag and could be written like this:
-
-```typescript
-import { Given, Then, When } from '@cucumber/cucumber';
-import { expect } from '@playwright/test';
-import { PlaywrightWorld } from '@gnuechtel/nx-cucumber';
-
-Given(
-  'the user has searched for content',
-  async function (this: PlaywrightWorld) {
-    await this.page.type('#search', mySearch);
-    await this.page.click('#searchButton');
-  }
-);
-
-When('users copies the search', async function (this: PlaywrightWorld) {
-  await this.page.click('#copySearchButton');
-});
-
-Then(
-  'the search data is stored in the clipboard',
-  async function (this: PlaywrightWorld) {
-    const clipboardText = await readTextFromClipboard(this.page);
-    expect(clipboardText).toBe(mySearch);
-  }
-);
-
-const mySearch = 'my search';
-
-async function readTextFromClipboard(page: Page) {
-  await page.context().grantPermissions(['clipboard-read']);
-  return (await page.evaluate(() =>
-    window.navigator.clipboard.readText().then((text) => {
-      return new Promise((resolve) => {
-        resolve(text);
-      });
-    })
-  )) as string;
-}
-```
-
 ## Profiles
 
-Nx-cucumber supports [Cucumber profiles](https://github.com/cucumber/cucumber-js/blob/main/docs/profiles.md) with [custom Cucumber configuration](#custom-cucumber-configuration).  
-An example `cucumber.js` file which provides some profiles for special names could look like this:
+Nx-cucumber supports [Cucumber profiles](https://github.com/cucumber/cucumber-js/blob/main/docs/profiles.md) in the `cucumber.js` config:
 
 ```javascript
 module.exports = {
+  default: {
+    // ... default configuration
+  },
   homepage: { name: ['a user visits the home page'] },
   'project-info': { name: ['a user wants to get project information'] },
 };
 ```
 
-To define profiles, which will be executed by default, we can define them in `project.json` like this:
-
-```json
-"profiles": ["homepage"]
-```
-
-We can also run profiles from the command-line, which would override any defined default profiles:
+Run profiles from the command-line:
 
 ```bash
-# Use our custom homepage and project-info profiles
-npx nx e2e my-project-e2e --profile homepage --profile project-info
-
-# Use built-in Cucumber default profile
-npx nx e2e my-project-e2e --profile default
+npx nx e2e my-project-e2e -- --profile homepage
 ```
 
 ## Logging
 
-Logging messages are produced by the [debug](https://www.npmjs.com/package/debug) library. The project generator creates a [.env file](https://gitlab.com/gnuechtel/open-source/-/blob/main/libs/nx-cucumber/src/generators/project/files/all/.env.template?ref_type=heads) which contains the default logging configuration. By changing the `.env` file in the generated Cucumber project, the verbosity of the log output may be decreased (e.g. remove `pw:api` or just use `e2e:cucumber`) or increased (e.g. use `pw:*`). A typical output for a single scenario with Playwright looks like this:
-
-```log
-2023-10-31T23:26:23.135Z e2e:cucumber STARTED - scenario - a user visits the home page
-2023-10-31T23:26:23.136Z e2e:hooks Before - Cleaning up
-2023-10-31T23:26:23.136Z e2e:world Cleaning up world instance
-2023-10-31T23:26:23.136Z e2e:world World instance cleaned up
-2023-10-31T23:26:23.136Z e2e:hooks Before - Cleaned up
-2023-10-31T23:26:23.137Z e2e:cucumber PASSED - hook - prepare
-2023-10-31T23:26:23.137Z e2e:hooks Before not @headed - Creating new headless Chromium instance
-2023-10-31T23:26:23.139Z pw:api => browserType.launch started
-2023-10-31T23:26:23.295Z pw:api <= browserType.launch succeeded
-2023-10-31T23:26:23.295Z e2e:hooks Before not @headed - Chromium instance created
-2023-10-31T23:26:23.296Z e2e:cucumber PASSED - hook - ensure headless browser [not @headed]
-2023-10-31T23:26:23.296Z e2e:hooks BeforeStep
-2023-10-31T23:26:23.298Z pw:api =>  started
-2023-10-31T23:26:23.304Z pw:api <=  succeeded
-2023-10-31T23:26:23.307Z pw:api => browserContext.exposeFunction started
-2023-10-31T23:26:23.310Z pw:api <= browserContext.exposeFunction succeeded
-2023-10-31T23:26:23.310Z pw:api =>  started
-2023-10-31T23:26:23.311Z pw:api <=  succeeded
-2023-10-31T23:26:23.311Z pw:api => browserContext.newPage started
-2023-10-31T23:26:23.338Z pw:api <= browserContext.newPage succeeded
-2023-10-31T23:26:23.340Z pw:api => page.goto started
-2023-10-31T23:26:23.341Z pw:api navigating to "http://localhost:4200/", waiting until "load"
-2023-10-31T23:26:23.356Z pw:api   "commit" event fired
-2023-10-31T23:26:23.356Z pw:api   navigated to "http://localhost:4200/"
-2023-10-31T23:26:23.426Z pw:api   "domcontentloaded" event fired
-2023-10-31T23:26:23.426Z pw:api   "load" event fired
-2023-10-31T23:26:23.427Z pw:api <= page.goto succeeded
-2023-10-31T23:26:23.427Z e2e:hooks AfterStep - Creating screenshots
-2023-10-31T23:26:23.428Z e2e:world Storing screenshots
-2023-10-31T23:26:23.430Z pw:api => page.screenshot started
-2023-10-31T23:26:23.431Z pw:api taking page screenshot
-2023-10-31T23:26:23.655Z pw:api <= page.screenshot succeeded
-2023-10-31T23:26:23.655Z e2e:world Attaching image to current step
-2023-10-31T23:26:23.656Z e2e:world Image attached
-2023-10-31T23:26:23.656Z e2e:world Successful screenshot files are disabled
-2023-10-31T23:26:23.656Z e2e:world Screenshots stored
-2023-10-31T23:26:23.656Z e2e:hooks AfterStep - Screenshots created
-2023-10-31T23:26:23.657Z e2e:cucumber PASSED - step - any user finds our project home page
-2023-10-31T23:26:23.657Z e2e:hooks BeforeStep
-2023-10-31T23:26:23.662Z pw:api => locator._expect started
-2023-10-31T23:26:23.663Z pw:api locator._expect with timeout 5000ms
-2023-10-31T23:26:23.665Z pw:api waiting for locator('h1').getByText('Hello there, Welcome gnu-app 👋')
-2023-10-31T23:26:23.683Z pw:api   locator resolved to <h1>…</h1>
-2023-10-31T23:26:23.683Z pw:api <= locator._expect succeeded
-2023-10-31T23:26:23.684Z e2e:hooks AfterStep - Creating screenshots
-2023-10-31T23:26:23.684Z e2e:world Storing screenshots
-2023-10-31T23:26:23.685Z pw:api => page.screenshot started
-2023-10-31T23:26:23.686Z pw:api taking page screenshot
-2023-10-31T23:26:23.837Z pw:api <= page.screenshot succeeded
-2023-10-31T23:26:23.837Z e2e:world Attaching image to current step
-2023-10-31T23:26:23.838Z e2e:world Image attached
-2023-10-31T23:26:23.838Z e2e:world Successful screenshot files are disabled
-2023-10-31T23:26:23.838Z e2e:world Screenshots stored
-2023-10-31T23:26:23.838Z e2e:hooks AfterStep - Screenshots created
-2023-10-31T23:26:23.839Z e2e:cucumber PASSED - step - a welcome message will be shown
-2023-10-31T23:26:23.839Z e2e:hooks After - Collecting coverage
-2023-10-31T23:26:23.841Z pw:api => page.evaluate started
-2023-10-31T23:26:23.847Z pw:api =>  started
-2023-10-31T23:26:23.848Z pw:api <=  succeeded
-2023-10-31T23:26:23.849Z pw:api <= page.evaluate succeeded
-2023-10-31T23:26:23.849Z e2e:hooks After - Coverage collected
-2023-10-31T23:26:23.849Z e2e:hooks After - Cleaning up
-2023-10-31T23:26:23.849Z e2e:world Cleaning up world instance
-2023-10-31T23:26:23.849Z e2e:world Closing browser context
-2023-10-31T23:26:23.850Z pw:api =>  started
-2023-10-31T23:26:23.859Z pw:api <=  succeeded
-2023-10-31T23:26:23.859Z e2e:world Browser context closed
-2023-10-31T23:26:23.859Z e2e:world World instance cleaned up
-2023-10-31T23:26:23.859Z e2e:hooks After - Cleaned up
-2023-10-31T23:26:23.859Z e2e:cucumber PASSED - hook - clean up
-2023-10-31T23:26:23.860Z e2e:cucumber FINISHED - scenario - a user visits the home page
-```
+Logging messages are produced by the [debug](https://www.npmjs.com/package/debug) library. The project generator creates a [.env file](https://gitlab.com/gnuechtel/open-source/-/blob/main/libs/nx-cucumber/src/generators/project/files/all/.env.template?ref_type=heads) which contains the default logging configuration. By changing the `.env` file in the generated Cucumber project, the verbosity of the log output may be decreased or increased.
 
 ## Contribution
 
-Currently, this project is written and maintained by a [single person](https://gitlab.com/christian.gnuechtel). Development is active with focus on 1.x compatibility and planned 2.x improvements. Contributing is welcome, especially bug fixes and compatibility updates. Please [open an issue](https://gitlab.com/gnuechtel/open-source/-/issues/new) if you want to join.
+Currently, this project is written and maintained by a [single person](https://gitlab.com/christian.gnuechtel). Development is active with focus on 2.x improvements. Contributing is welcome, especially bug fixes and compatibility updates. Please [open an issue](https://gitlab.com/gnuechtel/open-source/-/issues/new) if you want to join.
 
 ## Troubleshooting
 
-### Known limitations in 1.x
+### A tag is not found
 
-In the 1.x maintenance line, the following limitations are intentional:
+A common mistake, is to forget the `@` before any tag. This would be wrong: ~~npx nx e2e example-react-app-e2e -- --tags "mytag"~~.
+The correct usage is: `npx nx e2e example-react-app-e2e -- --tags "@mytag"`.
 
-- Playwright UI mode is not supported in the current 1.x executor architecture (tracked for 2.x via #43).
-- Deterministic parallel Cucumber execution is not supported in 1.x (tracked for 2.x via #44).
-- Inline-workspace Playwright inspector line precision is a known limitation and remains `won't fix` in 1.x (#36).
-- Generated external-workspace debug source navigation history is tracked in #49 (currently closed). Open a follow-up issue if regression reappears.
+### Some Cucumber product feature does not work with nx-cucumber
 
-### Dev server does not shutdown properly
+Since 2.x uses framework-native execution via `npx cucumber-js`, all Cucumber CLI features are available directly. Configure them in the `cucumber.js` file.
 
-Nx-cucumber does its best to properly shutdown dev server(s) after Cucumber execution. For some project setups it is difficult or even impossible to kill all processes. For such cases an easy workaround exists:
+If a feature is missing, please open an issue with a minimal reproducible setup.
 
-Before executing the Cucumber project, we just start the dev server in another terminal. For example: `npx nx serve my-application`. After that, we execute the Cucumber scenarios as usual: `npx nx e2e my-application-e2e`. The nx-cucumber will detect the running application via the base URL. After the execution the server is still running, since nx-cucumber only shutdowns the self-started dev servers.
+## Migration from 1.x
 
-### Wrong line numbers when using Playwright inspector
+### Prerequisites
 
-When trying out the example projects inside this repository, the Playwright inspector can highlight incorrect line numbers when execution is paused. For inline-workspace scenarios this is tracked in [#36](https://gitlab.com/gnuechtel/open-source/-/issues/36) and remains `won't fix` in 1.x.
+- Upgrade to Nx `>=22`
+- Install `@gnuechtel/nx-cucumber@2`
 
-Generated external-workspace debug source navigation history is documented in [#49](https://gitlab.com/gnuechtel/open-source/-/issues/49), which is currently closed. If a regression reappears, open a follow-up issue. Depending on workspace setup and sync state, source mapping may still vary.
+### Step 1: Register the plugin
 
-### A tag is not found
+Add the plugin to `nx.json`:
 
-A common mistake, is to forget the `@` before any tag. This would be wrong: ~~npx nx e2e example-react-app-e2e --tag=mytag~~.  
-The correct usage is: `npx nx e2e example-react-app-e2e --tag=@mytag`.
+```json
+{
+  "plugins": ["@gnuechtel/nx-cucumber"]
+}
+```
 
-### Some Cucumber product feature does not work with nx-cucumber
+### Step 2: Create cucumber.js config
 
-Nx-cucumber aims to support all important Cucumber product features. Since we are using the [Cucumber JavaScript API](#cucumber-javascript-api), the `cucumber-js` command-line tool is not available, but fortunately most of the advanced features may be used with [custom Cucumber configuration](#custom-cucumber-configuration).
+For each e2e project, create a `cucumber.js` file. For Playwright projects:
 
-Since this is an open source project, you can change this software for your own needs. However, it would be the best choice to [contribute](#contribution) to this project by opening an [issue](https://gitlab.com/gnuechtel/open-source/-/issues/new).
+```javascript
+const outputDir = 'dist/e2e/apps/my-project-e2e';
+
+module.exports = {
+  default: {
+    paths: ['apps/my-project-e2e/features/**/*.feature'],
+    requireModule: ['ts-node/register'],
+    require: [
+      'apps/my-project-e2e/src/**/*.ts',
+      'node_modules/@gnuechtel/nx-cucumber/src/playwright/playwright-world-default.js',
+      'node_modules/@gnuechtel/nx-cucumber/src/playwright/playwright-hooks.js',
+    ],
+    tags: 'not @ignore',
+    format: [
+      'summary',
+      'progress-bar',
+      `json:${outputDir}/reports/cucumber-json/cucumber-test-report.json`,
+      `html:${outputDir}/reports/html/cucumber-test-report-builtin.html`,
+      `junit:${outputDir}/reports/test-results/cucumber-test-report.xml`,
+    ],
+    publishQuiet: true,
+  },
+};
+```
+
+For core (non-Playwright) projects, omit the Playwright require entries.
+
+### Step 3: Simplify project.json
+
+Remove the executor-based `e2e` and `e2e-cucumber` targets from `project.json`. The plugin infers the `e2e` target automatically from the `cucumber.js` file. Keep only non-inferred targets like `lint`.
+
+### Step 4: Move executor options to cucumber.js
+
+| 1.x executor option            | 2.x equivalent                                        |
+| ------------------------------ | ----------------------------------------------------- |
+| `testRunner`                   | Which `require` entries are in `cucumber.js`          |
+| `featuresDirectory`            | `paths` in `cucumber.js`                              |
+| `tags`                         | `tags` in `cucumber.js`                               |
+| `cucumberTimeout`              | `timeout` in `cucumber.js`                            |
+| `baseUrl`, `headed`, `browser` | `worldParameters` in `cucumber.js`                    |
+| `disableVideoFiles`, etc.      | `worldParameters` in `cucumber.js`                    |
+| `devServerTarget`              | Use Nx task dependencies (`dependsOn`)                |
+| `reportOptions`                | `format` entries in `cucumber.js`                     |
+| `instrumentTestRunner`         | External coverage tooling (nyc, vite-plugin-istanbul) |
+
+### Step 5: Verify
+
+```bash
+npx nx e2e my-project-e2e
+```
 
-If a Cucumber feature is missing, please open an issue with a minimal reproducible setup. Maintenance work is prioritized by compatibility and impact.
+The inferred target runs `npx cucumber-js` with the configuration from `cucumber.js`.