{"id":14206,"library":"unroll","title":"Unroll Parameterized Test Helper","description":"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.","status":"active","version":"1.6.0","language":"javascript","source_language":"en","source_url":"git://github.com/lawrencec/unroll","tags":["javascript","tdd","bdd","testing","test","unit","unroll"],"install":[{"cmd":"npm install unroll","lang":"bash","label":"npm"},{"cmd":"yarn add unroll","lang":"bash","label":"yarn"},{"cmd":"pnpm add unroll","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primarily designed for CommonJS. While an ESM import might work, `require` is the documented and most reliable method shown in examples.","wrong":"import unroll from 'unroll';","symbol":"unroll","correct":"const unroll = require('unroll');"},{"note":"The `use` method must be called once to configure `unroll` with your testing library's main test function (e.g., `it`, `test`).","wrong":"unroll(it);","symbol":"unroll.use","correct":"unroll.use(it);"},{"note":"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.","wrong":"function(done, a, b) { console.log(a); }","symbol":"testArgs","correct":"function(done, testArgs) { console.log(testArgs['a']); }"}],"quickstart":{"code":"const unroll = require('unroll');\nconst { expect } = require('chai'); // Example assertion library\n\n// Mock your testing framework's 'it' or 'test' function\nconst it = (name, fn) => {\n  console.log(`Running test: ${name}`);\n  // For a real test runner, 'done' would be handled asynchronously.\n  // Here, we simulate it for demonstration purposes.\n  try {\n    fn(() => {}, {}); // Pass a dummy 'done' and empty 'testArgs' for non-unrolled tests if 'it' is used directly\n  } catch (e) {\n    console.error(`  FAILURE: ${e.message}`);\n    throw e;\n  }\n};\n\nunroll.use(it); // Integrate unroll with your mock 'it' function\n\nconsole.log('\\n--- Unrolled Test Example ---\\n');\n\ndescribe('maximum of two numbers (unrolled)', function() {\n    unroll('maximum of #a and #b is #c', \n      function(done, testArgs) {\n        console.log(`  Testing: Math.max(${testArgs['a']}, ${testArgs['b']}) === ${testArgs['c']}`);\n        expect(\n          Math.max(testArgs['a'], testArgs['b'])\n        ).to.be.equal(testArgs['c']);\n        done();\n      },\n      `\n        where:\n        a   |   b   |   c\n        3   |   5   |   5\n        7   |   0   |   7\n        ${JSON.stringify({val: 1})} | ${JSON.stringify({val: 2})} | ${JSON.stringify({val: 2})}\n      `\n    );\n});\n\n// Example of how to run this with Mocha (requires installing mocha and chai):\n// In your actual test file:\n// const unroll = require('unroll');\n// const { expect } = require('chai');\n// unroll.use(it); // For Mocha\n// describe('...', function() { ... unroll(...) ... });\n// Then run: mocha your_test_file.js\n","lang":"javascript","description":"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."},"warnings":[{"fix":"Use `${JSON.stringify(yourObject)}` or `${JSON.stringify(yourArray)}` within the template literal data table.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `unroll.use(yourTestFunction);` is executed early in your test setup, typically at the top of your test file or a setup hook.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Rewrite test functions to accept `testArgs` as the second parameter (after `done`) and access values like `testArgs['yourParam']`.","message":"Test 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']`).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to `unroll` version 1.2.1 or newer to ensure correct argument reuse behavior.","message":"In 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.","severity":"gotcha","affected_versions":"<1.2.1"}],"env_vars":null,"search_vec":"'1.6.0':25 'across':16 'adapt':102 'agnost':141 'allow':27 'annot':45 'argument':126 'array':65,67 'ava/tape':94 'bdd':157 'browser':18 'bug':112 'cadenc':107 'clariti':76 'core':132 'current':22 'data':39,61,145 'data-driven':144 'decor':83 'defin':59 'design':11 'detail':149 'develop':28 'draw':40 'driven':110,146 'e.g':88 'either':62 'enabl':148 'enhanc':74,117 'environ':21 'featur':116 'fix':113 'focus':123 'found':46 'framework':50,98,140 'framework-agnost':139 'function':34,81,87 'handl':127 'helper':4,9 'high':101 'improv':125 'inspir':41 'intermitt':109 'iter':154 'java':52 'javascript':8,155 'latest':120 'librari':10,104 'lie':135 'liter':73 'make':99 'minor':115 'mocha/jasmine':91 'multilin':71 'multipl':36 'node.js':20 'offer':54 'output':150 'overal':129 'parameter':2,14 'primari':85 'proposit':134 'provid':137 'reduc':78 'redund':79 'releas':106,122 'robust':130 'run':30 'set':37 'simplifi':13 'singl':32 'solut':142 'spock':49 'stabl':121 'structur':56 'tdd':156 'templat':72 'test':3,15,33,60,75,86,92,97,147,153,158,159 'unit':160 'unrol':1,5,44,80,161 'use':69 'valu':133 'various':96 'version':24 'way':57","created_at":"2026-04-20T01:58:29.171973+00:00","updated_at":"2026-04-20T01:58:29.171973+00:00","problems":[{"fix":"Ensure `unroll.use(it);` (or your test function) is called once before any `unroll()` invocations.","cause":"The `unroll.use()` method was not called, or it was called with an incorrect function, leading `unroll` to be an uninitialized object when invoked.","error":"TypeError: unroll is not a function"},{"fix":"Modify the test function signature to `function(done, testArgs)` and access parameters as `testArgs['a']`, `testArgs['b']`, etc.","cause":"Attempting to access a test parameter directly as a named argument (e.g., `function(done, a, b)` instead of `function(done, testArgs)`).","error":"TypeError: Cannot read properties of undefined (reading 'a')"},{"fix":"Wrap objects and arrays within the template literal with `JSON.stringify()`: `${JSON.stringify({ yourKey: 'value' })}`.","cause":"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.","error":"SyntaxError: Unexpected token o in JSON at position 1"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.1.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/lawrencec/unroll","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/unroll","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}