{"id":13464825,"url":"https://github.com/ehmicky/test-each","last_synced_at":"2025-04-09T12:08:48.359Z","repository":{"id":40572012,"uuid":"188094787","full_name":"ehmicky/test-each","owner":"ehmicky","description":"🤖 Repeat tests. Repeat tests. Repeat tests.","archived":false,"fork":false,"pushed_at":"2024-04-05T16:54:41.000Z","size":8740,"stargazers_count":109,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-05T17:51:24.233Z","etag":null,"topics":["cartesian","code-quality","data-driven","data-driven-testing","data-driven-tests","es6","foreach","functional-programming","fuzz","fuzz-testing","fuzzing","iterable","javascript","library","nodejs","snapshot-testing","test","test-automation","testing","typescript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ehmicky.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-05-22T18:41:45.000Z","updated_at":"2024-04-15T06:31:32.833Z","dependencies_parsed_at":"2024-04-15T06:31:05.793Z","dependency_job_id":"a3b58f25-5baa-41f5-8942-2386db19c5c1","html_url":"https://github.com/ehmicky/test-each","commit_stats":{"total_commits":888,"total_committers":3,"mean_commits":296.0,"dds":0.009009009009009028,"last_synced_commit":"efda60340a67d0d22ec374e7ccf2e87be4f2ac7e"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Ftest-each","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Ftest-each/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Ftest-each/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Ftest-each/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ehmicky","download_url":"https://codeload.github.com/ehmicky/test-each/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248036067,"owners_count":21037092,"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":["cartesian","code-quality","data-driven","data-driven-testing","data-driven-tests","es6","foreach","functional-programming","fuzz","fuzz-testing","fuzzing","iterable","javascript","library","nodejs","snapshot-testing","test","test-automation","testing","typescript"],"created_at":"2024-07-31T14:00:51.072Z","updated_at":"2025-04-09T12:08:48.341Z","avatar_url":"https://github.com/ehmicky.png","language":"JavaScript","readme":"\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/ehmicky/design/main/test-each/test-each_dark.svg\"/\u003e\n  \u003cimg alt=\"test-each logo\" src=\"https://raw.githubusercontent.com/ehmicky/design/main/test-each/test-each.svg\" width=\"500\"/\u003e\n\u003c/picture\u003e\n\n[![Node](https://img.shields.io/badge/-Node.js-808080?logo=node.js\u0026colorA=404040\u0026logoColor=66cc33)](https://www.npmjs.com/package/test-each)\n[![Browsers](https://img.shields.io/badge/-Browsers-808080?logo=firefox\u0026colorA=404040)](https://unpkg.com/test-each?module)\n[![TypeScript](https://img.shields.io/badge/-Typed-808080?logo=typescript\u0026colorA=404040\u0026logoColor=0096ff)](/src/main.d.ts)\n[![Codecov](https://img.shields.io/badge/-Tested%20100%25-808080?logo=codecov\u0026colorA=404040)](https://codecov.io/gh/ehmicky/test-each)\n[![Minified size](https://img.shields.io/bundlephobia/minzip/test-each?label\u0026colorA=404040\u0026colorB=808080\u0026logo=webpack)](https://bundlephobia.com/package/test-each)\n[![Mastodon](https://img.shields.io/badge/-Mastodon-808080.svg?logo=mastodon\u0026colorA=404040\u0026logoColor=9590F9)](https://fosstodon.org/@ehmicky)\n[![Medium](https://img.shields.io/badge/-Medium-808080.svg?logo=medium\u0026colorA=404040)](https://medium.com/@ehmicky)\n\n🤖 Repeat tests. Repeat tests. Repeat tests.\n\nRepeats tests using different inputs\n([Data-Driven Testing](https://en.wikipedia.org/wiki/Data-driven_testing)):\n\n- test runner independent: works with your current setup\n- generates [test titles](#test-titles) that are descriptive, unique, for any\n  JavaScript type (not just JSON)\n- loops over every possible combination of inputs\n  ([cartesian product](#cartesian-product))\n- can use random functions ([fuzz testing](#fuzz-testing))\n- [snapshot testing](#snapshot-testing) friendly\n\n# Example\n\n\u003c!-- eslint-disable max-nested-callbacks --\u003e\n\n```js\n// The examples use Ava but any test runner works (Jest, Mocha, Jasmine, etc.)\nimport test from 'ava'\n\nimport multiply from './multiply.js'\n\nimport { each } from 'test-each'\n\n// The code we are testing\n\n// Repeat test using different inputs and expected outputs\neach(\n  [\n    { first: 2, second: 2, output: 4 },\n    { first: 3, second: 3, output: 9 },\n  ],\n  ({ title }, { first, second, output }) =\u003e {\n    // Test titles will be:\n    //    should multiply | {\"first\": 2, \"second\": 2, \"output\": 4}\n    //    should multiply | {\"first\": 3, \"second\": 3, \"output\": 9}\n    test(`should multiply | ${title}`, (t) =\u003e {\n      t.is(multiply(first, second), output)\n    })\n  },\n)\n\n// Snapshot testing. The `output` is automatically set on the first run,\n// then re-used in the next runs.\neach(\n  [\n    { first: 2, second: 2 },\n    { first: 3, second: 3 },\n  ],\n  ({ title }, { first, second }) =\u003e {\n    test(`should multiply outputs | ${title}`, (t) =\u003e {\n      t.snapshot(multiply(first, second))\n    })\n  },\n)\n\n// Cartesian product.\n// Run this test 4 times using every possible combination of inputs\neach([0.5, 10], [2.5, 5], ({ title }, first, second) =\u003e {\n  test(`should mix integers and floats | ${title}`, (t) =\u003e {\n    t.is(typeof multiply(first, second), 'number')\n  })\n})\n\n// Fuzz testing. Run this test 1000 times using different numbers.\neach(1000, Math.random, ({ title }, index, randomNumber) =\u003e {\n  test(`should correctly multiply floats | ${title}`, (t) =\u003e {\n    t.is(multiply(randomNumber, 1), randomNumber)\n  })\n})\n```\n\n# Install\n\n```\nnpm install -D test-each\n```\n\nThis package works in both Node.js \u003e=18.18.0 and\n[browsers](https://raw.githubusercontent.com/ehmicky/dev-tasks/main/src/browserslist).\n\nThis is an ES module. It must be loaded using\n[an `import` or `import()` statement](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c),\nnot `require()`. If TypeScript is used, it must be configured to\n[output ES modules](https://www.typescriptlang.org/docs/handbook/esm-node.html),\nnot CommonJS.\n\n# Usage\n\n```js\nimport { each } from 'test-each'\n\nconst inputs = [\n  ['red', 'blue'],\n  [0, 5, 50],\n]\neach(...inputs, (info, color, number) =\u003e {})\n```\n\nFires `callback` once for each possible combination of `inputs`.\n\nEach `input` can be an [`array`](#cartesian-product), a\n[`function`](#input-functions) or an [`integer`](#fuzz-testing).\n\nA common use case for `callback` is to define tests (using any test runner).\n\n[`info`](#info) is an `object` whose properties can be used to generate\n[test titles](#test-titles).\n\n### Test titles\n\nEach combination of parameters is stringified as a `title` available in the\n`callback`'s [first argument](#infotitle).\n\nTitles should be included in test titles to make them descriptive and unique.\n\nLong titles are truncated. An incrementing counter is appended to duplicates.\n\nAny JavaScript type is\n[stringified](https://github.com/facebook/jest/tree/master/packages/pretty-format),\nnot just JSON.\n\nYou can customize titles either by:\n\n- defining `title` properties in `inputs` that are\n  [plain objects](https://stackoverflow.com/a/52453477/1526301)\n- using the [`info` argument](#info)\n\n\u003c!-- eslint-disable max-nested-callbacks --\u003e\n\n```js\nimport { each } from 'test-each'\n\neach([{ color: 'red' }, { color: 'blue' }], ({ title }, param) =\u003e {\n  // Test titles will be:\n  //    should test color | {\"color\": \"red\"}\n  //    should test color | {\"color\": \"blue\"}\n  test(`should test color | ${title}`, () =\u003e {})\n})\n\n// Plain objects can override this using a `title` property\neach(\n  [\n    { color: 'red', title: 'Red' },\n    { color: 'blue', title: 'Blue' },\n  ],\n  ({ title }, param) =\u003e {\n    // Test titles will be:\n    //    should test color | Red\n    //    should test color | Blue\n    test(`should test color | ${title}`, () =\u003e {})\n  },\n)\n\n// The `info` argument can be used for dynamic titles\neach([{ color: 'red' }, { color: 'blue' }], (info, param) =\u003e {\n  // Test titles will be:\n  //    should test color | 0 red\n  //    should test color | 1 blue\n  test(`should test color | ${info.index} ${param.color}`, () =\u003e {})\n})\n```\n\n### Cartesian product\n\nIf several `inputs` are specified, their\n[cartesian product](https://github.com/ehmicky/fast-cartesian) is used.\n\n```js\nimport { each } from 'test-each'\n\n// Run callback five times: a -\u003e b -\u003e c -\u003e d -\u003e e\neach(['a', 'b', 'c', 'd', 'e'], (info, param) =\u003e {})\n\n// Run callback six times: a c -\u003e a d -\u003e a e -\u003e b c -\u003e b d -\u003e b e\neach(['a', 'b'], ['c', 'd', 'e'], (info, param, otherParam) =\u003e {})\n\n// Nested arrays are not iterated.\n// Run callback only twice: ['a', 'b'] -\u003e ['c', 'd', 'e']\neach(\n  [\n    ['a', 'b'],\n    ['c', 'd', 'e'],\n  ],\n  (info, param) =\u003e {},\n)\n```\n\n### Input functions\n\nIf a `function` is used instead of an array, each iteration fires it and uses\nits return value instead. The `function` is called with the\n[same arguments](https://github.com/ehmicky/test-each#testeachinputs-callback)\nas the `callback`.\n\nThe generated values are included in [test titles](#test-titles).\n\n\u003c!-- eslint-disable max-params --\u003e\n\n```js\nimport { each } from 'test-each'\n\n// Run callback with a different random number each time\neach(['red', 'green', 'blue'], Math.random, (info, color, randomNumber) =\u003e {})\n\n// Input functions are called with the same arguments as the callback\neach(\n  ['02', '15', '30'],\n  ['January', 'February', 'March'],\n  ['1980', '1981'],\n  (info, day, month, year) =\u003e `${day}/${month}/${year}`,\n  (info, day, month, year, date) =\u003e {},\n)\n```\n\n### Fuzz testing\n\nIntegers can be used instead of arrays to multiply the number of iterations.\n\nThis enables [fuzz testing](https://en.wikipedia.org/wiki/Fuzzing) when combined\nwith [input functions](#input-functions) and libraries like\n[faker.js](https://github.com/tzuryby/Faker.js),\n[chance.js](https://github.com/chancejs/chancejs) or\n[json-schema-faker](https://github.com/json-schema-faker/json-schema-faker).\n\n```js\nimport faker from 'faker'\n\n// Run callback 1000 times with a random UUID and color each time\neach(\n  1000,\n  faker.random.uuid,\n  faker.random.arrayElement(['green', 'red', 'blue']),\n  (info, randomUuid, randomColor) =\u003e {},\n)\n\n// `info.index` can be used as a seed for reproducible randomness.\n// The following series of 1000 UUIDs will remain the same across executions.\neach(\n  1000,\n  ({ index }) =\u003e faker.seed(index) \u0026\u0026 faker.random.uuid(),\n  (info, randomUuid) =\u003e {},\n)\n```\n\n### Snapshot testing\n\nThis library works well with\n[snapshot testing](https://github.com/bahmutov/snap-shot-it#use).\n\nAny library can be used\n([`snap-shot-it`](https://github.com/bahmutov/snap-shot-it),\n[Ava snapshots](https://github.com/avajs/ava/blob/master/docs/04-snapshot-testing.md),\n[Jest snapshots](https://jestjs.io/docs/en/snapshot-testing),\n[Node TAP snapshots](https://node-tap.org/plugins/snapshot/), etc.).\n\n\u003c!-- eslint-disable max-nested-callbacks --\u003e\n\n```js\nimport { each } from 'test-each'\n\n// The `output` is automatically set on the first run,\n// then re-used in the next runs.\neach(\n  [\n    { first: 2, second: 2 },\n    { first: 3, second: 3 },\n  ],\n  ({ title }, { first, second }) =\u003e {\n    test(`should multiply outputs | ${title}`, (t) =\u003e {\n      t.snapshot(multiply(first, second))\n    })\n  },\n)\n```\n\n### Side effects\n\nIf `callback`'s [parameters](#params) are directly modified, they should be\ncopied to prevent side effects for the next iterations.\n\n\u003c!-- eslint-disable fp/no-mutation, no-param-reassign --\u003e\n\n```js\nimport { each } from 'test-each'\n\neach(\n  ['green', 'red', 'blue'],\n  [{ active: true }, { active: false }],\n  (info, color, param) =\u003e {\n    // This should not be done, as the objects are re-used in several iterations\n    param.active = false\n\n    // But this is safe since it's a copy\n    const newParam = { ...param }\n    newParam.active = false\n  },\n)\n```\n\n### Iterables\n\n[`iterable()`](#iterableinputs) can be used to iterate over each combination\ninstead of providing a callback.\n\n\u003c!-- eslint-disable fp/no-loops --\u003e\n\n```js\nimport { iterable } from 'test-each'\n\nconst combinations = iterable(\n  ['green', 'red', 'blue'],\n  [{ active: true }, { active: false }],\n)\n\nfor (const [{ title }, color, param] of combinations) {\n  test(`should test color | ${title}`, () =\u003e {})\n}\n```\n\nThe return value is an\n[`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators#Iterables).\nThis can be converted to an array with the spread operator.\n\n\u003c!-- eslint-disable max-nested-callbacks --\u003e\n\n```js\nconst array = [...combinations]\n\narray.forEach(([{ title }, color, param]) =\u003e {\n  test(`should test color | ${title}`, () =\u003e {})\n})\n```\n\n# API\n\n## each(...inputs, callback)\n\n`inputs`: `Array | function | integer` (one or [several](#cartesian-product))\\\n`callback`: `(info, ...params) =\u003e void`\n\nFires `callback` with each combination of [`params`](#params).\n\n## iterable(...inputs)\n\n`inputs`: `Array | function | integer` (one or [several](#cartesian-product))\\\n_Return value_:\n[`Iterable\u003c[info, ...params]\u003e`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators#Iterables)\n\nReturns an\n[`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators#Iterables)\nlooping through each combination of [`params`](#params).\n\n### info\n\n_Type_: `object`\n\n#### info.title\n\n_Type_: `string`\n\nLike [`params`](#params) but stringified. Should be used in\n[test titles](#test-titles).\n\n#### info.titles\n\n_Type_: `string[]`\n\nLike [`info.title`](#infotitle) but for each [`param`](#params).\n\n#### info.index\n\n_Type_: `integer`\n\nIncremented on each iteration. Starts at `0`.\n\n#### info.indexes\n\n_Type_: `integer[]`\n\nIndex of each [`params`](#params) inside each initial\n[`input`](#eachinputs-callback).\n\n### params\n\n_Type_: `any` (one or [several](#cartesian-product))\n\nCombination of inputs for the current iteration.\n\n# Support\n\nFor any question, _don't hesitate_ to [submit an issue on GitHub](../../issues).\n\nEveryone is welcome regardless of personal background. We enforce a\n[Code of conduct](CODE_OF_CONDUCT.md) in order to promote a positive and\ninclusive environment.\n\n# Contributing\n\nThis project was made with ❤️. The simplest way to give back is by starring and\nsharing it online.\n\nIf the documentation is unclear or has a typo, please click on the page's `Edit`\nbutton (pencil icon) and suggest a correction.\n\nIf you would like to help us fix a bug or add a new feature, please check our\n[guidelines](CONTRIBUTING.md). Pull requests are welcome!\n\n\u003c!-- Thanks go to our wonderful contributors: --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START --\u003e\n\u003c!-- prettier-ignore --\u003e\n\u003c!--\n\u003ctable\u003e\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://fosstodon.org/@ehmicky\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/8136211?v=4\" width=\"100px;\" alt=\"ehmicky\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eehmicky\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ehmicky/test-each/commits?author=ehmicky\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"#design-ehmicky\" title=\"Design\"\u003e🎨\u003c/a\u003e \u003ca href=\"#ideas-ehmicky\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"https://github.com/ehmicky/test-each/commits?author=ehmicky\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n--\u003e\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n","funding_links":[],"categories":["JavaScript","Software","Tools"],"sub_categories":["Make your life easier","Web, JavaScript"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmicky%2Ftest-each","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fehmicky%2Ftest-each","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmicky%2Ftest-each/lists"}