Mocha Cakes 2

Mocha Cakes is a Gherkin/Cucumber syntax integration for the Mocha testing framework.

Installation

NPM:

npm install --save-dev @bonniernews/mocha-cakes-2

Requirements

• Node.js 22.12 or later
• Mocha 11 or 12 (mocha is a peer dependency: mocha >= 11)

Mocha Cakes 2 is tested on Node.js 22, 24 and 26 with Mocha 11 and 12.

If you're on an older version of Node.js or Mocha, use [email protected].

Usage

Enable the @bonniernews/mocha-cakes-2 integration

To enable the Mocha integration you need to specify @bonniernews/mocha-cakes-2 in the ui option.

CLI

Either use the command line argument:

mocha --ui @bonniernews/mocha-cakes-2 path/to/my/tests

Or set it in your Mocha configuration file, e.g. .mocharc.json:

{
  "ui": "@bonniernews/mocha-cakes-2"
}

Or .mocharc.yml:

ui: "@bonniernews/mocha-cakes-2"

API

Either pass it in the options as you construct Mocha:

var Mocha = require('mocha');
// Mocha 12 is an ES module, so `require()` returns its namespace object
Mocha = Mocha.default || Mocha;

var mocha = new Mocha({
  ui: '@bonniernews/mocha-cakes-2'
});

Or set it after you've constructed Mocha:

var mocha = new Mocha();
mocha.ui('@bonniernews/mocha-cakes-2')

Test structure

require('chai').should();

Feature('Some feature', () => {

  Scenario('Some Scenario', () => {

    let number = 2;

    Given('a number', () => {
      number.should.exist;
    });
    And('that number is 2', () => {
      number.should.equal(2);
    });

    When('adding 40', () => {
      number += 40;
    });

    Then('the number should be 42', () => {
      number.should.equal(42);
    });
  });
});

The result will look something like this:

The common Mocha functions (describe, it, before, after, etc) are also available and can be used together with Mocha Cakes.

Upgrading from mocha-cakes-2 3.x

Replace the mocha-cakes-2 dependency with @bonniernews/mocha-cakes-2 and change the ui option to @bonniernews/mocha-cakes-2. The old mocha-cakes-2 ui name still works if the package is loaded with --require @bonniernews/mocha-cakes-2.

Upgrading from version 1.x

Replace the require('mocha-cakes-2') statement(s) with the --ui @bonniernews/mocha-cakes-2 option as described above.

TypeScript

The TypeScript definitions are bundled together with @bonniernews/mocha-cakes-2. To use mocha directly with TypeScript you need types for mocha and ts-node.

npm install --save-dev typescript ts-node @types/mocha

You should have a tsconfig.json in the root of your project like so

{
  "compilerOptions": {
    "module": "commonjs",
    "moduleResolution": "node"
  }
}

Now you can run it like so:

mocha -r ts-node/register --ui @bonniernews/mocha-cakes-2  ...

Your tests should look like this:

import '@bonniernews/mocha-cakes-2';

Feature('Some feature', () => {

  Scenario('Some Scenario', () => {

    let number = 2;

    Given('a number', () => {

    });
    And('that number is 2', () => {

    });

    When('adding 40', () => {

    });

    Then('the number should be 42', () => {

    });
  });
});

API

The Mocha Cakes integration adds the following functions to the global scope:

• Feature | feature
  • Scenario | scenario
    • Given | given
    • When | when
    • Then | then
    • And | and
    • But | but

.skip

Skips a test clause. Works on all test functions.

Mocha's --forbid-pending option is respected.

Feature('Some feature', () => {

  Scenario.skip('Skipped scenario', () => {
    // ...
  });

  Scenario('Ordinary', () => {
    // ...
  });
});

.only

Only run the specified test clause. Works on all test functions.

Multiple .only clauses are combined, just like Mocha's describe.only and it.only, and Mocha's --forbid-only and --grep options are respected.

Feature('Some feature', () => {

  Scenario('First scenario', () => {
    // ...
  });

  Scenario('Second scenario', () => {
    // ...
  });

  Scenario.only('Only I will run!', () => {
    // ...
  });

  // ...
});

beforeEachScenario and afterEachScenario

Executes the provided function only once for each of the scenarios under the current scope.

Feature('Some feature', () => {

  beforeEachScenario( () => {
    someSetup();
  });

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

  Scenario('First scenario', () => {
    // ...
  });

  Scenario('Second scenario', () => {
    // ...
  });

  // ...
});

beforeEachFeature and afterEachFeature

Executes the provided function only once for each of the features under the current scope.

beforeEachFeature( () => {
  someSetup();
});

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

Feature('Some feature', () => {
  // ...
});

Feature('Another feature', () => {
  // ...
});

// ...

Development

Run the tests with:

npm test

This runs the test suite twice, once using Mocha's CLI and once using Mocha's API (see below).

Continuous integration

The tests are run by GitHub Actions on Node.js 22, 24 and 26 with both Mocha 11 and Mocha 12.

Testing against Mocha 11

Mocha 12 is installed as a development dependency. To run the tests against Mocha 11 locally, install it without saving it to package.json:

npm install --no-save mocha@11 && npm test

Run npm install to go back to Mocha 12.

Testing the CLI and API interfaces

If you use Mocha directly to run the tests you can set the MOCHA_INTERFACE environment variable to either cli or api to choose which Mocha interface to run the tests with. The api interface runs the sample tests in the same process, so it also needs --require ./mocha-cakes.js:

MOCHA_INTERFACE=cli npx mocha test/feature/tests.js
MOCHA_INTERFACE=api npx mocha --require ./mocha-cakes.js test/feature/tests.js

MOCHA_INTERFACE will default to cli if no value is set.

When you run npm run test:cli or npm run test:api (or npm test to run them both), MOCHA_INTERFACE is set automatically to the appropriate value.

Acknowledgements

Mocha Cakes 2 is heavily influenced by quangv's mocha-cakes.