@gnuechtel/nx-cucumber 2.0.0-beta.4 → 2.1.0-14848049561

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`.
-
-### Beautiful HTML report
+### Built-in formatter outputs
 
-For a richer HTML report with metadata and screenshots, install `cucumber-html-reporter` and use the exported `createBeautifulHtmlReport` utility:
+Generated projects configure Cucumber-native formatter outputs by default:
 
-```bash
-npm i -D cucumber-html-reporter
-```
+- 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`
 
-The utility generates a beautiful HTML report from the Cucumber JSON output:
+### Run metadata report
 
-```typescript
-import { createBeautifulHtmlReport } from '@gnuechtel/nx-cucumber';
+Generated projects also include an additional metadata artifact:
 
-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',
-});
-```
+- Metadata JSON: `dist/e2e/<project-root>/reports/metadata/cucumber-run-metadata.json`
 
-### JSON and XML reports
+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).
 
-The generator configures `json` and `junit` formatters by default:
+### Custom formatter configuration
 
-- 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
@@ -549,32 +566,95 @@ 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:
+
+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 Windows jobs appear to hang after scenarios finish, or fail intermittently before the first browser step, use the generated Playwright `e2e` command pattern:
+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
 ```
 
-For CI, prefer the generated `e2e-ci` target to include browser preparation:
+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...
+```
+
+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
+```
+
+and then rerun your `npx nx e2e "<project-id>"` command.
+
+To avoid this manual step in interactive environments, configure `nx.json`:
+
+```json
+{
+  "sync": { "applyChanges": true }
+}
 ```
 
-Why this is more stable:
+With this setting Nx automatically applies sync changes before running tasks in interactive terminals.
 
-- `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.
+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.
 
-For this repository, use the dedicated regression command:
+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
 
 ### Prerequisites
@@ -670,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`,
     ],

package/migrations.json

@@ -1,7 +1,7 @@
 {
   "generators": {
     "migrate-cucumber-api-to-inferred-tasks": {
-      "version": "2.0.0-beta.4",
+      "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.4",
+  "version": "2.1.0-14848049561",
   "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.4",
-    "@gnuechtel/shared-util": "2.0.0-beta.4"
+    "@gnuechtel/shared-coverage": "2.1.0-14848049561",
+    "@gnuechtel/shared-util": "2.1.0-14848049561"
   },
   "peerDependencies": {
     "@cucumber/cucumber": ">=9 <13",
@@ -22,14 +22,8 @@
     "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",

package/src/adapters/registry.js

@@ -7,7 +7,7 @@ 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,cjs,mjs,ts,mts,cts,json,yaml,yml}',
     technologies: ['@cucumber/cucumber'],
     targets: {
         e2e: {

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":";;AAmBA,gDAEC;AAMD,4DAMC;AAOD,gDAKC;AA7CD,yCAAsC;AACtC,+BAAgC;AAGhC,MAAM,iBAAiB,GAAsB;IAC3C,IAAI,EAAE,aAAa;IACnB,iBAAiB,EAAE,gDAAgD;IACnE,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,ts,mts,cts,json,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"]}

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/config/cjs/cucumber.__configFormat__.template

@@ -0,0 +1,72 @@
+<% if (isTypeScript) { %>import type { IConfiguration } from '@cucumber/cucumber';
+import { pathToFileURL } from 'url';
+<% } else { %>const { pathToFileURL } = require('url');
+<% } %>const outputDir = 'dist/e2e/<%= projectRoot %>';
+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,<% } %>
+};
+<% if (isTypeScript) { %>
+const config: { [profile: string]: Partial<IConfiguration> } = {
+  default: {
+    paths: ['<%= projectRoot %>/features/**/*.feature'],
+    requireModule: ['ts-node/register', 'tsconfig-paths/register'],
+    require: [
+      '<%= projectRoot %>/src/**/!(*.d|*.spec|*.test).ts',<% if (playwrightRequires !== '[]') { %>
+      ...<%- playwrightRequires %>,<% } %>
+    ],
+    tags: 'not @ignore',
+    format: [
+      '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`,
+    ],
+    formatOptions: {
+      nxCucumberRunMetadata: {
+        worldParameters,
+      },
+    },
+    worldParameters,
+    publishQuiet: true,
+  },
+};
+
+export default config;
+<% } else { %>
+module.exports = {
+  default: {
+    paths: ['<%= projectRoot %>/features/**/*.feature'],
+    requireModule: ['ts-node/register', 'tsconfig-paths/register'],
+    require: [
+      '<%= projectRoot %>/src/**/!(*.d|*.spec|*.test).ts',<% if (playwrightRequires !== '[]') { %>
+      ...<%- playwrightRequires %>,<% } %>
+    ],
+    tags: 'not @ignore',
+    format: [
+      '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`,
+    ],
+    formatOptions: {
+      nxCucumberRunMetadata: {
+        worldParameters,
+      },
+    },
+    worldParameters,
+    publishQuiet: true,
+  },
+};
+<% } %>

