Registry / testing / unroll

unroll

JSON →
library0.1.0jsnpmunverified

Unroll is a JavaScript helper library designed to simplify parameterized testing across both browser and Node.js environments. Currently at version 1.6.0, it allows developers to run a single test function against multiple sets of data, drawing inspiration from the 'Unroll annotation' found in the Spock framework for Java. It offers a structured way to define test data, either through an array of arrays or using a multiline template literal, enhancing test clarity and reducing redundancy. Unroll functions by decorating the primary test function (e.g., `it` in Mocha/Jasmine, `test` in AVA/Tape) of various testing frameworks, making it highly adaptable. The library's release cadence is intermittent, driven by bug fixes and minor feature enhancements, with its latest stable release focusing on improving argument handling and overall robustness. Its core value proposition lies in providing a framework-agnostic solution for data-driven tests, enabling detailed output for each test iteration.

testing
npm install unroll
github ↗package ↗
INSTALL
IMPORT
SIG · UNROLL
U
unroll
testingjavascriptv0.1.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.

unroll
✓ const unroll = require('unroll');
✗ import unroll from 'unroll';
Primarily designed for CommonJS. While an ESM import might work, `require` is the documented and most reliable method shown in examples.
unroll.use
✓ unroll.use(it);
✗ unroll(it);
The `use` method must be called once to configure `unroll` with your testing library's main test function (e.g., `it`, `test`).
testArgs
✓ function(done, testArgs) { console.log(testArgs['a']); }
✗ function(done, a, b) { console.log(a); }
Parameters are passed as a single `testArgs` object, which is an object mapping parameter names (from the test title) to their values. Do not expect individual arguments.

Demonstrates how to integrate `unroll` with a testing framework (mocked `it` function), define parameterized tests using template literals, and access parameters via the `testArgs` object. It also highlights the need for `JSON.stringify` for complex types in template literals.

const unroll = require('unroll'); const { expect } = require('chai'); // Example assertion library // Mock your testing framework's 'it' or 'test' function const it = (name, fn) => { console.log(`Running test: ${name}`); // For a real test runner, 'done' would be handled asynchronously. // Here, we simulate it for demonstration purposes. try { fn(() => {}, {}); // Pass a dummy 'done' and empty 'testArgs' for non-unrolled tests if 'it' is used directly } catch (e) { console.error(` FAILURE: ${e.message}`); throw e; } }; unroll.use(it); // Integrate unroll with your mock 'it' function console.log('\n--- Unrolled Test Example ---\n'); describe('maximum of two numbers (unrolled)', function() { unroll('maximum of #a and #b is #c', function(done, testArgs) { console.log(` Testing: Math.max(${testArgs['a']}, ${testArgs['b']}) === ${testArgs['c']}`); expect( Math.max(testArgs['a'], testArgs['b']) ).to.be.equal(testArgs['c']); done(); }, ` where: a | b | c 3 | 5 | 5 7 | 0 | 7 ${JSON.stringify({val: 1})} | ${JSON.stringify({val: 2})} | ${JSON.stringify({val: 2})} ` ); }); // Example of how to run this with Mocha (requires installing mocha and chai): // In your actual test file: // const unroll = require('unroll'); // const { expect } = require('chai'); // unroll.use(it); // For Mocha // describe('...', function() { ... unroll(...) ... }); // Then run: mocha your_test_file.js
Debug
Known issues
gotchaWhen using template literals for test data, objects and arrays must be explicitly stringified using `JSON.stringify()` before being embedded. Failing to do so will result in incorrect parsing or runtime errors.
fix
Use `${JSON.stringify(yourObject)}` or `${JSON.stringify(yourArray)}` within the template literal data table.
affects: >=1.0.0
gotchaThe `unroll.use()` method must be called once to inject your testing framework's primary test function (e.g., `it`, `test`) before any `unroll` calls are made. Forgetting this step will cause `unroll` to not function correctly.
fix
Ensure `unroll.use(yourTestFunction);` is executed early in your test setup, typically at the top of your test file or a setup hook.
affects: >=1.0.0
gotchaTest arguments are always passed as a single `testArgs` object to the test function, regardless of how many parameters are defined in the test title. Individual parameters must be accessed using bracket notation (e.g., `testArgs['paramName']`).
fix
Rewrite test functions to accept `testArgs` as the second parameter (after `done`) and access values like `testArgs['yourParam']`.
affects: >=1.0.0
gotchaIn versions prior to 1.2.1, there was a known issue where test arguments referenced as variables could not be reused across different tests, leading to unexpected behavior or incorrect test results.
fix
Upgrade to `unroll` version 1.2.1 or newer to ensure correct argument reuse behavior.
affects: <1.2.1
Errors
Common errors & fixes
TypeError: unroll is not a function
The `unroll.use()` method was not called, or it was called with an incorrect function, leading `unroll` to be an uninitialized object when invoked.
fix
Ensure `unroll.use(it);` (or your test function) is called once before any `unroll()` invocations.
TypeError: Cannot read properties of undefined (reading 'a')
Attempting to access a test parameter directly as a named argument (e.g., `function(done, a, b)` instead of `function(done, testArgs)`).
fix
Modify the test function signature to `function(done, testArgs)` and access parameters as `testArgs['a']`, `testArgs['b']`, etc.
SyntaxError: Unexpected token o in JSON at position 1
An object or array was included directly in a template literal data table without being stringified, causing JSON parsing errors when `unroll` tries to process the data.
fix
Wrap objects and arrays within the template literal with `JSON.stringify()`: `${JSON.stringify({ yourKey: 'value' })}`.
Upgrade
Version history
0.1.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
9 hits · last 30 days
node
8
Resources
githubhttps://github.com/lawrencec/unroll ↗
packagehttps://www.npmjs.com/package/unroll ↗
unroll — npm install unroll · libregistry