mattphillips / jest-each

A parameterised testing library for Jest. https://www.npmjs.com/package/jest-each 🏃

jest-each has a new home over in core Jest 🎉

From Jest >=23 jest-each is available natively with test.each and describe.each see docs here

If you are using an older version of Jest I am still maintaining jest-each over in the core repo so you can still use jest-each in the exact same way as normal 😊

jest-each

Jest Parameterised Testing

---

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
• .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: sprintf
• 🖖 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.

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

// es5
const each = require('jest-each');

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

.test:

• name: String the title of the test, use %s in the name string to positionally inject parameter values into the test title
• 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

.describe:

• name: String the title of the describe, use %s in the name string to positionally inject parameter values into the suite title
• 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)

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

.test.only(name, fn)

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

each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
]).test.only('returns the result of adding %s to %s', (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)

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

Asynchronous .test(name, fn(done))

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

each([
  ['hello'],
  ['mr'],
  ['spy'],
]).test('gives 007 secret message ', (str, done) => {
  const asynchronousSpy = (message) => {
    expect(message).toBe(str);
    done();
  };
  callSomeAsynchronousFunction(asynchronousSpy)(str);
});

.describe(name, fn)

each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
]).describe('.add(%s, %s)', (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)

each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
]).describe.only('.add(%s, %s)', (a, b, expected) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });
});

.describe.skip(name, fn)

Aliases: .xdescribe(name, fn)

each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
]).describe.skip('.add(%s, %s)', (a, b, expected) => {
  test(`returns ${expected}`, () => {
    expect(a + b).toBe(expected);
  });
});

---

Tagged Template Literal of rows

API

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

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

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

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)

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)

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

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)

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)

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)

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

jest-each's Issues

Complex datasets

First, thank you for this library, it made my tests cleaner.

Sometimes the datasets are too complex to print in the test description, is it possible to print the row being tested if a test fails?

let complexData = [
  [{ complexObject, ... }, expectedValue],
  [{ complexObject, ... }, expectedValue]
]

I basically need to print the complex object only if the test fails.

support for setup and teardown methods

thanks for a great library, matt! this might be more of a feature request, but i'm having a hard time defining the array i pass into each() in the global jest setup methods, specifically beforeAll. at first i thought it had something to do with async request i was making in the beforeAll, but then I realized this doesn't work either:

describe('test suite', () => {
  let products

  beforeAll(() => {
    products = [['def', '321'], ['abc', '123']]
  })

  describe('in here now', () => {
    each(products).test('test %s', (name, id) => {
      expect(id).toBe(id)
    })
  })

I get 'TypeError: Cannot read property 'forEach' of undefined' on the line where each() is called. i tried it inside and outside its own describe block, and no luck. have you noticed a similar issue? apologies if I missed something obvious. thanks again.

Support non-nested arrays?

It seems something like this should work:

describe('test numbers', () => {
  each([2, 1, 0]).test('test %s', (expected) => {
    expect(typeof expected).toBe('number')
  })
})

But expected will be undefined, the array has to be rewritten as [[2], [1], [0]]. Would it maybe make more sense to check if the parameters are not iterable or an array, and wrap them appropriately? The resulting test code would look a lot cleaner.

Add typing support

After the each().test() chain my IDE WebStorm can't recognize the test() method call, and I am guessing that's because of some typing/definition issue. Wondering if it's possible to support typing from this repo. It would be great to see a better IDE support.

Doesn't show test name on fail

This works great showing the name of the passing tests, but doesn't show the name of the failed tests.