# jest-each
> Parameterised tests for Jest
Latest version **30.5.1** (published 2026-09-01) · MIT license · 0 weekly downloads
## Install
```sh
npm install jest-each
pnpm add jest-each
yarn add jest-each
bun add jest-each
```
## Health
**Score 70/100 (B)** — status: active.
Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; popular repo.
Warnings: low downloads.
## Facts
| | |
|---|---|
| Version | 30.5.1 |
| Published | 2026-09-01 |
| First published | 2017-03-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^18.14.0 \|\| ^20.0.0 \|\| ^22.0.0 \|\| >=24.0.0 |
| Dependencies | 5 |
| Unpacked size | 35.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 45458 |
| Author | Matt Phillips |
| Maintainers | aaronabramov, simenb, rickhanlonii, openjs-operations, cpojer, mattphillips |
| Keywords | jest, parameterised, test, each |
## Links
- npm: https://www.npmjs.com/package/jest-each
- Repository: https://github.com/jestjs/jest
- Homepage: https://github.com/jestjs/jest#readme
- Issues: https://github.com/jestjs/jest/issues
- npm.io page: https://npm.io/package/jest-each
## Dependencies (5)
- [chalk](https://npm.io/package/chalk.md) ^4.1.2
- [jest-util](https://npm.io/package/jest-util.md) 30.5.1
- [@jest/types](https://npm.io/package/@jest/types.md) 30.5.1
- [pretty-format](https://npm.io/package/pretty-format.md) 30.5.1
- [@jest/get-type](https://npm.io/package/@jest/get-type.md) 30.5.0
## Alternatives
- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads
## Recent versions
- 30.5.1 (latest) — 2026-09-01
- 30.0.0-rc.1 (next) — 2025-06-09
- 30.5.0 — 2026-08-28
- 30.4.1 — 2026-05-08
- 30.4.0 — 2026-05-07
- 30.3.0 — 2026-03-10
- 30.2.0 — 2025-09-28
- 30.1.0 — 2025-08-27
- 30.0.5 — 2025-07-22
- 30.0.2 — 2025-06-19
- 30.0.1 — 2025-06-18
- 30.0.0 — 2025-06-10
- 30.0.0-beta.8 — 2025-06-04
- 30.0.0-beta.7 — 2025-06-04
- 30.0.0-beta.6 — 2025-06-03
- … 147 more at https://npm.io/package/jest-each/versions
## README
jest-each
Jest Parameterised Testing
[](https://www.npmjs.com/package/jest-each) [](http://npm-stat.com/charts.html?package=jest-each&from=2017-03-21) [](https://github.com/jestjs/jest/blob/main/LICENSE)
A parameterised testing library for [Jest](https://jestjs.io/) inspired by [mocha-each](https://github.com/ryym/mocha-each).
jest-each allows you to provide multiple arguments to your `test`/`describe` which results in the test/suite being run once per row of parameters.
## Features
- `.test` to runs multiple tests with parameterised data
- Also under the alias: `.it`
- `.test.only` to only run the parameterised tests
- Also under the aliases: `.it.only` or `.fit`
- `.test.skip` to skip the parameterised tests
- Also under the aliases: `.it.skip` or `.xit` or `.xtest`
- `.test.concurrent`
- Also under the alias: `.it.concurrent`
- `.test.concurrent.only`
- Also under the alias: `.it.concurrent.only`
- `.test.concurrent.skip`
- Also under the alias: `.it.concurrent.skip`
- `.describe` to runs test suites with parameterised data
- `.describe.only` to only run the parameterised suite of tests
- Also under the aliases: `.fdescribe`
- `.describe.skip` to skip the parameterised suite of tests
- Also under the aliases: `.xdescribe`
- Asynchronous tests with `done`
- Unique test titles with [`printf` formatting](https://nodejs.org/api/util.html#util_util_format_format_args):
- `%p` - [pretty-format](https://www.npmjs.com/package/pretty-format).
- `%s`- String.
- `%d`- Number.
- `%i` - Integer.
- `%f` - Floating point value.
- `%j` - JSON.
- `%o` - Object.
- `%#` - Index of the test case.
- `%$` - Number of the test case.
- `%%` - single percent sign ('%'). This does not consume an argument.
- Unique test titles by injecting properties of test case object
- 🖖 Spock like data tables with [Tagged Template Literals](#tagged-template-literal-of-rows)
---
- [Demo](#demo)
- [Installation](#installation)
- [Importing](#importing)
- APIs
- [Array of Rows](#array-of-rows)
- [Usage](#usage)
- [Tagged Template Literal of rows](#tagged-template-literal-of-rows)
- [Usage](#usage-1)
## Demo
#### Tests without jest-each
#### Tests can be re-written with jest-each to:
**`.test`**
**`.test` with Tagged Template Literals**
**`.describe`**
## Installation
`npm i --save-dev jest-each`
`yarn add -D jest-each`
## Importing
jest-each is a default export so it can be imported with whatever name you like.
```js
// es6
import each from 'jest-each';
```
```js
// es5
const each = require('jest-each').default;
```
## Array of rows
### API
#### `each([parameters]).test(name, testFn)`
##### `each`:
- parameters: `Array` of Arrays with the arguments that are passed into the `testFn` for each row
- _Note_ If you pass in a 1D array of primitives, internally it will be mapped to a table i.e. `[1, 2, 3] -> [[1], [2], [3]]`
##### `.test`:
- name: `String` the title of the `test`.
- Generate unique test titles by positionally injecting parameters with [`printf` formatting](https://nodejs.org/api/util.html#util_util_format_format_args):
- `%p` - [pretty-format](https://www.npmjs.com/package/pretty-format).
- `%s`- String.
- `%d`- Number.
- `%i` - Integer.
- `%f` - Floating point value.
- `%j` - JSON.
- `%o` - Object.
- `%#` - Index of the test case.
- `%$` - Number of the test case.
- `%%` - single percent sign ('%'). This does not consume an argument.
- Or generate unique test titles by injecting properties of test case object with `$variable`
- To inject nested object values use you can supply a keyPath i.e. `$variable.path.to.value` (only works for ["own" properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty), e.g. `$variable.constructor.name` wouldn't work)
- You can use `$#` to inject the index of the test case
- You cannot use `$variable` with the `printf` formatting except for `%%`
- testFn: `Function` the test logic, this is the function that will receive the parameters of each row as function arguments
#### `each([parameters]).describe(name, suiteFn)`
##### `each`:
- parameters: `Array` of Arrays with the arguments that are passed into the `suiteFn` for each row
- _Note_ If you pass in a 1D array of primitives, internally it will be mapped to a table i.e. `[1, 2, 3] -> [[1], [2], [3]]`
##### `.describe`:
- name: `String` the title of the `describe`
- Generate unique test titles by positionally injecting parameters with [`printf` formatting](https://nodejs.org/api/util.html#util_util_format_format_args):
- `%p` - [pretty-format](https://www.npmjs.com/package/pretty-format).
- `%s`- String.
- `%d`- Number.
- `%i` - Integer.
- `%f` - Floating point value.
- `%j` - JSON.
- `%o` - Object.
- `%#` - Index of the test case.
- `%$` - Number of the test case.
- `%%` - single percent sign ('%'). This does not consume an argument.
- Or generate unique test titles by injecting properties of test case object with `$variable`
- To inject nested object values use you can supply a keyPath i.e. `$variable.path.to.value` (only works for ["own" properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty), e.g. `$variable.constructor.name` wouldn't work)
- You can use `$#` to inject the index of the test case
- You cannot use `$variable` with the `printf` formatting except for `%%`
- suiteFn: `Function` the suite of `test`/`it`s to be ran, this is the function that will receive the parameters in each row as function arguments
### Usage
#### `.test(name, fn)`
Alias: `.it(name, fn)`
```js
each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
]).test('returns the result of adding %d to %d', (a, b, expected) => {
expect(a + b).toBe(expected);
});
```
```js
each([
{a: 1, b: 1, expected: 2},
{a: 1, b: 2, expected: 3},
{a: 2, b: 1, expected: 3},
]).test('returns the result of adding $a to $b', ({a, b, expected}) => {
expect(a + b).toBe(expected);
});
```
#### `.test.only(name, fn)`
Aliases: `.it.only(name, fn)` or `.fit(name, fn)`
```js
each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
]).test.only('returns the result of adding %d to %d', (a, b, expected) => {
expect(a + b).toBe(expected);
});
```
#### `.test.skip(name, fn)`
Aliases: `.it.skip(name, fn)` or `.xit(name, fn)` or `.xtest(name, fn)`
```js
each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
]).test.skip('returns the result of adding %d to %d', (a, b, expected) => {
expect(a + b).toBe(expected);
});
```
#### `.test.concurrent(name, fn)`
Aliases: `.it.concurrent(name, fn)`
```js
each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
]).test.concurrent(
'returns the result of adding %d to %d',
(a, b, expected) => {
expect(a + b).toBe(expected);
},
);
```
#### `.test.concurrent.only(name, fn)`
Aliases: `.it.concurrent.only(name, fn)`
```js
each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
]).test.concurrent.only(
'returns the result of adding %d to %d',
(a, b, expected) => {
expect(a + b).toBe(expected);
},
);
```
#### `.test.concurrent.skip(name, fn)`
Aliases: `.it.concurrent.skip(name, fn)`
```js
each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
]).test.concurrent.skip(
'returns the result of adding %d to %d',
(a, b, expected) => {
expect(a + b).toBe(expected);
},
);
```
#### Asynchronous `.test(name, fn(done))`
Alias: `.it(name, fn(done))`
```js
each([['hello'], ['mr'], ['spy']]).test(
'gives 007 secret message: %s',
(str, done) => {
const asynchronousSpy = message => {
expect(message).toBe(str);
done();
};
callSomeAsynchronousFunction(asynchronousSpy)(str);
},
);
```
#### `.describe(name, fn)`
```js
each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
]).describe('.add(%d, %d)', (a, b, expected) => {
test(`returns ${expected}`, () => {
expect(a + b).toBe(expected);
});
test('does not mutate first arg', () => {
a + b;
expect(a).toBe(a);
});
test('does not mutate second arg', () => {
a + b;
expect(b).toBe(b);
});
});
```
```js
each([
{a: 1, b: 1, expected: 2},
{a: 1, b: 2, expected: 3},
{a: 2, b: 1, expected: 3},
]).describe('.add($a, $b)', ({a, b, expected}) => {
test(`returns ${expected}`, () => {
expect(a + b).toBe(expected);
});
test('does not mutate first arg', () => {
a + b;
expect(a).toBe(a);
});
test('does not mutate second arg', () => {
a + b;
expect(b).toBe(b);
});
});
```
#### `.describe.only(name, fn)`
Aliases: `.fdescribe(name, fn)`
```js
each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
]).describe.only('.add(%d, %d)', (a, b, expected) => {
test(`returns ${expected}`, () => {
expect(a + b).toBe(expected);
});
});
```
#### `.describe.skip(name, fn)`
Aliases: `.xdescribe(name, fn)`
```js
each([
[1, 1, 2],
[1, 2, 3],
[2, 1, 3],
]).describe.skip('.add(%d, %d)', (a, b, expected) => {
test(`returns ${expected}`, () => {
expect(a + b).toBe(expected);
});
});
```
---
## Tagged Template Literal of rows
### API
#### `each[tagged template].test(name, suiteFn)`
```js
each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`.test('returns $expected when adding $a to $b', ({a, b, expected}) => {
expect(a + b).toBe(expected);
});
```
##### `each` takes a tagged template string with:
- First row of variable name column headings separated with `|`
- One or more subsequent rows of data supplied as template literal expressions using `${value}` syntax.
##### `.test`:
- name: `String` the title of the `test`, use `$variable` in the name string to inject test values into the test title from the tagged template expressions
- To inject nested object values use you can supply a keyPath i.e. `$variable.path.to.value` (only works for ["own" properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty), e.g. `$variable.constructor.name` wouldn't work)
- You can use `$#` to inject the index of the table row.
- testFn: `Function` the test logic, this is the function that will receive the parameters of each row as function arguments
#### `each[tagged template].describe(name, suiteFn)`
```js
each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`.describe('$a + $b', ({a, b, expected}) => {
test(`returns ${expected}`, () => {
expect(a + b).toBe(expected);
});
test('does not mutate first arg', () => {
a + b;
expect(a).toBe(a);
});
test('does not mutate second arg', () => {
a + b;
expect(b).toBe(b);
});
});
```
##### `each` takes a tagged template string with:
- First row of variable name column headings separated with `|`
- One or more subsequent rows of data supplied as template literal expressions using `${value}` syntax.
##### `.describe`:
- name: `String` the title of the `test`, use `$variable` in the name string to inject test values into the test title from the tagged template expressions
- To inject nested object values use you can supply a keyPath i.e. `$variable.path.to.value` (only works for ["own" properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty), e.g. `$variable.constructor.name` wouldn't work)
- suiteFn: `Function` the suite of `test`/`it`s to be ran, this is the function that will receive the parameters in each row as function arguments
### Usage
#### `.test(name, fn)`
Alias: `.it(name, fn)`
```js
each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`.test('returns $expected when adding $a to $b', ({a, b, expected}) => {
expect(a + b).toBe(expected);
});
```
#### `.test.only(name, fn)`
Aliases: `.it.only(name, fn)` or `.fit(name, fn)`
```js
each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`.test.only('returns $expected when adding $a to $b', ({a, b, expected}) => {
expect(a + b).toBe(expected);
});
```
#### `.test.skip(name, fn)`
Aliases: `.it.skip(name, fn)` or `.xit(name, fn)` or `.xtest(name, fn)`
```js
each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`.test.skip('returns $expected when adding $a to $b', ({a, b, expected}) => {
expect(a + b).toBe(expected);
});
```
#### Asynchronous `.test(name, fn(done))`
Alias: `.it(name, fn(done))`
```js
each`
str
${'hello'}
${'mr'}
${'spy'}
`.test('gives 007 secret message: $str', ({str}, done) => {
const asynchronousSpy = message => {
expect(message).toBe(str);
done();
};
callSomeAsynchronousFunction(asynchronousSpy)(str);
});
```
#### `.describe(name, fn)`
```js
each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`.describe('$a + $b', ({a, b, expected}) => {
test(`returns ${expected}`, () => {
expect(a + b).toBe(expected);
});
test('does not mutate first arg', () => {
a + b;
expect(a).toBe(a);
});
test('does not mutate second arg', () => {
a + b;
expect(b).toBe(b);
});
});
```
#### `.describe.only(name, fn)`
Aliases: `.fdescribe(name, fn)`
```js
each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`.describe.only('$a + $b', ({a, b, expected}) => {
test(`returns ${expected}`, () => {
expect(a + b).toBe(expected);
});
});
```
#### `.describe.skip(name, fn)`
Aliases: `.xdescribe(name, fn)`
```js
each`
a | b | expected
${1} | ${1} | ${2}
${1} | ${2} | ${3}
${2} | ${1} | ${3}
`.describe.skip('$a + $b', ({a, b, expected}) => {
test(`returns ${expected}`, () => {
expect(a + b).toBe(expected);
});
});
```
## License
MIT
---
_Source: https://npm.io/package/jest-each · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._