@gnuechtel/nx-cucumber 2.0.0-beta.3 → 2.0.0

package/README.md

@@ -11,6 +11,7 @@ Plugin to use Cucumber within Nx workspaces
 - [Install Nx](#install-nx)
 - [Install dependencies](#install-dependencies)
 - [Generate Cucumber projects](#generate-cucumber-projects)
+  - [Choosing the --project value](#choosing-the---project-value)
   - [Basic project generator usage](#basic-project-generator-usage)
   - [Additional project generator options](#additional-project-generator-options)
 - [Execute Cucumber projects](#execute-cucumber-projects)
@@ -24,9 +25,9 @@ Plugin to use Cucumber within Nx workspaces
     - [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)
+  - [Built-in formatter outputs](#built-in-formatter-outputs)
+  - [Run metadata report](#run-metadata-report)
+  - [Custom formatter configuration](#custom-formatter-configuration)
 - [Code coverage](#code-coverage)
 - [Example projects](#example-projects)
   - [Main examples](#main-examples)
@@ -64,6 +65,9 @@ Version 2.x is a deliberate breaking release that simplifies the plugin architec
 - **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.
 - **Faster execution.** Removing the executor bootstrap, in-process Cucumber API, plugin-managed dev server lifecycle, and report post-processing from the execution path results in faster test runs.
+- **Reporting is formatter-first.** Generated projects now rely on Cucumber-native formatters (`html`, `json`, `message`, `junit`) plus a dedicated run-metadata formatter artifact. No HTML mutation layer is used.
+- **Legacy HTML post-processing removed.** The previously exported `createBeautifulHtmlReport` helper and `cucumber-html-reporter` integration are no longer part of 2.x.
+- **Configuration filename scope.** In 2.x, plugin discovery/generation/migration is centered on `cucumber.js`.
 
 ## Prerequisites
 
@@ -91,11 +95,14 @@ 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
+# inspect available Nx project ids (quick-start app id is @gnu-repo/gnu-app)
+npx nx show projects
 
-# run cucumber scenarios (uses inferred e2e target)
-npx nx e2e gnu-app-e2e
+# create a cucumber project for the quick-start app project id
+npx nx g @gnuechtel/nx-cucumber:project --project="@gnu-repo/gnu-app" --test-runner=playwright
+
+# run cucumber scenarios with the generated e2e project id
+npx nx e2e "@gnu-repo/gnu-app-e2e"
 ```
 
 ## Install Nx
@@ -122,27 +129,43 @@ If we want to use the Playwright test runner, we should also install one of the
 
 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 required for the [beautiful HTML report](#beautiful-html-report).
+No additional reporting dependency is required for the default outputs.
 
 ## Generate Cucumber projects
 
+### Choosing the `--project` value
+
+`--project` must be an existing Nx project id, not the workspace folder name.
+
+Use `npx nx show projects` to list valid project ids in your workspace. For Nx 22 monorepo presets (including this quick-start), app project ids are scoped by default (for example `@gnu-repo/gnu-app`).
+
+Some existing/legacy workspaces can still use unscoped ids, so always copy the exact id from `npx nx show projects`.
+
+If the id is scoped, quote it in shell commands:
+
+```bash
+npx nx g @gnuechtel/nx-cucumber:project --project="@smoke-test/smoke-test"
+```
+
+If `--project` does not exist, generation fails fast with an explicit error.
+
+When `--name` is unscoped and the tested project id is scoped, the generated e2e project id inherits the same scope.
+
 ### Basic project generator usage
 
 After the installation of the dependencies, we can create a project with Cucumber, for any kind of node application:
 
 ```bash
-# Prerequisite: create application 'my-project' (see quick start for a complete example)
+# Prerequisite: create an application and identify its Nx project id via "npx nx show projects"
 
 # default core test runner (generates an e2e app 'my-project-e2e')
-npx nx g @gnuechtel/nx-cucumber:project --project=my-project
+npx nx g @gnuechtel/nx-cucumber:project --project="<app-project-id>"
 
 # playwright test runner (also generates an e2e app 'my-project-e2e')
-npx nx g @gnuechtel/nx-cucumber:project --project=my-project --test-runner=playwright
+npx nx g @gnuechtel/nx-cucumber:project --project="<app-project-id>" --test-runner=playwright
 
 # 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
+npx nx g @gnuechtel/nx-cucumber:project --project="<app-project-id>" --name my-project-foo-e2e --test-runner=playwright
 ```
 
 The generator creates:
@@ -155,8 +178,8 @@ The `e2e` target behavior depends on the selected test runner:
 
 - **Core runner:** no explicit `e2e` target is generated. The `e2e` task is inferred by the plugin from `cucumber.js`.
 - **Playwright runner:** explicit command targets are generated:
-  - `e2e-prepare` installs Playwright Chromium (Linux uses `--with-deps`).
-  - `e2e` runs `start-server-and-test` with `kill-port` before Cucumber execution.
+  - `e2e-prepare` installs Playwright Chromium (Linux uses `--with-deps`) and is configured with `cache: false`.
+  - `e2e` runs a generated `run-e2e.js` lifecycle script that manages the full dev server lifecycle (clear port, start server, wait for readiness, run Cucumber, stop server) using only Node.js built-ins.
   - `e2e-ci` runs `e2e-prepare` and then `e2e`.
 
 ### Additional project generator options
@@ -223,6 +246,8 @@ module.exports = {
 
 All advanced Cucumber [options](https://github.com/cucumber/cucumber-js/blob/main/docs/configuration.md#options) can be set in the `cucumber.js` file.
 
+> **2.x limitation:** `@gnuechtel/nx-cucumber` currently supports `cucumber.js` as the plugin configuration file for inferred-task discovery, generator output, and migration output. Other Cucumber config filenames (for example `cucumber.mjs`) are not supported by the plugin in this major version.
+
 ### World parameters
 
 Playwright-related options that were previously set in `project.json` executor options are now configured via `worldParameters` in `cucumber.js`:
@@ -330,36 +355,26 @@ 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`.
+### Built-in formatter outputs
 
-### Beautiful HTML report
+Generated projects configure Cucumber-native formatter outputs by default:
 
-For a richer HTML report with metadata and screenshots, install `cucumber-html-reporter` and use the exported `createBeautifulHtmlReport` utility:
+- HTML: `dist/e2e/<project-root>/reports/html/cucumber-test-report-builtin.html`
+- JSON: `dist/e2e/<project-root>/reports/cucumber-json/cucumber-test-report.json`
+- NDJSON messages: `dist/e2e/<project-root>/reports/cucumber-messages/cucumber-messages.ndjson`
+- XML (JUnit): `dist/e2e/<project-root>/reports/test-results/cucumber-test-report.xml`
 
-```bash
-npm i -D cucumber-html-reporter
-```
+### Run metadata report
 
-The utility generates a beautiful HTML report from the Cucumber JSON output:
+Generated projects also include an additional metadata artifact:
 
-```typescript
-import { createBeautifulHtmlReport } from '@gnuechtel/nx-cucumber';
+- Metadata JSON: `dist/e2e/<project-root>/reports/metadata/cucumber-run-metadata.json`
 
-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',
-});
-```
+This file is written by `@gnuechtel/nx-cucumber/src/core/cucumber-run-metadata-formatter.js` and is intentionally separate from Cucumber's standard JSON/NDJSON schema. It contains run context (for example Cucumber meta info, run timestamps, selected world parameters, and environment hints like browser/baseUrl/mode).
 
-### JSON and XML reports
+### Custom formatter configuration
 
-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`
+The plugin does not lock formatter choices. You can freely add, remove, or replace formatters in your `cucumber.js` file. The generated metadata formatter receives values via `formatOptions.nxCucumberRunMetadata.worldParameters`, while normal runtime behavior still uses `worldParameters`.
 
 ## Code coverage
 
@@ -390,6 +405,8 @@ If we have executed our nx-cucumber [end-to-end tests](#end-to-end-tests-of-this
 
 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)!
 
+Generation coverage includes validation for unknown `--project` ids and execution against real Nx project ids detected in the test workspace.
+
 To run our own end-to-end tests we simply execute them by:
 
 ```bash
@@ -426,12 +443,15 @@ PWDEBUG=1 npx nx e2e my-project-e2e
 
 ### Watching
 
-To watch Cucumber tests, we can use nx [workspace watching](https://nx.dev/recipes/running-tasks/workspace-watching):
+There is no dedicated watch mode in `@gnuechtel/nx-cucumber`.
+If you want automatic re-runs on file changes, you can use Nx [workspace watching](https://nx.dev/recipes/running-tasks/workspace-watching) as an optional outer loop:
 
 ```bash
 npx nx watch --projects=my-project-e2e -- npx nx e2e my-project-e2e
 ```
 
+This command belongs to Nx workspace tooling, not to a plugin-specific watch implementation.
+
 ## 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 in the `cucumber.js` config or via CLI arguments.
@@ -546,31 +566,94 @@ Since 2.x uses framework-native execution via `npx cucumber-js`, all Cucumber CL
 
 If a feature is missing, please open an issue with a minimal reproducible setup.
 
-### Windows Playwright jobs hang or time out unexpectedly
+### Garbled terminal output with verbose Playwright logs (`pw:api`)
+
+If log lines look overwritten or scattered (for example on macOS, Linux, or Windows terminals), there are usually two independent redraw layers:
 
-If Windows jobs appear to hang after scenarios finish, or fail intermittently before the first browser step, use the generated Playwright `e2e` command pattern:
+1. Cucumber formatter output:
+   - `progress-bar` is a real-time updating bar (redraws terminal line).
+   - `progress` is step-by-step progress output without a live bar redraw.
+2. Nx task output lifecycle:
+   - dynamic/TUI modes may also rewrite terminal output while tasks run.
+   - `static` prints append-only output.
+
+References:
+
+- Cucumber formatters (`progress` vs `progress-bar`): https://github.com/cucumber/cucumber-js/blob/main/docs/formatters.md
+- Nx `outputStyle` modes: https://nx.dev/reference/core-api/nx/documents/show#outputstyle
+
+nx-cucumber templates currently use `progress-bar`. If redraw artifacts are distracting with verbose `pw:api` logs, switch to `progress` (or keep only `summary`) in your local `cucumber.js`.
+
+If you still want fully append-only Nx logs, run:
 
 ```bash
-npx kill-port 4200 && start-server-and-test "npx nx run <app>:serve --port=4200 --strictPort" http://localhost:4200 "npx cucumber-js --config <e2e-project>/cucumber.js"
+npx nx e2e "<project-id>" --outputStyle=static
+```
+
+or set this in a **workspace-root** `.env`:
+
+```env
+NX_DEFAULT_OUTPUT_STYLE=static
+```
+
+Note: nx-cucumber intentionally does not generate or modify a workspace-root `.env`, because that would change logging behavior globally for unrelated projects in the same workspace.
+
+### Workspace sync after generating projects
+
+On Nx 20+, running `e2e` immediately after generating a new nx-cucumber project (core or Playwright) may fail with:
+
+```
+The workspace is out of sync
+[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references...
 ```
 
-For CI, prefer the generated `e2e-ci` target to include browser preparation:
+This is standard Nx behaviour and is not Windows-specific. It can happen on macOS, Linux, and Windows when sync generators detect pending workspace updates.
+
+For deterministic smoke-test runs, execute:
 
 ```bash
-npx nx run <e2e-project>:e2e-ci
+npx nx sync
 ```
 
-Why this is more stable:
+and then rerun your `npx nx e2e "<project-id>"` command.
 
-- `kill-port` removes stale listeners before readiness checks.
-- `start-server-and-test` owns start/wait/test/stop lifecycle in one process chain.
-- `--strictPort` prevents fallback port switches by Vite that can break URL expectations.
+To avoid this manual step in interactive environments, configure `nx.json`:
 
-For this repository, use the dedicated regression command:
+```json
+{
+  "sync": { "applyChanges": true }
+}
+```
+
+With this setting Nx automatically applies sync changes before running tasks in interactive terminals.
+
+In non-interactive local runs (no TTY), Nx cannot prompt; if sync changes are needed, task execution stops with a workspace-out-of-sync error.
+
+In CI on Nx 22, task-time sync prompting is skipped, so add an explicit preflight:
 
 ```bash
-npm run e2e:port-regression:react-example
+npx nx sync:check
+```
+
+If it reports changes are required, run `npx nx sync` and commit the resulting files.
+
+`npx nx reset` is a recovery step for stale daemon/project-graph state (for example `Cannot find project "..."` right after generation, or a newly generated project missing from `npx nx show projects` even after `npx nx sync`). It is not the primary sync fix.
+
+### `TS_NODE_PROJECT` and formatter file extensions
+
+Generated `cucumber.js` files set `process.env.TS_NODE_PROJECT` explicitly. Keep this setting so `ts-node/register` resolves the correct `tsconfig.json` in monorepos.
+
+If you add custom formatters, prefer `.js` (or precompiled output) for formatter modules referenced in `format`. Cucumber loads formatter modules via dynamic import, and pointing directly to a `.ts` formatter can fail with `ERR_UNKNOWN_FILE_EXTENSION` before TypeScript transpilation hooks are applied.
+
+### Windows Playwright teardown noise
+
+On Windows, after all scenarios finish, the following message may appear in the output:
+
 ```
+ERROR: The process "XXXX" not found.
+```
+
+This is harmless. The generated `run-e2e.js` lifecycle script attempts to stop the dev server after testing. If the server has already exited on its own, `taskkill` reports this message. It does not indicate a test failure.
 
 ## Migration from 1.x
 
@@ -579,6 +662,63 @@ npm run e2e:port-regression:react-example
 - Upgrade to Nx `>=22`
 - Install `@gnuechtel/nx-cucumber@2`
 
+### Version compatibility and upgrade order
+
+`@gnuechtel/nx-cucumber` 1.x does not have one single Nx compatibility range (taken from published npm `peerDependencies`):
+
+| nx-cucumber 1.x | Nx peer compatibility     |
+| --------------- | ------------------------- |
+| `1.0.0`         | `^16 \|\| ^17`            |
+| `1.0.1`         | `^16 \|\| ^17 \|\| ^18`   |
+| `1.0.2`         | `16 - 19`                 |
+| `1.1.0`         | `>=19 <23`                |
+| `1.2.0 - 1.4.1` | `>=20 <23 \|\| ^22.0.0-0` |
+
+Recommended upgrade order for projects moving from 1.x to 2.x:
+
+1. If your project is on `1.0.0`, `1.0.1`, or `1.0.2`, first install and run with a compatible Nx (for example Nx 17) to avoid peer-resolution conflicts.
+2. Remove the legacy plugin package from `package.json`:
+   `npm remove @gnuechtel/nx-cucumber`
+3. Upgrade Nx to 22:
+   `npx nx@22.6.4 migrate 22.6.4`
+   `npm install`
+   `npx nx migrate --run-migrations`
+4. Install `@gnuechtel/nx-cucumber@2`.
+5. Run the plugin migration (`nx migrate @gnuechtel/nx-cucumber@2` + `nx migrate --run-migrations`).
+
+For `1.1.0+`, Nx 22 is already within the supported peer range. The temporary Nx-17 compatibility step is not required there.
+
+### Automated migration via nx migrate
+
+You can run the legacy executor migration as part of the standard Nx migration flow:
+
+```bash
+npx nx migrate @gnuechtel/nx-cucumber@2
+npx nx migrate --run-migrations
+```
+
+What this migration does:
+
+- Detects projects using `@gnuechtel/nx-cucumber:cucumber-api`.
+- Adds `@gnuechtel/nx-cucumber` to `nx.json` plugins (if missing).
+- Removes legacy executor targets (`e2e-cucumber`, and legacy `e2e` wrappers pointing to `e2e-cucumber`).
+- Removes legacy `e2e-watch` targets that use the old `--watch-message` run-command flow.
+- Creates a `cucumber.js` file when missing, based on detected legacy options.
+- Writes a migration report to `tmp/nx-cucumber-migration-report.json`.
+
+Dry-run mode:
+
+- Set `NX_CUCUMBER_MIGRATION_DRY_RUN=true` before running migrations to print planned changes without modifying files.
+
+### CI migration tests
+
+The repository includes an automated migration matrix test (`@migration` scenarios) for all stable 1.x versions (`1.0.0` to `1.4.1`).
+
+- For `1.0.0 - 1.0.2`, the test uses a compatible Nx 17 workspace first, removes the legacy plugin package, upgrades Nx to 22, then runs the 2.x migration.
+- For `1.1.0+`, the test runs directly on Nx 22.
+
+`npm install` failures from legacy generator internals are not treated as acceptable in these migration tests.
+
 ### Step 1: Register the plugin
 
 Add the plugin to `nx.json`:
@@ -610,6 +750,7 @@ module.exports = {
       'summary',
       'progress-bar',
       `json:${outputDir}/reports/cucumber-json/cucumber-test-report.json`,
+      `message:${outputDir}/reports/cucumber-messages/cucumber-messages.ndjson`,
       `html:${outputDir}/reports/html/cucumber-test-report-builtin.html`,
       `junit:${outputDir}/reports/test-results/cucumber-test-report.xml`,
     ],
@@ -622,7 +763,7 @@ 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`.
+Remove the executor-based `e2e` and `e2e-cucumber` targets from `project.json`. Also remove old `e2e-watch` run-commands. 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
 
@@ -645,3 +786,15 @@ npx nx e2e my-project-e2e
 ```
 
 The inferred target runs `npx cucumber-js` with the configuration from `cucumber.js`.
+
+### Rollback strategy
+
+- Revert the migration commit in git if validation fails.
+- Remove `@gnuechtel/nx-cucumber` from `nx.json` plugins if rollback to 1.x is required.
+- Restore previous `project.json` executor targets and `cucumber.js` from version control.
+
+### Known limitations
+
+- Existing `cucumber.js` files are not overwritten automatically.
+- Framework-native watch mode is not generated automatically. If you still need watch, add your own adapter-native watch command after migration.
+- Highly customized run-command wrappers may require manual cleanup after migration.

package/migrations.json

@@ -0,0 +1,10 @@
+{
+  "generators": {
+    "migrate-cucumber-api-to-inferred-tasks": {
+      "version": "2.0.0",
+      "description": "Migrate legacy cucumber-api executor projects to adapter-based inferred tasks",
+      "implementation": "./src/migrations/update-2-0-0/migrate-cucumber-api-to-inferred-tasks",
+      "cli": "nx"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gnuechtel/nx-cucumber",
-  "version": "2.0.0-beta.3",
+  "version": "2.0.0",
   "description": "Plugin to use Cucumber within Nx workspaces",
   "license": "MIT",
   "repository": {
@@ -12,8 +12,8 @@
     "@nx/devkit": ">=22 <23",
     "minimatch": "^10.0.0",
     "tslib": "^2.3.0",
-    "@gnuechtel/shared-coverage": "2.0.0-beta.3",
-    "@gnuechtel/shared-util": "2.0.0-beta.3"
+    "@gnuechtel/shared-coverage": "2.0.0",
+    "@gnuechtel/shared-util": "2.0.0"
   },
   "peerDependencies": {
     "@cucumber/cucumber": ">=9 <13",
@@ -22,17 +22,14 @@
     "playwright-core": ">=1.38.0-0 <2",
     "playwright": ">=1.38.0-0 <2",
     "@playwright/test": ">=1.38.0-0 <2",
-    "cucumber-html-reporter": "^7.1.0",
     "nx": ">=22 <23"
   },
-  "peerDependenciesMeta": {
-    "cucumber-html-reporter": {
-      "optional": true
-    }
-  },
   "type": "commonjs",
   "main": "./src/index.js",
   "generators": "./generators.json",
+  "nx-migrations": {
+    "migrations": "./migrations.json"
+  },
   "executors": "./executors.json",
   "typings": "./src/index.d.ts",
   "types": "./src/index.d.ts"

package/src/adapters/registry.js

@@ -7,11 +7,16 @@ const minimatch_1 = require("minimatch");
 const path_1 = require("path");
 const cucumberJsAdapter = {
     name: 'cucumber-js',
-    configFilePattern: 'cucumber.{js,cjs,mjs,yaml,yml}',
+    configFilePattern: 'cucumber.js',
     technologies: ['@cucumber/cucumber'],
     targets: {
         e2e: {
             command: 'npx cucumber-js',
+            defaultOptions: {
+                env: {
+                    TS_NODE_PROJECT: '',
+                },
+            },
             dependsOn: ['^build'],
         },
     },

package/src/adapters/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../../../libs/nx-cucumber/src/adapters/registry.ts"],"names":[],"mappings":";;AAmBA,gDAEC;AAMD,4DAMC;AAOD,gDAKC;AA7CD,yCAAsC;AACtC,+BAAgC;AAGhC,MAAM,iBAAiB,GAAsB;IAC3C,IAAI,EAAE,aAAa;IACnB,iBAAiB,EAAE,gCAAgC;IACnD,YAAY,EAAE,CAAC,oBAAoB,CAAC;IACpC,OAAO,EAAE;QACP,GAAG,EAAE;YACH,OAAO,EAAE,iBAAiB;YAC1B,SAAS,EAAE,CAAC,QAAQ,CAAC;SACtB;KACF;CACF,CAAC;AAEF;;GAEG;AACH,SAAgB,kBAAkB;IAChC,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,SAAgB,wBAAwB,CACtC,UAAkB,EAClB,QAA6B;IAE7B,MAAM,QAAQ,GAAG,IAAA,eAAQ,EAAC,UAAU,CAAC,CAAC;IACtC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,IAAA,qBAAS,EAAC,QAAQ,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC;AACpF,CAAC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB,CAAC,QAA6B;IAC9D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC;IACxE,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpE,OAAO,OAAO,QAAQ,GAAG,CAAC;AAC5B,CAAC","sourcesContent":["import { minimatch } from 'minimatch';\nimport { basename } from 'path';\nimport { AdapterDefinition } from './contract';\n\nconst cucumberJsAdapter: AdapterDefinition = {\n  name: 'cucumber-js',\n  configFilePattern: 'cucumber.{js,cjs,mjs,yaml,yml}',\n  technologies: ['@cucumber/cucumber'],\n  targets: {\n    e2e: {\n      command: 'npx cucumber-js',\n      dependsOn: ['^build'],\n    },\n  },\n};\n\n/**\n * Returns all built-in adapter definitions.\n */\nexport function getBuiltinAdapters(): AdapterDefinition[] {\n  return [cucumberJsAdapter];\n}\n\n/**\n * Finds the adapter whose configFilePattern matches the given config file path.\n * Returns undefined if no adapter matches.\n */\nexport function findAdapterForConfigFile(\n  configFile: string,\n  adapters: AdapterDefinition[]\n): AdapterDefinition | undefined {\n  const fileName = basename(configFile);\n  return adapters.find((adapter) => minimatch(fileName, adapter.configFilePattern));\n}\n\n/**\n * Builds a combined glob pattern from all registered adapter config file patterns.\n * Used by createNodesV2 to discover adapter-managed projects in one pass.\n * Returns undefined if no adapters are registered.\n */\nexport function buildDiscoveryGlob(adapters: AdapterDefinition[]): string | undefined {\n  if (adapters.length === 0) return undefined;\n  if (adapters.length === 1) return `**/${adapters[0].configFilePattern}`;\n  const patterns = adapters.map((a) => a.configFilePattern).join(',');\n  return `**/{${patterns}}`;\n}\n"]}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../../../libs/nx-cucumber/src/adapters/registry.ts"],"names":[],"mappings":";;AAwBA,gDAEC;AAMD,4DAMC;AAOD,gDAKC;AAlDD,yCAAsC;AACtC,+BAAgC;AAGhC,MAAM,iBAAiB,GAAsB;IAC3C,IAAI,EAAE,aAAa;IACnB,iBAAiB,EAAE,aAAa;IAChC,YAAY,EAAE,CAAC,oBAAoB,CAAC;IACpC,OAAO,EAAE;QACP,GAAG,EAAE;YACH,OAAO,EAAE,iBAAiB;YAC1B,cAAc,EAAE;gBACd,GAAG,EAAE;oBACH,eAAe,EAAE,EAAE;iBACpB;aACF;YACD,SAAS,EAAE,CAAC,QAAQ,CAAC;SACtB;KACF;CACF,CAAC;AAEF;;GAEG;AACH,SAAgB,kBAAkB;IAChC,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,SAAgB,wBAAwB,CACtC,UAAkB,EAClB,QAA6B;IAE7B,MAAM,QAAQ,GAAG,IAAA,eAAQ,EAAC,UAAU,CAAC,CAAC;IACtC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,IAAA,qBAAS,EAAC,QAAQ,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC;AACpF,CAAC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB,CAAC,QAA6B;IAC9D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC;IACxE,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpE,OAAO,OAAO,QAAQ,GAAG,CAAC;AAC5B,CAAC","sourcesContent":["import { minimatch } from 'minimatch';\nimport { basename } from 'path';\nimport { AdapterDefinition } from './contract';\n\nconst cucumberJsAdapter: AdapterDefinition = {\n  name: 'cucumber-js',\n  configFilePattern: 'cucumber.js',\n  technologies: ['@cucumber/cucumber'],\n  targets: {\n    e2e: {\n      command: 'npx cucumber-js',\n      defaultOptions: {\n        env: {\n          TS_NODE_PROJECT: '',\n        },\n      },\n      dependsOn: ['^build'],\n    },\n  },\n};\n\n/**\n * Returns all built-in adapter definitions.\n */\nexport function getBuiltinAdapters(): AdapterDefinition[] {\n  return [cucumberJsAdapter];\n}\n\n/**\n * Finds the adapter whose configFilePattern matches the given config file path.\n * Returns undefined if no adapter matches.\n */\nexport function findAdapterForConfigFile(\n  configFile: string,\n  adapters: AdapterDefinition[]\n): AdapterDefinition | undefined {\n  const fileName = basename(configFile);\n  return adapters.find((adapter) => minimatch(fileName, adapter.configFilePattern));\n}\n\n/**\n * Builds a combined glob pattern from all registered adapter config file patterns.\n * Used by createNodesV2 to discover adapter-managed projects in one pass.\n * Returns undefined if no adapters are registered.\n */\nexport function buildDiscoveryGlob(adapters: AdapterDefinition[]): string | undefined {\n  if (adapters.length === 0) return undefined;\n  if (adapters.length === 1) return `**/${adapters[0].configFilePattern}`;\n  const patterns = adapters.map((a) => a.configFilePattern).join(',');\n  return `**/{${patterns}}`;\n}\n"]}

package/src/core/cucumber-run-metadata-formatter.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const { Formatter } = require('@cucumber/cucumber');
+
+class CucumberRunMetadataFormatter extends Formatter {
+  constructor(options) {
+    super(options);
+    const parsedArgvOptions = options.parsedArgvOptions || {};
+    const metadataOptions = readObject(parsedArgvOptions.nxCucumberRunMetadata);
+    this.worldParameters =
+      readWorldParameters(metadataOptions?.worldParameters) ?? readWorldParameters(parsedArgvOptions.worldParameters);
+    this.meta = undefined;
+    this.startedAt = undefined;
+    this.finishedAt = undefined;
+    this.emitted = false;
+
+    options.eventBroadcaster.on('envelope', (envelope) => {
+      if (envelope.meta && !this.meta) {
+        this.meta = envelope.meta;
+      }
+      if (envelope.testRunStarted && envelope.testRunStarted.timestamp) {
+        this.startedAt = timestampToIso(envelope.testRunStarted.timestamp);
+      }
+      if (envelope.testRunFinished) {
+        this.finishedAt = timestampToIso(envelope.testRunFinished.timestamp);
+        this.emitMetadata();
+      }
+    });
+  }
+
+  async finished() {
+    this.emitMetadata();
+    await super.finished();
+  }
+
+  emitMetadata() {
+    if (this.emitted) return;
+    this.log(
+      `${JSON.stringify(buildRunMetadata(this.meta, this.startedAt, this.finishedAt, this.worldParameters), null, 2)}\n`
+    );
+    this.emitted = true;
+  }
+}
+
+function buildRunMetadata(meta, startedAt, finishedAt, worldParameters) {
+  const environment = resolveEnvironmentMetadata(worldParameters);
+  const metadata = {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+  };
+
+  if (meta) metadata.meta = meta;
+  if (startedAt || finishedAt) metadata.testRun = { startedAt, finishedAt };
+  if (worldParameters && Object.keys(worldParameters).length > 0) metadata.worldParameters = worldParameters;
+  if (environment && Object.keys(environment).length > 0) metadata.environment = environment;
+  return metadata;
+}
+
+function resolveEnvironmentMetadata(worldParameters) {
+  if (!worldParameters) return undefined;
+  const browser = stringValue(worldParameters.browser);
+  const baseUrl = stringValue(worldParameters.baseUrl);
+  const headed = worldParameters.headed;
+  const mode = typeof headed === 'boolean' ? (headed ? 'headed' : 'headless') : undefined;
+  const environment = {};
+  if (browser) environment.browser = browser;
+  if (baseUrl) environment.baseUrl = baseUrl;
+  if (mode) environment.mode = mode;
+  return Object.keys(environment).length > 0 ? environment : undefined;
+}
+
+function readWorldParameters(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  return value;
+}
+
+function readObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  return value;
+}
+
+function stringValue(value) {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function timestampToIso(timestamp) {
+  if (!timestamp) return undefined;
+  const seconds = numberValue(timestamp.seconds);
+  if (seconds === undefined) return undefined;
+  const nanos = numberValue(timestamp.nanos) || 0;
+  return new Date(seconds * 1000 + nanos / 1000000).toISOString();
+}
+
+function numberValue(value) {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : undefined;
+  if (typeof value === 'bigint') return Number(value);
+  if (typeof value === 'string') {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  if (!value || typeof value !== 'object') return undefined;
+  if (typeof value.toNumber === 'function') {
+    const result = value.toNumber();
+    return Number.isFinite(result) ? result : undefined;
+  }
+  if (typeof value.low === 'number') return Number.isFinite(value.low) ? value.low : undefined;
+  return undefined;
+}
+
+module.exports = CucumberRunMetadataFormatter;
+module.exports.buildRunMetadata = buildRunMetadata;

package/src/generators/project/files/all/cucumber.js.template

@@ -1,5 +1,15 @@
 process.env.TS_NODE_PROJECT = '<%= projectRoot %>/tsconfig.json';
 const outputDir = 'dist/e2e/<%= projectRoot %>';
+const { pathToFileURL } = require('url');
+const runMetadataFormatter = pathToFileURL(
+  require.resolve('@gnuechtel/nx-cucumber/src/core/cucumber-run-metadata-formatter.js')
+).href;
+const worldParameters = {
+  outputDirectory: outputDir,<% if (isPlaywright) { %>
+  baseUrl: '<%= baseUrl %>',
+  disableVideoFiles: true,
+  disableVideoAttachments: true,<% } %>
+};
 module.exports = {
   default: {
     paths: ['<%= projectRoot %>/features/**/*.feature'],
@@ -13,15 +23,17 @@ module.exports = {
       'summary',
       'progress-bar',
       `json:${outputDir}/reports/cucumber-json/cucumber-test-report.json`,
+      `message:${outputDir}/reports/cucumber-messages/cucumber-messages.ndjson`,
       `html:${outputDir}/reports/html/cucumber-test-report-builtin.html`,
+      [runMetadataFormatter, `${outputDir}/reports/metadata/cucumber-run-metadata.json`],
       `junit:${outputDir}/reports/test-results/cucumber-test-report.xml`,
     ],
-    worldParameters: {
-      outputDirectory: outputDir,<% if (isPlaywright) { %>
-      baseUrl: '<%= baseUrl %>',
-      disableVideoFiles: true,
-      disableVideoAttachments: true,<% } %>
+    formatOptions: {
+      nxCucumberRunMetadata: {
+        worldParameters,
+      },
     },
+    worldParameters,
     publishQuiet: true,
   },
 };