---

A parameterised testing library for Jest inspired by 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:
  • %p - pretty-format.
  • %s- String.
  • %d- Number.
  • %i - Integer.
  • %f - Floating point value.
  • %j - JSON.
  • %o - Object.
  • %# - Index 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

---

• Demo
• Installation
• Importing
• APIs
  • Array of Rows
    • Usage
  • Tagged Template Literal of rows
    • Usage

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.

1// es6
2import each from 'jest-each';

1// es5
2const 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:
    • %p - pretty-format.
    • %s- String.
    • %d- Number.
    • %i - Integer.
    • %f - Floating point value.
    • %j - JSON.
    • %o - Object.
    • %# - Index 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
    • 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:
    • %p - pretty-format.
    • %s- String.
    • %d- Number.
    • %i - Integer.
    • %f - Floating point value.
    • %j - JSON.
    • %o - Object.
    • %# - Index 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
    • 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/its 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)

1each([
2  [1, 1, 2],
3  [1, 2, 3],
4  [2, 1, 3],
5]).test('returns the result of adding %d to %d', (a, b, expected) => {
6  expect(a + b).toBe(expected);
7});

1each([
2  {a: 1, b: 1, expected: 2},
3  {a: 1, b: 2, expected: 3},
4  {a: 2, b: 1, expected: 3},
5]).test('returns the result of adding $a to $b', ({a, b, expected}) => {
6  expect(a + b).toBe(expected);
7});

.test.only(name, fn)

Aliases: .it.only(name, fn) or .fit(name, fn)

1each([
2  [1, 1, 2],
3  [1, 2, 3],
4  [2, 1, 3],
5]).test.only('returns the result of adding %d to %d', (a, b, expected) => {
6  expect(a + b).toBe(expected);
7});

.test.skip(name, fn)

Aliases: .it.skip(name, fn) or .xit(name, fn) or .xtest(name, fn)

1each([
2  [1, 1, 2],
3  [1, 2, 3],
4  [2, 1, 3],
5]).test.skip('returns the result of adding %d to %d', (a, b, expected) => {
6  expect(a + b).toBe(expected);
7});

.test.concurrent(name, fn)

Aliases: .it.concurrent(name, fn)

1each([
2  [1, 1, 2],
3  [1, 2, 3],
4  [2, 1, 3],
5]).test.concurrent(
6  'returns the result of adding %d to %d',
7  (a, b, expected) => {
8    expect(a + b).toBe(expected);
9  },
10);

.test.concurrent.only(name, fn)

Aliases: .it.concurrent.only(name, fn)

1each([
2  [1, 1, 2],
3  [1, 2, 3],
4  [2, 1, 3],
5]).test.concurrent.only(
6  'returns the result of adding %d to %d',
7  (a, b, expected) => {
8    expect(a + b).toBe(expected);
9  },
10);

.test.concurrent.skip(name, fn)

Aliases: .it.concurrent.skip(name, fn)

1each([
2  [1, 1, 2],
3  [1, 2, 3],
4  [2, 1, 3],
5]).test.concurrent.skip(
6  'returns the result of adding %d to %d',
7  (a, b, expected) => {
8    expect(a + b).toBe(expected);
9  },
10);

Asynchronous .test(name, fn(done))

Alias: .it(name, fn(done))

1each([['hello'], ['mr'], ['spy']]).test(
2  'gives 007 secret message: %s',
3  (str, done) => {
4    const asynchronousSpy = message => {
5      expect(message).toBe(str);
6      done();
7    };
8    callSomeAsynchronousFunction(asynchronousSpy)(str);
9  },
10);

.describe(name, fn)

1each([
2  [1, 1, 2],
3  [1, 2, 3],
4  [2, 1, 3],
5]).describe('.add(%d, %d)', (a, b, expected) => {
6  test(`returns ${expected}`, () => {
7    expect(a + b).toBe(expected);
8  });
9
10  test('does not mutate first arg', () => {
11    a + b;
12    expect(a).toBe(a);
13  });
14
15  test('does not mutate second arg', () => {
16    a + b;
17    expect(b).toBe(b);
18  });
19});

1each([
2  {a: 1, b: 1, expected: 2},
3  {a: 1, b: 2, expected: 3},
4  {a: 2, b: 1, expected: 3},
5]).describe('.add($a, $b)', ({a, b, expected}) => {
6  test(`returns ${expected}`, () => {
7    expect(a + b).toBe(expected);
8  });
9
10  test('does not mutate first arg', () => {
11    a + b;
12    expect(a).toBe(a);
13  });
14
15  test('does not mutate second arg', () => {
16    a + b;
17    expect(b).toBe(b);
18  });
19});

.describe.only(name, fn)