package/src/generators/project/files/config/esm/cucumber.__configFormat__.template

@@ -0,0 +1,47 @@
+<% if (isTypeScript) { %>import type { IConfiguration } from '@cucumber/cucumber';
+<% } %>import { pathToFileURL } from 'url';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const outputDir = 'dist/e2e/<%= projectRoot %>';
+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,<% } %>
+};
+<% if (isTypeScript) { %>
+const config: { [profile: string]: Partial<IConfiguration> } = {
+<% } else { %>
+const config = {
+<% } %>  default: {
+    paths: ['<%= projectRoot %>/features/**/*.feature'],
+    requireModule: ['ts-node/register', 'tsconfig-paths/register'],
+    require: [
+      '<%= projectRoot %>/src/**/!(*.d|*.spec|*.test).ts',<% if (playwrightRequires !== '[]') { %>
+      ...<%- playwrightRequires %>,<% } %>
+    ],
+    tags: 'not @ignore',
+    format: [
+      '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`,
+    ],
+    formatOptions: {
+      nxCucumberRunMetadata: {
+        worldParameters,
+      },
+    },
+    worldParameters,
+    publishQuiet: true,
+  },
+};
+
+export default config;

package/src/generators/project/files/config/json/cucumber.__configFormat__.template

@@ -0,0 +1,37 @@
+{
+  "default": {
+    "paths": ["<%= projectRoot %>/features/**/*.feature"],
+    "requireModule": ["ts-node/register", "tsconfig-paths/register"],
+    "require": [
+      "<%= projectRoot %>/src/**/!(*.d|*.spec|*.test).ts"<% for (const req of playwrightRequiresArray) { %>,
+      "<%= req %>"<% } %>
+    ],
+    "tags": "not @ignore",
+    "format": [
+      "summary",
+      "progress-bar",
+      "json:dist/e2e/<%= projectRoot %>/reports/cucumber-json/cucumber-test-report.json",
+      "message:dist/e2e/<%= projectRoot %>/reports/cucumber-messages/cucumber-messages.ndjson",
+      "html:dist/e2e/<%= projectRoot %>/reports/html/cucumber-test-report-builtin.html",
+      ["@gnuechtel/nx-cucumber/src/core/cucumber-run-metadata-formatter.js", "dist/e2e/<%= projectRoot %>/reports/metadata/cucumber-run-metadata.json"],
+      "junit:dist/e2e/<%= projectRoot %>/reports/test-results/cucumber-test-report.xml"
+    ],
+    "formatOptions": {
+      "nxCucumberRunMetadata": {
+        "worldParameters": {
+          "outputDirectory": "dist/e2e/<%= projectRoot %>"<% if (isPlaywright) { %>,
+          "baseUrl": "<%= baseUrl %>",
+          "disableVideoFiles": true,
+          "disableVideoAttachments": true<% } %>
+        }
+      }
+    },
+    "worldParameters": {
+      "outputDirectory": "dist/e2e/<%= projectRoot %>"<% if (isPlaywright) { %>,
+      "baseUrl": "<%= baseUrl %>",
+      "disableVideoFiles": true,
+      "disableVideoAttachments": true<% } %>
+    },
+    "publishQuiet": true
+  }
+}