npm - @g_package/jest-cucumber-fusion - Versions diffs - 3.0.3 → 3.0.5 - Mend

@g_package/jest-cucumber-fusion 3.0.3 → 3.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -3,43 +3,41 @@
 Write Cucumber feature files and run them as Jest tests, without the scaffolding.
 [![Build Status](https://github.com/gotreasa/jest-cucumber-fusion/workflows/Continuous%20Integration/badge.svg)](https://github.com/gotreasa/jest-cucumber-fusion/actions?query=workflow%3A%22Continuous+Integration%22)
-[![Codecov](https://codecov.io/gh/gotreasa/jest-cucumber-fusion/branch/master/graph/badge.svg)](https://codecov.io/gh/gotreasa/jest-cucumber-fusion)
+[![Codecov](https://codecov.io/gh/gotreasa/jest-cucumber-fusion/branch/main/graph/badge.svg)](https://codecov.io/gh/gotreasa/jest-cucumber-fusion)
 [![npm downloads](https://img.shields.io/npm/dm/@g_package/jest-cucumber-fusion)](https://www.npmjs.com/package/@g_package/jest-cucumber-fusion)
 [![npm latest](https://img.shields.io/npm/v/@g_package/jest-cucumber-fusion/latest.svg)](https://www.npmjs.com/package/@g_package/jest-cucumber-fusion)
 [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
 ## Overview
-Jest Cucumber Fusion runs your Cucumber feature files as Jest tests. You write the feature file in Gherkin, and a step definition file with a `Given`, `When`, `Then`, `And` or `But` definition for each step. A `Fusion` call at the end of the step definition file links the two: Fusion reads the feature and creates one Jest test per scenario, so you write no `describe` or `it` blocks yourself. Everything else is plain Jest: `expect`, mocks, coverage and reporting.
-The style of this package began with [Jest-cucumber](https://github.com/bencompton/jest-cucumber), which it was originally built on top of. Since version 3 it no longer depends on that package: it runs on Jest and [@cucumber/gherkin](https://github.com/cucumber/gherkin) directly, and owns the whole test lifecycle itself.
-This package continues [b-yond-infinite-network/jest-cucumber-fusion](https://github.com/b-yond-infinite-network/jest-cucumber-fusion), published on npm as `jest-cucumber-fusion` until version 0.8.1 in June 2021, and is now maintained and published as `@g_package/jest-cucumber-fusion`.
-## Motivation
+Jest Cucumber Fusion runs your Cucumber feature files as Jest tests. You write the feature file in Gherkin, and a step definition file with a `Given`, `When`, `Then`, `And` or `But` definition for each step. A `Fusion` call at the end of the step definition file links the two: Fusion reads the feature and creates one Jest test per scenario, so you write no `describe` or `it` blocks yourself. Everything else is plain Jest: `expect`, mocks, coverage and reporting.
-Jest-cucumber has you write a `defineFeature` block, a `test` for every scenario and a callback for every step to link Jest and Cucumber. With Jest Cucumber Fusion you write only:
- - a Cucumber Feature file with gherkin sentences
- - a Cucumber Step definition file with your javascript validation code, ended with the `Fusion` function to link the two
+**New to Gherkin?** A feature file describes behaviour in plain sentences. Each feature file holds one `Feature`, and each `Scenario` in it is one example of that behaviour. Each line of a scenario starting with `Given`, `When`, `Then`, `And` or `But` is a step, and a step definition is the code that runs for one step. The [Gherkin reference](https://cucumber.io/docs/gherkin/reference/) covers the full syntax.
+**Upgrading** from version 2, or from `jest-cucumber-fusion` 0.8.x? Your feature and step definition files keep their shape, and step files written as CommonJS keep their `require`. [Migrating to version 3](./docs/Migrating.md) lists what changes.
+**Know Cucumber already?** [If you know Cucumber](#if-you-know-cucumber) lists what differs.
 ## Getting Started
-These steps set up a project whose files are ES modules (they use `import` and `export`), which is the recommended way to use Fusion. If your project is CommonJS (it uses `require`), or you need Node 18, follow the same steps with the changes in [Using CommonJS instead](#using-commonjs-instead).
+These steps set up a project whose files are ES modules (they use `import` and `export`), which is the recommended way to use Fusion: ES modules are the module format Node and Jest are moving to, and Fusion's own source is written in them. If your project is CommonJS (it uses `require`), or you need Node 18 (CommonJS runs from Node 18.14), follow these steps with the changes in [Using CommonJS](./docs/CommonJS.md). For step files written in TypeScript, see [Using TypeScript](./docs/TypeScript.md).
-For ES modules you need Node 20.11 or newer.
+### Start a project
-### Install Jest and Jest Cucumber Fusion:
+Check that `node --version` prints 20.11 or newer (for CommonJS, 18.14: see [Using CommonJS](./docs/CommonJS.md)), then:
 ```
+mkdir my-project
+cd my-project
+npm init -y
 npm install --save-dev jest @g_package/jest-cucumber-fusion
+npm pkg set type=module
+npm pkg set scripts.test="node --experimental-vm-modules node_modules/jest/bin/jest.js"
+npm pkg set "jest.testMatch[0]=**/*.steps.js"
 ```
-Coming from `jest-cucumber-fusion` 0.8.x or from version 2 of this package? Your feature and step definition files keep their shape; the import name changes, and several behaviours that used to pass silently now fail with a message saying what to fix. [Migrating to version 3](./docs/Migrating.md) lists each change, observed under both versions.
-### Set these keys in your package.json:
+The last three commands set these keys in your `package.json`, replacing any that `npm init` wrote:
 ```json
 "type": "module",
@@ -47,10 +45,8 @@ Coming from `jest-cucumber-fusion` 0.8.x or from version 2 of this package? Your
 "jest": { "testMatch": [ "**/*.steps.js" ] }
 ```
-Replace any `type` and `scripts.test` that are already there rather than adding a second copy: `npm init -y` writes `"type": "commonjs"` and a placeholder `test` script, and when a key appears twice in `package.json` the last one silently wins.
-- `"type": "module"` makes Node read your `.js` files as ES modules. If you would rather not set it, name your files `.mjs` instead, and change `testMatch` to `[ "**/*.steps.mjs" ]`.
-- Jest runs ES modules only in its ES module mode, which Node's `--experimental-vm-modules` flag turns on. This form of the `test` script is the one Jest's own documentation gives, and it does not depend on your shell's syntax. Node prints an `ExperimentalWarning` about the flag on each run. That is expected.
+- `"type": "module"` makes Node read your `.js` files as ES modules. If you would rather not set it, skip `npm pkg set type=module` and name your step files and the code they import `.mjs` instead (and import them by that name, for example `'../../src/basket.mjs'`), and change `testMatch` to `[ "**/*.steps.mjs" ]`.
+- Jest runs ES modules only in its ES module mode, which Node's `--experimental-vm-modules` flag turns on, so always run the tests with `npm test`, not `npx jest`. Node prints an `ExperimentalWarning` about the flag on each run. That is expected.
 - `testMatch` tells Jest that your step definition files are the test files.
 ### Lay out your project
@@ -58,139 +54,83 @@ Replace any `type` and `scripts.test` that are already there rather than adding
 The examples below use this layout. Any layout works, as long as each `import` path and each `Fusion` path matches where your files are.
 ```
-your-project/
+my-project/
 ├── package.json
 ├── src/
-│   └── rocket.js                      the code under test
+│   └── basket.js                      the code under test
 └── test/
     └── features/
-        ├── rocket-launching.feature
-        └── rocket-launching.steps.js
+        ├── shopping-basket.feature
+        └── shopping-basket.steps.js
 ```
 The code under test in these examples is a small class of your own:
 ```javascript
-//filename: src/rocket.js
-export class Rocket {
+// filename: src/basket.js
+export class Basket {
     constructor() {
-        this.isInSpace = false
-        this.boostersLanded = false
+        this.products = []
     }
-    launch() {
-        this.isInSpace = true
-        this.boostersLanded = true
+    add( product ) {
+        this.products.push( product )
     }
 }
 ```
-### Add a Feature file:
+### Write the feature file
 ```gherkin
-###filename: test/features/rocket-launching.feature
-Feature: Rocket Launching
-Scenario: Launching a SpaceX rocket
-  Given I am Elon Musk attempting to launch a rocket into space
-  When I launch the rocket
-  Then the rocket should end up in space
-  And the booster(s) should land back on the launch pad
-  And nobody should doubt me ever again
-```
-### Add a Cucumber step definition file and load Fusion
-```javascript
-//filename: test/features/rocket-launching.steps.js
-import { Given, When, Then, And, Fusion } from '@g_package/jest-cucumber-fusion'
+# filename: test/features/shopping-basket.feature
+Feature: Shopping basket
+Scenario: Adding a product to an empty basket
+  Given my basket is empty
+  When I add a coffee mug to my basket
+  Then my basket holds 1 product
+  And the product in my basket is a coffee mug
 ```
-Import only the keywords your steps use. `But` is also available.
-**A step binds only to a definition registered with its own keyword.** An `And` step needs an `And(...)` definition, and a `Then(...)` definition with the same text does not serve it. That is why the steps below define `And` for the two `And` lines of the feature. When one definition should serve several keywords, chain it: `Then( And( 'text', fn ) )` registers the same definition under both. A step with no definition makes Fusion refuse the file, naming the step and suggesting the code to add.
-### Load any dependency you need to do your test
-```javascript
-//filename: test/features/rocket-launching.steps.js
-import { Given, When, Then, And, Fusion } from '@g_package/jest-cucumber-fusion'
-import { Rocket } from '../../src/rocket.js'
-let rocket
-```
+### Write the step definitions
-A relative import names the file in full, extension included: `'../../src/rocket.js'`, not `'../../src/rocket'`.
+Each step needs a definition registered with **the same keyword the step uses**. The last step of the feature starts with `And`, so its definition, in the file below, is `And(...)`: a `Then(...)` with the same text would not match it, and Fusion would report the step as having no definition. A `But` step likewise needs a `But(...)` definition: [Rule](./docs/Rule.md) shows one.
-### Add steps definitions:
+The step definition file registers a definition for each step, then calls `Fusion` with the feature file's path:
 ```javascript
-//filename: test/features/rocket-launching.steps.js
+// filename: test/features/shopping-basket.steps.js
 import { Given, When, Then, And, Fusion } from '@g_package/jest-cucumber-fusion'
-import { Rocket } from '../../src/rocket.js'
-let rocket
+import { Basket } from '../../src/basket.js'
-Given( 'I am Elon Musk attempting to launch a rocket into space', () => {
-    rocket = new Rocket()
-} )
+let basket
-When( 'I launch the rocket', () => {
-    rocket.launch()
+Given( 'my basket is empty', () => {
+    basket = new Basket()
 } )
-Then( 'the rocket should end up in space', () => {
-    expect(rocket.isInSpace).toBe(true)
+When( 'I add a coffee mug to my basket', () => {
+    basket.add( 'coffee mug' )
 } )
-And( /^the booster\(s\) should land back on the launch pad$/, () => {
-    expect(rocket.boostersLanded).toBe(true)
+Then( 'my basket holds 1 product', () => {
+    expect( basket.products ).toHaveLength( 1 )
 } )
-And( 'nobody should doubt me ever again', () => {
-    expect('people').not.toBe('haters')
+And( 'the product in my basket is a coffee mug', () => {
+    expect( basket.products[ 0 ] ).toBe( 'coffee mug' )
 } )
-```
-`expect` and the other test globals work as usual. The `jest` object (for `jest.fn()` and friends) is not a global in Jest's ES module mode. Add `@jest/globals` to your `devDependencies` and import it:
-```javascript
-import { jest } from '@jest/globals'
+Fusion( 'shopping-basket.feature' )
 ```
-### Adding the Fusion() call at the end of the Step definition file
-You have to match it with your Cucumber Feature definition file. The path is relative to the step definition file, so a feature file beside it is named on its own:
-```javascript
-//filename: test/features/rocket-launching.steps.js
-import { Given, When, Then, And, Fusion } from '@g_package/jest-cucumber-fusion'
-import { Rocket } from '../../src/rocket.js'
-let rocket
-Given( 'I am Elon Musk attempting to launch a rocket into space', () => {
-    rocket = new Rocket()
-} )
-When( 'I launch the rocket', () => {
-    rocket.launch()
-} )
-Then( 'the rocket should end up in space', () => {
-    expect(rocket.isInSpace).toBe(true)
-} )
-And( /^the booster\(s\) should land back on the launch pad$/, () => {
-    expect(rocket.boostersLanded).toBe(true)
-} )
-And( 'nobody should doubt me ever again', () => {
-    expect('people').not.toBe('haters')
-} )
-Fusion( 'rocket-launching.feature' )
-```
+- **A string matches a step whose text is exactly that string.** To capture a value from a step, such as a number, match it with a regular expression instead: see [Step definition arguments](./docs/StepDefinitionArguments.md).
+- **`Fusion` comes last**, after every definition, and its path is relative to the step definition file, so a feature file beside it is named on its own.
+- **A relative `import` names the file in full**, extension included: `'../../src/basket.js'`, not `'../../src/basket'`.
+- **A step may be `async`.** Fusion waits for each step before running the next. A scenario is one Jest test, so Jest's timeout, 5 seconds by default, covers all of its steps together: raise it with `"testTimeout"` in the `jest` key if your steps are slow.
+- **`expect` and Jest's other test functions work as usual.** The `jest` object is the exception in ES module mode: see [Troubleshooting](#troubleshooting).
+- **Import only the keywords your steps use.** `But` is also available.
 ### Run the tests
@@ -198,373 +138,136 @@ Fusion( 'rocket-launching.feature' )
 npm test
 ```
-Jest reports one test for the scenario, named after it, and fails it at the first step that fails.
-Writing your steps in TypeScript? See [Using TypeScript](#using-typescript).
-## Adding coverage
-Fusion's tests are Jest tests, so Jest's coverage works as usual. Set these keys in your `package.json`:
-```json
-"jest": {
-    "testMatch": [
-      "**/*.steps.js"
-    ],
-    "coveragePathIgnorePatterns": [
-      "/node_modules/",
-      "/test/"
-    ],
-    "coverageDirectory": "./coverage/",
-    "collectCoverage": true
-  }
-```
-For TypeScript step files, match `**/*.steps.ts` instead (see [Using TypeScript](#using-typescript)).
-## Setting options once for a whole run
+Jest reports one test for the scenario, named after it:
-Options can be passed to a single `Fusion` call:
+```text
+ PASS  test/features/shopping-basket.steps.js
+  Shopping basket
+    ✓ Adding a product to an empty basket (2 ms)
-```javascript
-Fusion( 'rocket-launching.feature', { tagFilter: '@smoke and not @slow' } )
+Test Suites: 1 passed, 1 total
+Tests:       1 passed, 1 total
 ```
-Or set once for every step definition file of a run, from a script that Jest's `setupFiles` lists. A global tag filter applies to every feature, so a scenario without a matching tag, such as the untagged rocket scenario above, is reported as skipped:
+If Jest prints only the summary, without the list of tests, see [Troubleshooting](#troubleshooting). A test fails at the first step that fails, and names that step. If a step has no definition at all, Fusion refuses the whole file before any test runs, and gives you the code to add. Without the `And` definition above, for example:
-```javascript
-//filename: jest-fusion-config.js
-import { setFusionConfiguration } from '@g_package/jest-cucumber-fusion'
+```text
+ FAIL  test/features/shopping-basket.steps.js
+  ● Test suite failed to run
-setFusionConfiguration( { tagFilter: '@smoke and not @slow' } )
+    Fusion found 1 step in the feature "Shopping basket" that no registered step definition matches.
+    ...
+      1. No step definition matches: "the product in my basket is a coffee mug"
+         And("the product in my basket is a coffee mug", () => {});
 ```
-```json
-"jest": {
-    "testMatch": [ "**/*.steps.js" ],
-    "setupFiles": [ "./jest-fusion-config.js" ]
-}
-```
-A per-call option still wins for its own file. See [Configuration options](./docs/AdditionalConfiguration.md) for every option and for the merge order.
-If you are coming from version 2, global configuration used to go through `jest-cucumber`'s own `setJestCucumberConfiguration`. That package is no longer a dependency, so the import moves to `setFusionConfiguration` from this package; the options object is the same shape.
-## Linting with ESLint
-[eslint-plugin-jest](https://github.com/jest-community/eslint-plugin-jest) gives ESLint Jest's globals, such as `expect`, and its rules. One rule needs to be told about Fusion. `jest/no-standalone-expect` reports every `expect` that is not inside a `test` or `it` block, and in a step definition file every `expect` sits inside `Then`, `And` or another step function instead. Each step function and each `Before` and `After` hook runs inside the test that Fusion makes for its scenario, so tell the rule to treat them as test blocks.
+### Run one scenario
-Install ESLint and the plugin:
+While you work on one scenario, you can run it alone. Each scenario is a Jest test named after it, so Jest's `-t` option selects it by name; the other tests are reported as skipped. `-t` takes a regular expression and matches it anywhere in the test's full name, so a short phrase can select several tests:
 ```
-npm install --save-dev eslint @eslint/js globals eslint-plugin-jest
+npm test -- -t "Adding a product"
 ```
-Then add an `eslint.config.js` to your project:
+To pick scenarios by tag instead, pass the tag filter from an environment variable:
 ```javascript
-//filename: eslint.config.js
-import js from '@eslint/js'
-import globals from 'globals'
-import jest from 'eslint-plugin-jest'
-export default [
-  js.configs.recommended,
-  {
-    languageOptions: { sourceType: 'module', globals: globals.node },
-  },
-  {
-    files: [ '**/*.steps.js' ],
-    ...jest.configs[ 'flat/recommended' ],
-    rules: {
-      ...jest.configs[ 'flat/recommended' ].rules,
-      // Fusion runs each step and hook inside the test it makes for the scenario.
-      'jest/no-standalone-expect': [ 'error', {
-        additionalTestBlockFunctions: [ 'Given', 'When', 'Then', 'And', 'But', 'Before', 'After' ],
-      } ],
-    },
-  },
-]
+Fusion( 'shopping-basket.feature', { tagFilter: process.env.TAGS } )
 ```
-Run it with `npx eslint .`. Without the `jest/no-standalone-expect` options, every `expect` in the steps file above is reported as `Expect must be inside of a test block`. With them, an `expect` that really is outside a step, a hook or a test is still reported.
+Then tag the scenario, on the line above it:
-If your shared step files are not named `*.steps.js` (see [Re-using step definitions](./docs/ReusingStepDefinitions.md)), add their names to `files`.
-## Using CommonJS instead
-Fusion ships a CommonJS build beside its ES modules: `require` gets the CommonJS build and `import` gets the ES modules. Use CommonJS if your project already is CommonJS, if you need Node 18 (CommonJS runs on Node 18.14 and newer), or if you would rather not run Jest's experimental ES module mode. CommonJS needs no Jest set-up at all.
-The steps in [Getting Started](#getting-started) work with these changes.
-**package.json.** Leave out `"type": "module"`, and run Jest directly:
-```json
-"scripts": { "test": "jest" },
-"jest": { "testMatch": [ "**/*.steps.js" ] }
+```gherkin
+@wip
+Scenario: Adding a product to an empty basket
 ```
-**The code under test** exports with `module.exports`:
-```javascript
-//filename: src/rocket.js
-class Rocket {
-    constructor() {
-        this.isInSpace = false
-        this.boostersLanded = false
-    }
+and run `TAGS=@wip npm test`. That form of setting a variable works in macOS and Linux shells; in Windows PowerShell, set `$env:TAGS = '@wip'` first, then run `npm test`. With `TAGS` unset, this call adds no filter of its own, so every scenario runs unless a [global configuration](./docs/AdditionalConfiguration.md#global-configuration) sets one. [Tag filtering](./docs/AdditionalConfiguration.md#tag-filtering) covers the expressions you can use, such as `@wip and not @slow`.
-    launch() {
-        this.isInSpace = true
-        this.boostersLanded = true
-    }
-}
+## Hooks
-module.exports = { Rocket }
-```
-**Step definition files** `require` the same names. A relative `require` may leave the extension out:
+`Before` and `After` run a function before or after every scenario of the `Fusion` call that follows them, which is the place to give each scenario a fresh start. With a `Before` hook, the steps above no longer need to create the basket:
 ```javascript
-//filename: test/features/rocket-launching.steps.js
-const { Given, When, Then, And, Fusion } = require( '@g_package/jest-cucumber-fusion' )
+import { Before, Given, When, Then, And, Fusion } from '@g_package/jest-cucumber-fusion'
-const { Rocket } = require( '../../src/rocket' )
-let rocket
+import { Basket } from '../../src/basket.js'
-Given( 'I am Elon Musk attempting to launch a rocket into space', () => {
-    rocket = new Rocket()
-} )
+let basket
-When( 'I launch the rocket', () => {
-    rocket.launch()
+Before( () => {
+    basket = new Basket()
 } )
-Then( 'the rocket should end up in space', () => {
-    expect(rocket.isInSpace).toBe(true)
+Given( 'my basket is empty', () => {
+    expect( basket.products ).toHaveLength( 0 )
 } )
-And( /^the booster\(s\) should land back on the launch pad$/, () => {
-    expect(rocket.boostersLanded).toBe(true)
+When( 'I add a coffee mug to my basket', () => {
+    basket.add( 'coffee mug' )
 } )
-And( 'nobody should doubt me ever again', () => {
-    expect('people').not.toBe('haters')
+Then( 'my basket holds 1 product', () => {
+    expect( basket.products ).toHaveLength( 1 )
 } )
+And( 'the product in my basket is a coffee mug', () => {
+    expect( basket.products[ 0 ] ).toBe( 'coffee mug' )
+} )
-Fusion( 'rocket-launching.feature' )
-```
-The `jest` object is a global, as in any CommonJS Jest project.
-**A global configuration script** `require`s `setFusionConfiguration`:
-```javascript
-//filename: jest-fusion-config.js
-const { setFusionConfiguration } = require( '@g_package/jest-cucumber-fusion' )
-setFusionConfiguration( { tagFilter: '@smoke and not @slow' } )
-```
-**ESLint.** The configuration file is CommonJS too, with `sourceType: 'commonjs'`:
-```javascript
-//filename: eslint.config.js
-const js = require( '@eslint/js' )
-const globals = require( 'globals' )
-const jest = require( 'eslint-plugin-jest' )
-module.exports = [
-  js.configs.recommended,
-  {
-    languageOptions: { sourceType: 'commonjs', globals: globals.node },
-  },
-  {
-    files: [ '**/*.steps.js' ],
-    ...jest.configs[ 'flat/recommended' ],
-    rules: {
-      ...jest.configs[ 'flat/recommended' ].rules,
-      // Fusion runs each step and hook inside the test it makes for the scenario.
-      'jest/no-standalone-expect': [ 'error', {
-        additionalTestBlockFunctions: [ 'Given', 'When', 'Then', 'And', 'But', 'Before', 'After' ],
-      } ],
-    },
-  },
-]
-```
-**Mixing the two styles** works. A CommonJS shared step library can serve ES module step files, and a CommonJS setup script can configure ES module steps: both styles share one set of step definitions and one global configuration. An ES module imports a CommonJS file by its full name, for example `import './shared-steps.cjs'`.
-The other pages in this documentation show ES modules. To use one of their examples in CommonJS, turn each `import { … } from '…'` into `const { … } = require( '…' )` and each `export` into `module.exports`.
-## Using TypeScript
-Fusion ships its type definitions, and TypeScript finds the right ones for ES modules and CommonJS with no configuration. To run step definition files written in TypeScript, Jest needs a transform. [ts-jest](https://kulshekhar.github.io/ts-jest/) is the usual one.
-```
-npm install --save-dev jest ts-jest typescript @types/jest @g_package/jest-cucumber-fusion
-```
-### ES modules (recommended)
-```json
-"type": "module",
-"scripts": {
-  "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
-  "typecheck": "tsc --noEmit"
-}
-```
-```json
-//filename: tsconfig.json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "isolatedModules": true,
-    "strict": true,
-    "types": [ "jest" ]
-  }
-}
-```
-```javascript
-//filename: jest.config.js
-export default {
-  preset: 'ts-jest/presets/default-esm',
-  testMatch: [ '**/*.steps.ts' ],
-  moduleNameMapper: { '^(\\.{1,2}/.*)\\.js$': '$1' },
-}
-```
-**Run `npm run typecheck` as well as `npm test`, for example in CI.** In ES module mode ts-jest only strips the types and does not check them, so a type error does not fail `npm test`; `tsc --noEmit` is what reports it. (`isolatedModules` tells ts-jest that this is expected. Without it, ts-jest warns `TS151002` and still does not check.)
-`moduleNameMapper` lets your imports keep the `.js` extension that ES modules need, while Jest loads the `.ts` file: `import { Rocket } from '../../src/rocket.js'` loads `src/rocket.ts`.
-### CommonJS
-Leave out `"type": "module"`, compile to CommonJS, and use ts-jest's default preset:
-```json
-"scripts": {
-  "test": "jest",
-  "typecheck": "tsc --noEmit"
-}
-```
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "CommonJS",
-    "strict": true,
-    "types": [ "jest" ]
-  }
-}
-```
-`"module": "CommonJS"` is what lets ts-jest check types here. With `NodeNext` or `Node16`, ts-jest warns `TS151002` and asks for `isolatedModules`, which would switch its checking off.
-```javascript
-//filename: jest.config.js
-module.exports = {
-  preset: 'ts-jest',
-  testMatch: [ '**/*.steps.ts' ],
-  moduleNameMapper: { '^(\\.{1,2}/.*)\\.js$': '$1' },
-}
-```
-Here ts-jest checks types while it runs the tests, so a type error fails `npm test` too.
-### Typed step definitions
-To move the [Getting Started](#getting-started) example to TypeScript, renaming its files to `.ts` is not enough under `strict`: `tsc --noEmit` then reports the `Rocket` class's fields as undeclared (`TS2339`) and `let rocket` as an implicit `any` (`TS7034`). Declare the fields in the class and write `let rocket: Rocket`, as the example below does. A step may also declare the type of each argument it receives: a capture or a docstring arrives as a `string`, and a data table as an `Array<Record<string, string>>` of its rows. For example, with this feature:
-```gherkin
-###filename: test/features/launch.feature
-Feature: Launch
-Scenario: Launching a batch of rockets
-  Given I am launching 3 rockets
-  When the countdown says
-    """
-    ignition
-    """
-  Then the manifest has
-    | name   |
-    | Falcon |
-```
-and this code under test:
-```typescript
-//filename: src/launch.ts
-export class Launch {
-    launched = 0
-    count: number
-    constructor( count: number ) {
-        this.count = count
-    }
-    countdown( word: string ): void {
-        if ( word === 'ignition' ) this.launched = this.count
-    }
-}
+Fusion( 'shopping-basket.feature' )
 ```
-the steps declare a `string` for the capture and the docstring, and the rows for the table:
+Register hooks, like step definitions, before the `Fusion` call. A hook may be `async`, and it receives nothing, so declare no parameters: Jest treats a declared parameter as a `done` callback and waits for it to be called.
-```typescript
-//filename: test/features/launch.steps.ts
-import { Given, When, Then, Fusion } from '@g_package/jest-cucumber-fusion'
+## If you know Cucumber
-import { Launch } from '../../src/launch.js'
+Most of Gherkin works as you expect: [`Background`](./docs/Background.md), [`Rule`](./docs/Rule.md), `Scenario Outline` with `Examples`, data tables, docstrings, tags and [80 languages](./docs/Language.md). The differences:
-let launch: Launch
+- **Steps bind by keyword.** An `And` step needs an `And` definition, as above. When one definition should serve several keywords, chain it: `Then( And( 'text', fn ) )` registers it under both.
+- **No Cucumber Expressions.** A string is compared as plain text, so `'I add {int} coffee mugs to my basket'` matches only that exact text. Use a regular expression to capture values: `/^I add (\d+) coffee mugs to my basket$/`.
+- **No `*` steps.** Because a step binds by its keyword, Fusion refuses a `*` step and asks you to write it with `Given`, `When`, `Then`, `And` or `But`.
+- **No World.** Steps are plain functions with no shared `this`. Share state through variables in the step definition file, and reset it in a `Before` hook.
+- **Hooks take no tags, and there is no `BeforeAll` or `AfterAll`.** `Before` and `After` run around every scenario of their `Fusion` call. For once-per-file set-up, use Jest's own `beforeAll` and `afterAll` at the top of the step definition file.
+- **Tags select scenarios through an option**, `tagFilter`, rather than a command-line flag: see [Configuration options](./docs/AdditionalConfiguration.md#tag-filtering). Jest's own `-t` filter also works, on scenario names.
-Given( /^I am launching (\d+) rockets$/, ( count: string ) => {
-    launch = new Launch( Number( count ) )
-} )
+## Where next
-When( 'the countdown says', ( words: string ) => {
-    launch.countdown( words.trim() )
-} )
+The [documentation index](./docs/README.md) suggests an order to read the guides in. In short:
-Then( 'the manifest has', ( rows: Array<Record<string, string>> ) => {
-    expect( rows ).toStrictEqual( [ { name: 'Falcon' } ] )
-    expect( launch.launched ).toBe( 3 )
-} )
+| To | Read |
+|---|---|
+| capture values from a step, or read a docstring | [Step definition arguments](./docs/StepDefinitionArguments.md) |
+| give every scenario the same first steps | [Background](./docs/Background.md) |
+| use a data table | [Gherkin tables](./docs/GherkinTables.md) |
+| run one scenario for every row of an `Examples` table | [Scenario outlines](./docs/ScenarioOutlines.md) |
+| group scenarios under a business rule | [Rule](./docs/Rule.md) |
+| share steps between feature files | [Re-using step definitions](./docs/ReusingStepDefinitions.md) |
+| filter by tag, name tests, or set options once for every file | [Configuration options](./docs/AdditionalConfiguration.md) |
+| use CommonJS, or Node 18 | [Using CommonJS](./docs/CommonJS.md) |
+| write step definitions in TypeScript | [Using TypeScript](./docs/TypeScript.md) |
+| lint step files with ESLint | [Linting with ESLint](./docs/ESLint.md) |
+| write feature files in another language | [Language](./docs/Language.md) |
+| upgrade from version 2 or 0.8.x | [Migrating to version 3](./docs/Migrating.md) |
-Fusion( 'launch.feature' )
-```
+## Coverage
-An argument you leave undeclared has the type `StepArgument` (`string | Array<Record<string, string>>`), which you can import from the package.
+Coverage works as in any Jest project, because Fusion's tests are Jest tests: run `npm test -- --coverage`. Jest already leaves the `*.steps.js` files out of the report; to leave out shared step files under `test/` as well, add `"coveragePathIgnorePatterns": [ "/node_modules/", "/test/" ]` to the `jest` key.
 ## Troubleshooting
-- **`SyntaxError: Unexpected token 'with'`** when Jest loads your ES module steps: your Node is older than 20.11, which ES module steps need. Upgrade Node, or [use CommonJS](#using-commonjs-instead), which runs from Node 18.14.
-- **`npm warn EBADENGINE` on Node 18**, naming `brace-expansion` or `lru-cache`: these come from Jest 30's own dependencies, not from Fusion. CommonJS steps still run on Node 18.14 and newer.
-- **ESLint on Node 18:** ESLint 10 itself needs Node 20.19 or newer. On Node 18.18 or newer, install ESLint 9 and the matching Jest plugin instead (`npm install --save-dev eslint@9 @eslint/js@9 eslint-plugin-jest@28 globals`); the configuration above works with them.
-- **`No step definition matches`** for a step you did define: the step's keyword decides which definitions it can bind to. An `And` step needs an `And(...)` definition (see [Getting Started](#add-a-cucumber-step-definition-file-and-load-fusion)).
+- **`Must use import to load ES Module`**: Jest ran without `--experimental-vm-modules`, so run the tests with `npm test`, not `npx jest`. If you did use `npm test`, a `.cjs` file `require`s an ES module, which Node before 24.9 cannot do (see [Mixing the two styles](./docs/CommonJS.md#mixing-the-two-styles)).
+- **`Cannot use import statement outside a module`**: `package.json` has no `"type": "module"`. Set it (see [Start a project](#start-a-project)), or name your files `.mjs`. On Jest 29 and older, Jest run without `--experimental-vm-modules` gives this message too: run the tests with `npm test`.
+- **`SyntaxError: Unexpected token 'with'`** when Jest loads your ES module steps: your Node cannot parse the import attributes in Fusion's ES modules (Node 18.19 and 20.9 fail; 20.11 is the oldest measured to work). Upgrade Node, or [use CommonJS](./docs/CommonJS.md), which runs from Node 18.14.
+- **`jest is not defined`**: in Jest's ES module mode the `jest` object (for `jest.fn()` and friends) is not a global. Add `@jest/globals` to your `devDependencies` and write `import { jest } from '@jest/globals'`.
+- **`No step definition matches`** for a step you did define: the step's keyword decides which definitions it can bind to. An `And` step needs an `And(...)` definition (see [Write the step definitions](#write-the-step-definitions)).
+- **`Your test suite must contain at least one test`**: the feature file is empty, or has a `Feature:` but no scenarios. Add a `Scenario`.
+- **`Error parsing feature Gherkin`**, with `expected: ... #FeatureLine`: the file has scenarios but no `Feature:` line. Add one before the first scenario.
+- **`Feature file not found`**: the path passed to `Fusion` is wrong. It is relative to the step definition file.
+- **`Exceeded timeout of 5000 ms for a test`**: the scenario's steps together took longer than Jest's timeout. Raise `"testTimeout"` in the `jest` key.
+- **A `Before` or `After` hook times out waiting for `done()`**: the hook declares a parameter. Remove it (see [Hooks](#hooks)).
+- **`Multiple configurations found`**: Jest found both a `jest` key in `package.json` and a `jest.config.js`. Keep one: see [Using TypeScript](./docs/TypeScript.md).
+- **`npm WARN EBADENGINE` on Node 18**, naming `brace-expansion` or `lru-cache`: these come from Jest 30's own dependencies, not from Fusion. CommonJS steps still run on Node 18.14 and newer.
 - **Jest prints only the summary, without the list of tests:** Jest shortens its output when it detects an AI agent's environment variables, such as `AI_AGENT` or `CLAUDECODE`. Run it from a terminal that does not have them.
-## Additional Documentation
-Using the package:
-  * [Step definition arguments](./docs/StepDefinitionArguments.md)
-  * [Gherkin tables](./docs/GherkinTables.md)
-  * [Scenario outlines](./docs/ScenarioOutlines.md)
-  * [Re-using step definitions](./docs/ReusingStepDefinitions.md)
-  * [Language](./docs/Language.md)
-  * [Configuration options](./docs/AdditionalConfiguration.md): every export and option
-  * [Migrating to version 3](./docs/Migrating.md)
-Working on the package:
-  * [Running the examples](./docs/RunningTheExamples.md)
-  * [Architecture](./docs/Architecture.md)
-Every example on the guide pages above runs as written: the repository's tests copy each one into a fresh project and run it.
+Still stuck, or found a bug? [Open an issue](https://github.com/gotreasa/jest-cucumber-fusion/issues/new/choose).

package/dist/index.d.cts CHANGED Viewed

@@ -92,18 +92,21 @@ export interface FusionOptions {
    * they are compared, so the operators may be written in any case too.
    *
    * A scenario is selected on the tags its compiled pickle carries, which is the union of the
-   * scenario's own tags, its feature's tags and, for a Scenario Outline row, that Examples
-   * set's tags. A scenario the expression excludes is registered through `test.skip` under its
-   * own unannotated name, so Jest reports it as skipped: never run, and never absent from the
-   * report. Its steps are also exempt from the unmatched-step check, because a scenario you
+   * scenario's own tags, its `Rule`'s tags, its feature's tags and, for a Scenario Outline row,
+   * that Examples set's tags. A scenario the expression excludes is registered through `test.skip`
+   * under its own unannotated name, so Jest reports it as skipped: never run, and never absent from
+   * the report. Its steps are also exempt from the unmatched-step check, because a scenario you
    * excluded is not one you are asking to have wired. They are still read, so a step with an
    * unsupported keyword (`*`) or one that matches two definitions is refused all the same.
    *
    * An expression that cannot be parsed is refused at collection, before anything is
    * registered, and the refusal names the expression you wrote. So is one with an operand
    * that is not a tag, such as `smoke` written for `@smoke`: it could never match.
+   *
+   * `null` means no filter. Unlike `undefined`, which counts as not set, it is a value, so
+   * `{ tagFilter: null }` on one call clears a filter set by `setFusionConfiguration`.
    */
-  tagFilter?: string;
+  tagFilter?: string | null;
   /**
    * Renames every test Fusion registers, Scenario Outline rows included. It is called once per
    * test while Fusion registers, never again while the tests run, and it names a test whatever
@@ -136,8 +139,9 @@ export function Fusion(feature: string, options?: FusionOptions): void;
  * as `{ tagFilter: process.env.TAGS }`, counts as not set and leaves the layer below in place.
  *
  * A second call REPLACES what the first set rather than merging into it, which is what lets a
- * global be cleared or redefined. Jest gives each test file its own module registry and runs
- * `setupFiles` inside it, so what is set here cannot reach another file.
+ * global be cleared or redefined. Jest gives each test file its own global object and runs
+ * `setupFiles` inside it. The configuration lives on that global, not in a module, so what is
+ * set here cannot reach another file, and `jest.resetModules()` does not clear it.
  *
  * An argument that is not an options object is refused where it is called, before any step
  * definition file has loaded. An unknown key is accepted and ignored, exactly as it is per call.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@g_package/jest-cucumber-fusion",
-  "version": "3.0.3",
+  "version": "3.0.5",
   "description": "Write cucumber test as part of a jest run (including coverage)",
   "type": "module",
   "main": "dist/index.cjs",
@@ -16,7 +16,7 @@
   "scripts": {
     "pretest": "npm run build",
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --color",
-    "test-d": "tsd",
+    "test-d": "tstyche",
     "test:baseline": "node test/specs/baseline/run-all.js",
     "coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
     "lint": "eslint . --max-warnings 0",
@@ -51,6 +51,7 @@
     "@eslint/js": "^10.0.1",
     "@secretlint/secretlint-rule-pattern": "^13.0.7",
     "@secretlint/secretlint-rule-preset-recommend": "^13.0.7",
+    "@semantic-release/exec": "^7.1.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^18.19.130",
     "czg": "1.14.0",
@@ -62,16 +63,19 @@
     "husky": "^9.1.7",
     "jest": "^30.4.2",
     "lint-staged": "^17.6.0",
-    "prettier": "3.9.9",
+    "prettier": "3.9.10",
     "secretlint": "^13.0.7",
     "semantic-release": "^25.0.5",
-    "tsd": "^0.33.0",
+    "tstyche": "^7.2.5",
     "typescript": "^6.0.3"
   },
   "publishConfig": {
     "access": "public"
   },
   "release": {
+    "branches": [
+      "main"
+    ],
     "plugins": [
       "@semantic-release/commit-analyzer",
       "@semantic-release/release-notes-generator",
@@ -79,7 +83,13 @@
         "@semantic-release/github",
         {
           "successComment": false,
-          "failComment": false
+          "failComment": false,
+          "assets": [
+            {
+              "path": "release/*.cdx.json",
+              "label": "SBOM (CycloneDX)"
+            }
+          ]
         }
       ],
       [
@@ -88,6 +98,12 @@
           "npmPublish": false,
           "tarballDir": "release"
         }
+      ],
+      [
+        "@semantic-release/exec",
+        {
+          "prepareCmd": "npm sbom --sbom-format cyclonedx --omit dev --package-lock-only > release/jest-cucumber-fusion-${nextRelease.version}.cdx.json"
+        }
       ]
     ],
     "parserOpts": {

package/src/index.d.ts CHANGED Viewed

@@ -92,18 +92,21 @@ export interface FusionOptions {
    * they are compared, so the operators may be written in any case too.
    *
    * A scenario is selected on the tags its compiled pickle carries, which is the union of the
-   * scenario's own tags, its feature's tags and, for a Scenario Outline row, that Examples
-   * set's tags. A scenario the expression excludes is registered through `test.skip` under its
-   * own unannotated name, so Jest reports it as skipped: never run, and never absent from the
-   * report. Its steps are also exempt from the unmatched-step check, because a scenario you
+   * scenario's own tags, its `Rule`'s tags, its feature's tags and, for a Scenario Outline row,
+   * that Examples set's tags. A scenario the expression excludes is registered through `test.skip`
+   * under its own unannotated name, so Jest reports it as skipped: never run, and never absent from
+   * the report. Its steps are also exempt from the unmatched-step check, because a scenario you
    * excluded is not one you are asking to have wired. They are still read, so a step with an
    * unsupported keyword (`*`) or one that matches two definitions is refused all the same.
    *
    * An expression that cannot be parsed is refused at collection, before anything is
    * registered, and the refusal names the expression you wrote. So is one with an operand
    * that is not a tag, such as `smoke` written for `@smoke`: it could never match.
+   *
+   * `null` means no filter. Unlike `undefined`, which counts as not set, it is a value, so
+   * `{ tagFilter: null }` on one call clears a filter set by `setFusionConfiguration`.
    */
-  tagFilter?: string;
+  tagFilter?: string | null;
   /**
    * Renames every test Fusion registers, Scenario Outline rows included. It is called once per
    * test while Fusion registers, never again while the tests run, and it names a test whatever
@@ -136,8 +139,9 @@ export function Fusion(feature: string, options?: FusionOptions): void;
  * as `{ tagFilter: process.env.TAGS }`, counts as not set and leaves the layer below in place.
  *
  * A second call REPLACES what the first set rather than merging into it, which is what lets a
- * global be cleared or redefined. Jest gives each test file its own module registry and runs
- * `setupFiles` inside it, so what is set here cannot reach another file.
+ * global be cleared or redefined. Jest gives each test file its own global object and runs
+ * `setupFiles` inside it. The configuration lives on that global, not in a module, so what is
+ * set here cannot reach another file, and `jest.resetModules()` does not clear it.
  *
  * An argument that is not an options object is refused where it is called, before any step
  * definition file has loaded. An unknown key is accepted and ignored, exactly as it is per call.