Registry / testing / it-each

it-each

JSON →
library0.5.0jsnpmunverified

it-each is a JavaScript module designed to extend Mocha's testing capabilities by enabling asynchronous test looping. It allows developers to iterate over data sets, executing a test case for each item with configurable titles and data extraction. The package, currently at version 0.5.0, explicitly states it is below v1.0.0 due to an unclear roadmap, implying potential breaking changes, though stability is aimed for. It operates by modifying Mocha's global `it` handler and works with Mocha v2.1.0 and likely newer versions, though no guarantees are made for future compatibility. Key features include automatic adjustment of `timeout` and `slow` values for collective tests, and an option (`testPerIteration`) to generate a separate test entry for each iteration, which helps in isolating failures. Its primary differentiator is its simplicity and direct integration into Mocha's existing `it` interface, making it easy to adapt existing tests for data-driven scenarios.

testing
npm install it-each
github ↗package ↗
INSTALL
IMPORT
SIG · IT-EACH
I
it-each
testingjavascriptv0.5.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

it.each
✓ require('it-each')(); // it.each is then available globally or via Mocha's `it` context
✗ import { each } from 'it-each';
This module uses CommonJS `require` and extends Mocha's global `it` object upon invocation. It does not provide named exports for ESM `import` statements. The function returned by `require('it-each')` must be called to enable the functionality.
it.each with options
✓ require('it-each')({ testPerIteration: true });
✗ const itEach = require('it-each'); itEach.testPerIteration = true;
Configuration options like `testPerIteration` are passed as an object to the initial invocation of the module. This call can be made multiple times to update settings across different test suites.
it.each.skip
✓ it.each.skip(iterable, title, fields, process);
✗ it.skip.each(iterable, title, fields, process);
Similar to Mocha's `it.skip`, `it.each.skip` is available for skipping entire `it.each` blocks.

This quickstart demonstrates how to set up `it-each` in a Mocha test file, iterating over an array of user data. It shows both an asynchronous `process` function using `next()` and a synchronous one, along with how to enable `testPerIteration` for granular test reporting.

const assert = require('assert'); const { expect } = require('chai'); // Require and activate it-each before your test suites require('it-each')(); describe('User Data Processing', () => { const users = [ { id: 1, name: 'Alice', age: 30, email: 'alice@example.com' }, { id: 2, name: 'Bob', age: 24, email: 'bob@example.com' }, { id: 3, name: 'Charlie', age: 35, email: 'charlie@example.com' } ]; // Asynchronous function to simulate a database call async function fetchUserData(userId) { return new Promise(resolve => { setTimeout(() => { const user = users.find(u => u.id === userId); resolve(user ? { ...user, fetchedAt: new Date() } : null); }, 50); }); } it.each(users, 'should process user %s correctly', ['name'], async (user, next) => { const fetchedUser = await fetchUserData(user.id); expect(fetchedUser).to.not.be.null; expect(fetchedUser.name).to.equal(user.name); expect(fetchedUser.age).to.be.at.least(20); console.log(`Processed user: ${fetchedUser.name} (Fetched at: ${fetchedUser.fetchedAt.toLocaleTimeString()})`); next(); // IMPORTANT: Call next() for async tests with a callback signature }); // Example with testPerIteration: true describe('Individual User Age Validation', () => { require('it-each')({ testPerIteration: true }); // Enable per-iteration tests for this suite const ageData = [ { name: 'David', age: 18, expectedAdult: false }, { name: 'Eve', age: 25, expectedAdult: true } ]; it.each(ageData, 'User %s should have adult status as %s', ['name', 'expectedAdult'], (data) => { expect(data.age >= 18).to.equal(data.expectedAdult); }); }); });
Debug
Known issues
gotchaThe `it-each` module is currently below v1.0.0 and explicitly states that breaking changes are possible, although they are avoided where possible. Its roadmap is unclear.
fix
Monitor the project's GitHub repository for updates and test thoroughly when upgrading to new patch versions, as they might introduce unexpected behavior changes given the pre-1.0.0 status.
affects: >=0.1.0
gotcha`it-each` is confirmed to work with Mocha v2.1.0, but compatibility with future major versions of Mocha is not guaranteed by the maintainers.
fix
Ensure you test your `it-each` based tests thoroughly when upgrading your Mocha version. If compatibility issues arise, consider pinning an older Mocha version or exploring alternatives like `mocha-each` or `jest-each` (if migrating to Jest).
affects: >=0.1.0
gotchaIf the `process` function provided to `it.each` is asynchronous and includes `next` in its parameter list, `next()` MUST be called to signal completion of the test iteration. Forgetting to call `next()` will cause the test to time out.
fix
Always call `next()` when using asynchronous operations within your `process` function, typically after all async tasks are resolved, similar to how Mocha's `done` callback is used. If `next` is not in the parameters, the function is treated as synchronous.
affects: >=0.1.0
gotchaWhen `testPerIteration` is `false` (the default), Mocha's `timeout` and `slow` values for the test are multiplied by the number of elements in the array. This prevents premature timeouts but can mask performance issues in individual iterations.
fix
For clearer feedback on individual test performance and easier debugging of specific iterations, consider setting `testPerIteration: true` in `require('it-each')({ testPerIteration: true })`. This generates a separate test entry for each iteration.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: it.each is not a function
The `it-each` module exports a function that must be invoked immediately to extend Mocha's `it` handler.
fix
Ensure you are calling `require('it-each')()` as a function, rather than just `require('it-each')`. For example: `require('it-each')();`
Timeout of 2000ms exceeded. For more information see https://mochajs.org/...
This Mocha timeout error typically occurs when an asynchronous `process` function passed to `it.each` fails to call its `next` callback, preventing Mocha from knowing the test has completed.
fix
Verify that your `process` function, if it contains asynchronous operations (e.g., Promises, `async/await`), correctly calls the `next()` callback after all operations have finished.
ReferenceError: it is not defined
`it-each` relies on the global `it` function provided by Mocha. This error indicates that `it-each` was either required before Mocha was loaded or the test file is not being run within a Mocha test runner context.
fix
Ensure that Mocha is properly installed and your test files are executed using the Mocha test runner (e.g., `mocha your-test-file.js`). Also, ensure `require('it-each')()` is called after Mocha has been 'instantiated' or loaded in your test environment.
Upgrade
Version history
0.5.0latest on npm
Audit
Dependencies
mocharequiredit-each extends Mocha's 'it' handler and requires Mocha to be loaded in the test environment to function.
Agent activity
4 hits · last 30 days
node
4
Resources
githubhttps://github.com/whitfin/it.each ↗
packagehttps://www.npmjs.com/package/it-each ↗