Aliases: .fdescribe(name, fn)

1each([
2  [1, 1, 2],
3  [1, 2, 3],
4  [2, 1, 3],
5]).describe.only('.add(%d, %d)', (a, b, expected) => {
6  test(`returns ${expected}`, () => {
7    expect(a + b).toBe(expected);
8  });
9});

.describe.skip(name, fn)

Aliases: .xdescribe(name, fn)

1each([
2  [1, 1, 2],
3  [1, 2, 3],
4  [2, 1, 3],
5]).describe.skip('.add(%d, %d)', (a, b, expected) => {
6  test(`returns ${expected}`, () => {
7    expect(a + b).toBe(expected);
8  });
9});

---

Tagged Template Literal of rows

API

each[tagged template].test(name, suiteFn)

1each`
2  a    | b    | expected
3  ${1} | ${1} | ${2}
4  ${1} | ${2} | ${3}
5  ${2} | ${1} | ${3}
6`.test('returns $expected when adding $a to $b', ({a, b, expected}) => {
7  expect(a + b).toBe(expected);
8});

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
  • 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)

1each`
2  a    | b    | expected
3  ${1} | ${1} | ${2}
4  ${1} | ${2} | ${3}
5  ${2} | ${1} | ${3}
6`.describe('$a + $b', ({a, b, expected}) => {
7  test(`returns ${expected}`, () => {
8    expect(a + b).toBe(expected);
9  });
10
11  test('does not mutate first arg', () => {
12    a + b;
13    expect(a).toBe(a);
14  });
15
16  test('does not mutate second arg', () => {
17    a + b;
18    expect(b).toBe(b);
19  });
20});

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
• suiteFn: Function the suite of test/its 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)

1each`
2  a    | b    | expected
3  ${1} | ${1} | ${2}
4  ${1} | ${2} | ${3}
5  ${2} | ${1} | ${3}
6`.test('returns $expected when adding $a to $b', ({a, b, expected}) => {
7  expect(a + b).toBe(expected);
8});

.test.only(name, fn)

Aliases: .it.only(name, fn) or .fit(name, fn)

1each`
2  a    | b    | expected
3  ${1} | ${1} | ${2}
4  ${1} | ${2} | ${3}
5  ${2} | ${1} | ${3}
6`.test.only('returns $expected when adding $a to $b', ({a, b, expected}) => {
7  expect(a + b).toBe(expected);
8});

.test.skip(name, fn)

Aliases: .it.skip(name, fn) or .xit(name, fn) or .xtest(name, fn)

1each`
2  a    | b    | expected
3  ${1} | ${1} | ${2}
4  ${1} | ${2} | ${3}
5  ${2} | ${1} | ${3}
6`.test.skip('returns $expected when adding $a to $b', ({a, b, expected}) => {
7  expect(a + b).toBe(expected);
8});

Asynchronous .test(name, fn(done))

Alias: .it(name, fn(done))

1each`
2  str
3  ${'hello'}
4  ${'mr'}
5  ${'spy'}
6`.test('gives 007 secret message: $str', ({str}, done) => {
7  const asynchronousSpy = message => {
8    expect(message).toBe(str);
9    done();
10  };
11  callSomeAsynchronousFunction(asynchronousSpy)(str);
12});

.describe(name, fn)

1each`
2  a    | b    | expected
3  ${1} | ${1} | ${2}
4  ${1} | ${2} | ${3}
5  ${2} | ${1} | ${3}
6`.describe('$a + $b', ({a, b, expected}) => {
7  test(`returns ${expected}`, () => {
8    expect(a + b).toBe(expected);
9  });
10
11  test('does not mutate first arg', () => {
12    a + b;
13    expect(a).toBe(a);
14  });
15
16  test('does not mutate second arg', () => {
17    a + b;
18    expect(b).toBe(b);
19  });
20});

.describe.only(name, fn)

Aliases: .fdescribe(name, fn)

1each`
2  a    | b    | expected
3  ${1} | ${1} | ${2}
4  ${1} | ${2} | ${3}
5  ${2} | ${1} | ${3}
6`.describe.only('$a + $b', ({a, b, expected}) => {
7  test(`returns ${expected}`, () => {
8    expect(a + b).toBe(expected);
9  });
10});

.describe.skip(name, fn)

Aliases: .xdescribe(name, fn)

1each`
2  a    | b    | expected
3  ${1} | ${1} | ${2}
4  ${1} | ${2} | ${3}
5  ${2} | ${1} | ${3}
6`.describe.skip('$a + $b', ({a, b, expected}) => {
7  test(`returns ${expected}`, () => {
8    expect(a + b).toBe(expected);
9  });
10});

License

MIT