{"id":15017411,"url":"https://github.com/lawrencec/unroll","last_synced_at":"2025-08-22T23:27:04.236Z","repository":{"id":6375580,"uuid":"7613042","full_name":"lawrencec/Unroll","owner":"lawrencec","description":"A helper tool to easily run the same tests against multiple data with verbose output.","archived":false,"fork":false,"pushed_at":"2020-09-17T11:28:33.000Z","size":2871,"stargazers_count":16,"open_issues_count":38,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-04-14T06:19:16.576Z","etag":null,"topics":["ava","bdd","data-table","jasmine","javascript","jest","jest-tests","mocha","spock","tape","tdd","test-driven-development","testing-tools"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lawrencec.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-01-14T21:28:32.000Z","updated_at":"2020-09-15T04:05:04.000Z","dependencies_parsed_at":"2022-09-26T20:22:09.641Z","dependency_job_id":null,"html_url":"https://github.com/lawrencec/Unroll","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lawrencec%2FUnroll","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lawrencec%2FUnroll/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lawrencec%2FUnroll/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lawrencec%2FUnroll/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lawrencec","download_url":"https://codeload.github.com/lawrencec/Unroll/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248564056,"owners_count":21125405,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ava","bdd","data-table","jasmine","javascript","jest","jest-tests","mocha","spock","tape","tdd","test-driven-development","testing-tools"],"created_at":"2024-09-24T19:50:25.480Z","updated_at":"2025-04-12T11:43:38.632Z","avatar_url":"https://github.com/lawrencec.png","language":"JavaScript","readme":"Unroll [![Build Status](https://travis-ci.org/lawrencec/Unroll.svg?branch=master)](https://travis-ci.org/lawrencec/Unroll)[![Test Coverage](https://coveralls.io/repos/github/lawrencec/Unroll/badge.svg?branch=master)](https://coveralls.io/github/lawrencec/Unroll?branch=master)\n=====================================================================================================================================================================================================================================================================================\n\nA helper tool (for browser and node tests) to easily iterate through test data against a single test method with output about each test iteration and its parameters. Or in other words a helper method to parameterize your tests.\n\nIt is an attempt to provide similar behaviour to the [Unroll annotation]\n(https://spockframework.github.io/spock/docs/1.0/data_driven_testing.html#_method_unrolling) from [Spock](https://code.google.com/p/spock/).\n\nUnroll works by decorating the testing library function so it works with any testing library e.g  [Jasmine](https://jasmine.github.io/), [Mocha](http://mochajs.org/), [Tape](https://github.com/substack/tape) and [AVA](https://github.com/sindresorhus/ava). The `examples` directory has working examples of each. See below for instructions on how to run them.\n\n\n## Install\n\n\t$\u003e npm install unroll\n\nTo run the unit tests or the examples:\n\n\t$\u003e npm install\n\n`npm run` commands expects `node_modules/.bin/` to be in `$PATH`.\n\n## Usage\n\nInclude `unroll` in your test file and configure.\n\n\tvar unroll = require('unroll');\n\tunroll.use(it); // specify test library function here.\n\nInstead of calling the testing library function e.g `it` or `test`, call `unroll` with three arguments:\n\n- name of the test with parameterized names\n- test function\n- data table of parameters to pass to tests.\n\nNote the use of `#` character to prefix parameter name and the additional argument `testArgs` from which to reference the arguments.\n\n      ```\n\tdescribe('maximum of two numbers (unrolled)', function() {\n        unroll('maximum of #a and #b is #c',\n          function(done, testArgs) {\n            expect(\n              Math.max(testArgs['a'], testArgs['b'])\n            ).to.be.equal(testArgs['c']);\n            done();\n          },\n          [\n            ['a', 'b', 'c'],\n            [ 3,   5,   5 ],\n            [ 7,   0,   7 ]\n          ]\n        );\n    });\n\nThe data table can also be specified using a template literal if nested arrays aren't your thing. For example the above can be written\nlike so when using template literals.\n\n    ```\n\tdescribe('maximum of two numbers (unrolled)', function() {\n        unroll('maximum of #a and #b is #c',\n          function(done, testArgs) {\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          `\n        );\n    });\n\nNote, that objects and arrays need to be stringified first:\n\n    ```\n    unroll('The #thing was jumped over by #entity.',\n        () =\u003e {},\n        `\n          where:\n          entity                            |   thing\n          cat                               |   moon\n          1                                 |   2\n          ${JSON.stringify({name: 'cat'})}  |   ${JSON.stringify({name: 'moon'})}\n        `\n      );\n\n## Examples\n\nThe following example is the same shown in examples/mocha-bdd-example.js file. It can be run using Mocha eg:\n\n    mocha -R spec ./mocha-bdd-example.js\n\n\nUsing a similar example from the above spock unroll documentation, a simple test of testing maximum of two numbers eg:\n\n    describe('maximum of two numbers', function() {\n\n      it('is performed correctly', function(done) {\n        expect(Math.max(3, 5)).to.be.equal(5);\n        expect(Math.max(7, 0)).to.be.equal(7);\n        done();\n      });\n\n    });\n\nThe test output would look like the following:\n\n\n      maximum of two numbers\n        ✓ is performed correctly\n\n      ✔ 1 test complete (4ms)\n\nwhilst a failing test would look like:\n\n      maximum of two numbers\n        1) is performed correctly\n\n\n      ✖ 1 of 1 test failed:\n\n      1) maximum of two numbers is performed correctly:\n         expected 7 to equal 0\n\n\nBut using unroll(), like so:\n\n      unroll.use(it);\n      describe('maximum of two numbers (unrolled)', function() {\n        unroll('maximum of #a and #b is #c',\n          function(done, testArgs) {\n            expect(\n              Math.max(testArgs['a'], testArgs['b'])\n            ).to.be.equal(testArgs['c']);\n            done();\n          },\n          [\n            ['a', 'b', 'c'],\n            [ 3,   5,   5 ],\n            [ 7,   0,   7 ]\n          ]\n        );\n    });\n\nwould give an unrolled test output like:\n\n\n      maximum of two numbers(unrolled)\n        - maximum of 3 and 5 is 5\n        - maximum of 7 and 0 is 7\n\n      ✔ 2 tests complete (6ms)\n\nand a failing test would show the following:\n\n      maximum of two numbers (unrolled)\n        ✓ maximum of 3 and 5 is 5\n        1) maximum of 7 and 0 is 0\n\n\n      ✖ 1 of 2 tests failed:\n\n      1) maximum of two numbers (unrolled) maximum of 7 and 0 is 0:\n         expected 7 to equal 0\n\nAnother way of using unroll can be\n\n      unroll.use(it);\n      describe('maximum of two numbers (unrolled)', function() {\n        unroll('calculates the maximum of #b and #a',\n          function(done, testArgs) {\n            expect(\n              Math.max(testArgs['a'], testArgs['b'])\n            ).to.be.equal(testArgs['c']);\n            done();\n          },\n          [\n            ['a', 'b', 'c'],\n            [ 3,   5,   5 ],\n            [ 7,   0,   7 ]\n          ]\n        );\n    });\n\nHere the title parameters are out of sequence with the sequence of the testArgs passed.\nThe output for this type of usage would be something like:\n\n      maximum of two numbers\n        - calculates the maximum of 5 and 3\n        - calculates the maximum of 0 and 7\n\n      ✔ 2 tests complete (6ms)\n\nand a failing test would show the following:\n\n      maximum of two numbers (unrolled)\n        ✓ calculates the maximum of 5 and 3\n        1) calculates the maximum of 0 and 7\n\n\n      ✖ 1 of 2 tests failed:\n\n      1) maximum of two numbers (unrolled) calculates the maximum of 0 and 7 is 0:\n         expected 7 to equal 0\n\nThe examples directory has examples for various testing frameworks. There are `npm run` commands to run each example or one can run all the examples with:\n\n\t$\u003e npm run examples\n\n### Mocha\n\nMocha's allows one use different interfaces e.g tdd, bdd and qunit. Run all the examples for each with:\n\n\t$\u003e npm run example-mocha\n\n### AVA\n\n\t$\u003e npm run example-ava\n\n### Tape\n\n\t$\u003e npm run example-tape\n\n### Jasmine\n\n\t$\u003e npm run example-jasmine\n\n\n## Tests\n\nTests can be run, from the project root directory, via:\n\n    $\u003e npm test\n\nBrowser tests can be run via karma (install the dev dependencies first):\n\n    $\u003e npm run test-browser\n\nA coverage report can be generated in target/lcov-report/index.html via:\n\n    $\u003e npm run coverage\n\n## Lint\n\nLinting can be tested with:\n\n\t$\u003e npm run lint\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flawrencec%2Funroll","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flawrencec%2Funroll","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flawrencec%2Funroll/lists"}