Parameterized Tests for Mocha

2.0.1 · active · verified Sun Apr 19

mocha-each is a utility for the Mocha testing framework that simplifies the creation of parameterized tests. It allows developers to define a single test case that runs multiple times with varying sets of input data, significantly reducing code duplication and enhancing test coverage. The current stable version is 2.0.1. While specific release cadence isn't explicitly stated, the project appears to be stable and maintained, with the latest version indicating ongoing support. Its primary differentiator is the seamless integration of data-driven testing within Mocha's existing `it` and `describe` syntax, making it straightforward to iterate over arrays of test data. A key feature is its guarantee that all parameterized test cases are executed, even if some individual cases fail, which is crucial for comprehensive test reporting. It also supports parameterization at the `describe` block level and handles asynchronous test cases effectively.

Common errors

```
TypeError: (0, _mochaEach.default) is not a function
```
cause Attempting to use a default ESM import (`import forEach from 'mocha-each';`) when the module is primarily CommonJS and transpilation/bundling does not correctly handle it.

fix Change your import statement to `const forEach = require('mocha-each');` which is the officially documented and most reliable way to import the package.
```
ReferenceError: forEach is not defined
```
cause The `forEach` function was not correctly imported or required into the test file before being used.

fix Ensure you have `const forEach = require('mocha-each');` at the top of your test file or within the appropriate scope.
```
Error: Timeout of 2000ms exceeded. For async tests and hooks, ensure "done()" is called; if returning a Promise, ensure it resolves.
```
cause An asynchronous parameterized test did not signal its completion, either by not calling the `done()` callback or by not returning a Promise that resolves.

fix For callback-style async tests, add `done` as the last argument to your test function and call `done()` when the async operation finishes. For Promise-based async tests, ensure your test function returns the Promise.

Warnings

gotcha When using `.only()` or `.skip()` on `forEach` blocks, be aware that Mocha's native behavior for these modifiers applies. If multiple `forEach` blocks are marked with `.only()`, only the last one encountered by Mocha might actually run, potentially leading to missed tests. `mocha-each` wraps `.only()` in a nameless `describe` block to ensure its parameters are exclusive, but global interaction needs care.
Fix: Use `.only()` sparingly and verify that all intended tests are executed. For isolating specific tests, consider running individual test files or using other Mocha filtering options.
gotcha `mocha-each` version 2.x is primarily designed for CommonJS (`require`). While some environments might allow ESM `import forEach from 'mocha-each'`, it's not explicitly documented or guaranteed. Using named imports for CommonJS modules (e.g., `import { forEach } from 'mocha-each';`) will likely fail.
Fix: For consistent behavior, especially in Node.js environments, stick to `const forEach = require('mocha-each');`. If you need full ESM support, check for a newer major version of `mocha-each` or use a different parameterized testing library that explicitly supports ESM.
gotcha When defining parameterized tests with asynchronous code, it's crucial to explicitly call the `done()` callback or return a Promise within your test function. Failing to do so will result in tests timing out or completing prematurely without proper assertion, leading to false positives or test failures.
Fix: Ensure your async test case function accepts `done` as its last argument (e.g., `(arg1, arg2, done) => { ... }`) and calls `done()` upon completion, or alternatively, ensure the function returns a Promise that resolves when the asynchronous operation is complete.

Install

npm install mocha-each npm
yarn add mocha-each yarn
pnpm add mocha-each pnpm

Imports

forEach
wrong:
```
const { forEach } = require('mocha-each');
```
correct:
```
import forEach from 'mocha-each';
```
The package primarily uses CommonJS `require` as shown in documentation, but a default ESM import may work in some environments. Named imports for CommonJS are incorrect.
forEach (CommonJS)
```
const forEach = require('mocha-each');
```
This is the documented and most reliable way to import `mocha-each` in Node.js environments, especially for older projects or those not configured for ESM.

Quickstart

Demonstrates how to use `mocha-each` to run a simple parameterized test for an `add` function with different input sets, verifying both valid and invalid arguments within a Mocha test suite.

const assert = require('assert');
const forEach = require('mocha-each');

function add(a, b) {
  return parseInt(a) + parseInt(b);
}

describe('add()', () => {
  forEach([
    [1, 1, 2],
    [2, -2, 0],
    [140, 48, 188]
  ])
  .it('adds %d and %d then returns %d', (left, right, expected) => {
    assert.equal(add(left, right), expected);
  });

  context('with invalid arguments', () => {
    forEach([
      [1, 'foo'],
      [null, 10],
      [{}, []]
    ])
    .it('adds %j and %j then returns NaN', (left, right) => {
      const value = add(left, right);
      assert(isNaN(value));
    });
  });
});

view raw JSON →