|
| 1 | +<h1 align="center"> |
| 2 | + <img alt="" width="75" src="./logo.svg"/> |
| 3 | + <br> |
| 4 | + cucumber-node |
| 5 | +</h1> |
| 6 | +<p align="center"> |
| 7 | + <b>Automated tests in plain language, for the Node.js test runner</b> |
| 8 | +</p> |
| 9 | + |
| 10 | +[Cucumber](https://github.com/cucumber) is a tool for running automated tests written in plain language. Because they're |
| 11 | +written in plain language, they can be read by anyone on your team. Because they can be |
| 12 | +read by anyone, you can use them to help improve communication, collaboration and trust on |
| 13 | +your team. |
| 14 | + |
| 15 | +⚠️ This is a new implementation of Cucumber built around the [Node.js test runner](https://nodejs.org/api/test.html). It's still in the pre-1.0.0 phase, so APIs and behaviour might change. The stable canonical implementation of Cucumber for JavaScript continues to be [@cucumber/cucumber](https://github.com/cucumber/cucumber-js) for now. ⚠️ |
| 16 | + |
| 17 | +## Install |
| 18 | + |
| 19 | +cucumber-node is [available on npm](https://www.npmjs.com/package/@cucumber/node): |
| 20 | + |
| 21 | +```shell |
| 22 | +npm install --save-dev @cucumber/node |
| 23 | +``` |
| 24 | + |
| 25 | +You'll need Node.js 22 or 23. |
| 26 | + |
| 27 | +## Get started |
| 28 | + |
| 29 | +Say we have this small class: |
| 30 | + |
| 31 | +```js |
| 32 | +export class Greeter { |
| 33 | + sayHello() { |
| 34 | + return 'hello' |
| 35 | + } |
| 36 | +} |
| 37 | +``` |
| 38 | + |
| 39 | +Let's write a feature file specifying how it should work, in `features/greeting.feature`: |
| 40 | + |
| 41 | +```gherkin |
| 42 | +Feature: Greeting |
| 43 | +
|
| 44 | + Scenario: Say hello |
| 45 | + When the greeter says hello |
| 46 | + Then I should have heard "hello" |
| 47 | +``` |
| 48 | + |
| 49 | +Next, we need to provide automation to turn that spec into tests, in `features/support/steps.js`: |
| 50 | + |
| 51 | +```js |
| 52 | +import assert from 'node:assert' |
| 53 | +import { When, Then } from '@cucumber/node' |
| 54 | +import { Greeter } from '../../lib/Greeter.js' |
| 55 | + |
| 56 | +When('the greeter says hello', (t) => { |
| 57 | + t.world.whatIHeard = new Greeter().sayHello() |
| 58 | +}); |
| 59 | + |
| 60 | +Then('I should have heard {string}', (t, expectedResponse) => { |
| 61 | + assert.equal(t.world.whatIHeard, expectedResponse) |
| 62 | +}); |
| 63 | +``` |
| 64 | + |
| 65 | +Finally, run `node --test` with some special arguments: |
| 66 | + |
| 67 | +```shell |
| 68 | +node --import @cucumber/node/bootstrap --test-reporter=dot --test 'features/**/*.feature' |
| 69 | +``` |
| 70 | + |
| 71 | +## Running tests |
| 72 | + |
| 73 | +Since cucumber-node augments the standard Node.js test runner, you can use many of its options in the same way you would when running tests written in JavaScript, like: |
| 74 | + |
| 75 | +- 🔀 [`--test-concurrency`](https://nodejs.org/api/cli.html#--test-concurrency) to control the number of concurrent processes |
| 76 | +- 🏃 [`--test-force-exit`](https://nodejs.org/api/cli.html#--test-force-exit) to forcibly exit once all tests have executed |
| 77 | +- 😷 [`--test-isolation=none`](https://nodejs.org/api/cli.html#--test-isolationmode) to have all tests run in a single process |
| 78 | +- 🔍 [`--test-name-pattern`](https://nodejs.org/api/cli.html#--test-name-pattern) to target some scenarios by name |
| 79 | +- 💎 [`--test-shard`](https://nodejs.org/api/cli.html#--test-shard) to shard execution across multiple runs/environments |
| 80 | +- ⏩ [`--test-skip-pattern`](https://nodejs.org/api/cli.html#--test-skip-pattern) to omit some scenarios by name |
| 81 | +- 👀 [`--watch`](https://nodejs.org/api/cli.html#--watch) to watch for changes and automatically re-run |
| 82 | + |
| 83 | +(In all cases you still need the `--import @cucumber/node/bootstrap` so that cucumber-node kicks in when a feature file is encountered.) |
| 84 | + |
| 85 | +## Writing steps |
| 86 | + |
| 87 | +Full API documentation is at https://cucumber.github.io/cucumber-node/ and includes: |
| 88 | + |
| 89 | +- `Before` and `After` for hooks |
| 90 | +- `Given`, `When` and `Then` for steps |
| 91 | +- `ParameterType` for custom parameter types |
| 92 | + |
| 93 | +## Reporters |
| 94 | + |
| 95 | +Some Cucumber formatters are included as Node.js test reporters: |
| 96 | + |
| 97 | +- HTML - `--test-reporter=@cucumber/node/reporters/html --test-reporter-destinaton=./report.html` |
| 98 | +- Message - `--test-reporter=@cucumber/node/reporters/message --test-reporter-destinaton=./messages.ndjson` |
0 commit comments