@bonniernews/node-test-bdd

Node Test BDD is a Gherkin/Cucumber-style testing framework for Node.js, designed to work seamlessly with the Node test runner.

It serves as a drop-in replacement for Mocha Cakes 2 for users transitioning from Mocha to Node's native test runner.

🚀 Quick Start

Install the package:

npm install --save-dev @bonniernews/node-test-bdd

Write your first test:

import assert from "node:assert";
import { Feature, Scenario, Given, When, Then } from "@bonniernews/node-test-bdd";

Feature("Basic Math", () => {
  Scenario("Incrementing a number", () => {
    let number = 1;

    Given("I have a number 1", () => {
      assert.strictEqual(number, 1);
    });

    When("I add 1", () => {
      number += 1;
    });

    Then("The number should be 2", () => {
      assert.strictEqual(number, 2);
    });
  });
});

Run the test using Node's built-in test runner:

node --test

The output should look like this:

Installation

Install as a development dependency:

npm install --save-dev @bonniernews/node-test-bdd

Usage

Node Test BDD provides Gherkin-style syntax for defining tests:

import assert from "node:assert";
import { Feature, Scenario, Given, When, Then, And } from "@bonniernews/node-test-bdd";

Feature("Example feature", () => {
  Scenario("Example scenario", () => {
    let number;
    Given("I have a number", () => {
      number = 1;
    });
    And("That number is 1", () => {
      assert.ok(number === 1);
    });
    When("Adding 1 to that number", () => {
      number += 1;
    });
    Then("The number should be 2", () => {
      assert.ok(number === 2);
    });
  });
});

Register the BDD test functions globally

To avoid importing BDD functions in every test file, you can register them globally:

Option 1: Import in your test setup file

import "@bonniernews/node-test-bdd/register-bdd";

Option 2: Import dynamically when running tests

node --test --import '@bonniernews/node-test-bdd/register-bdd'

API

Node Test BDD provides the following test functions:

• Feature(description, fn)
  • Scenario(description, fn)
    • Given(description, fn)
    • When(description, fn)
    • Then(description, fn)
    • And(description, fn)
    • But(description, fn)

Scenario Hooks

You can use hooks to set up and clean up before and after each scenario.

Feature("Some feature", () => {
  beforeEachScenario(() => {
    someSetup();
  });

  afterEachScenario(() => {
    doCleanup();
  });

  Scenario("First scenario", () => {
    // Test logic...
  });

  Scenario("Second scenario", () => {
    // Test logic...
  });
});

Migrating from Mocha

If your Mocha test suite runs sequentially (without parallelism), you should consider setting the --experimental-test-isolation flag to none.

This ensures that:

• All test files run in the same process as the test runner.
• The --test-concurrency flag is automatically set to 1, mimicking Mocha’s default behavior.

Mocha vs. Node.js Test Runner Options

Mocha Option	Equivalent in Node.js Test Runner
--exit	--test-force-exit
--grep	--test-name-pattern
--reporter	--test-reporter
--require	--import
--timeout	--test-timeout