Parameterized tests in JavaScript with Jest
Parameterized tests are used to test the same code under different conditions. One can set up a test method that retrieves data from a data source. This data source can be a collection of objects, external file or maybe even a database. The general idea is to make it easy to test different conditions with the same test method to avoid duplication and make the code easier to read and maintain.
Jest has a built-in support for tests parameterized with data table that can be provided either by an array of arrays or as tagged template literal.
Table of Contents
The code
Let’s consider a simple Calculator fn that accepts an operator and the numbers array:
type Operator = '+' | '-' | '*' | '/';
export default function calculator(operator: Operator, inputs: number[]) {
if (inputs.length < 2) {
throw new Error(`inputs should have length >= 2`);
}
switch (operator) {
case '+':
return inputs.reduce((prev, curr) => prev + curr);
case '-':
return inputs.reduce((prev, curr) => prev - curr);
case '*':
return inputs.reduce((prev, curr) => prev * curr);
case '/':
return inputs.reduce((prev, curr) => prev / curr);
default:
throw new Error(`Unknown operator ${operator}`);
}
}
The Calculator can be tested using the following scenarios:
import calculator from './calculator';
describe('Calculator', () => {
it('throws error when input.length < 2', () => {
expect(() => calculator('+', [0])).toThrow('inputs should have length >= 2');
});
it('throws error when unsupported operator was used', () => {
// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore
expect(() => calculator('&', [0, 0])).toThrow('unknown operator &');
});
it('adds 2 or more numbers incl. `NaN` and `Infinity`', () => {
expect(calculator('+', [1, 41])).toEqual(42);
expect(calculator('+', [1, 2, 39])).toEqual(42);
expect(calculator('+', [1, 2, NaN])).toEqual(NaN);
expect(calculator('+', [1, 2, Infinity])).toEqual(Infinity);
});
it('subtracts 2 or more numbers incl. `NaN` and `Infinity`', () => {
expect(calculator('-', [43, 1])).toEqual(42);
expect(calculator('-', [44, 1, 1])).toEqual(42);
expect(calculator('-', [1, 2, NaN])).toEqual(NaN);
expect(calculator('-', [1, 2, Infinity])).toEqual(-Infinity);
});
it('multiplies 2 or more numbers incl. `NaN` and `Infinity`', () => {
expect(calculator('*', [21, 2])).toEqual(42);
expect(calculator('*', [3, 7, 2])).toEqual(42);
expect(calculator('*', [42, NaN])).toEqual(NaN);
expect(calculator('*', [42, Infinity])).toEqual(Infinity);
});
it('divides 2 or more numbers incl. `NaN` and `Infinity`', () => {
expect(calculator('/', [84, 2])).toEqual(42);
expect(calculator('/', [42, 0])).toEqual(Infinity);
expect(calculator('/', [42, NaN])).toEqual(NaN);
expect(calculator('/', [168, 2, 2])).toEqual(42);
});
});
The most important scenarios are focused on the Calculator main features (add, subtract, multiple and divide) and each of the features is tested with differect set of data values. These tests could be parameterized as they are duplicating the same test logic with different data.
Parameterized (data-driven) tests in jest
In Jest, paramaterized tests can be created with .each that come with the APIs: .each(table)(name, fn) and .each`table`(name, fn) where the difference is how the test data is provided.
test.each(table)(name, fn)
In this example, data is provided as an array of arrays with the arguments that are injected into the test function for each row. Unique test names are created by positioinally injecting parameters:
import calculator from './calculator';
describe('Calculator', () => {
it.each([
[[1, 41], 42],
[[1, 2, 39], 42],
[[1, 2, NaN], NaN],
[[1, 2, Infinity], Infinity],
])('adds %p expecting %p', (numbers: number[], result: number) => {
expect(calculator('+', numbers)).toEqual(result);
});
it.each([
[[43, 1], 42],
[[44, 1, 1], 42],
[[1, 2, NaN], NaN],
[[1, 2, Infinity], -Infinity],
])('subtracts %p expecting %p', (numbers: number[], result: number) => {
expect(calculator('-', numbers)).toEqual(result);
});
it.each([
[[21, 2], 42],
[[3, 7, 2], 42],
[[42, NaN], NaN],
[[42, Infinity], Infinity],
])('multiplies %p expecting %p', (numbers: number[], result: number) => {
expect(calculator('*', numbers)).toEqual(result);
});
it.each([
[[84, 2], 42],
[[168, 2, 2], 42],
[[168, 2, 2], 42],
[[42, 0], Infinity],
[[42, NaN], NaN],
])('divides %p expecting %p', (numbers: number[], result: number) => {
expect(calculator('/', numbers)).toEqual(result);
});
});
Please note that in a parameterized test, each data table row creates a new test that has exactly the same lifecylce as the regular test created with the test clousure. For this example, there are 16 tests (4 tests and each with 4 sets of data values):
PASS src/parameterized/calculatorParameterized1.test.ts
Calculator
✓ adds [1, 41] expecting 42 (2 ms)
✓ adds [1, 2, 39] expecting 42
✓ adds [1, 2, NaN] expecting NaN
✓ adds [1, 2, Infinity] expecting Infinity
✓ subtracts [43, 1] expecting 42
✓ subtracts [44, 1, 1] expecting 42
✓ subtracts [1, 2, NaN] expecting NaN
✓ subtracts [1, 2, Infinity] expecting -Infinity
✓ multiplies [21, 2] expecting 42 (1 ms)
✓ multiplies [3, 7, 2] expecting 42 (1 ms)
✓ multiplies [42, NaN] expecting NaN
✓ multiplies [42, Infinity] expecting Infinity (1 ms)
✓ divides [84, 2] expecting 42
✓ divides [168, 2, 2] expecting 42
✓ divides [168, 2, 2] expecting 42
✓ divides [42, 0] expecting Infinity
✓ divides [42, NaN] expecting NaN (1 ms)
Test Suites: 1 passed, 1 total
Tests: 17 passed, 17 total
Snapshots: 0 total
Time: 2.361 s, estimated 3 s
Ran all test suites matching /src\/parameterized\/calculatorParameterized1.test.ts/i.
✨ Done in 3.55s.
In case of a failure you may expect only failed tests are reported, like in the example below:
FAIL src/parameterized/calculatorParameterized1.test.ts
Calculator
✓ adds [1, 41] expecting 42 (1 ms)
✓ adds [1, 2, 39] expecting 42 (3 ms)
✕ adds [1, 2, NaN] expecting Infinity (1 ms)
✓ adds [1, 2, Infinity] expecting Infinity
✓ subtracts [43, 1] expecting 42 (1 ms)
✓ subtracts [44, 1, 1] expecting 42
✓ subtracts [1, 2, NaN] expecting NaN (1 ms)
✓ subtracts [1, 2, Infinity] expecting -Infinity
✓ multiplies [21, 2] expecting 42
✓ multiplies [3, 7, 2] expecting 42
✓ multiplies [42, NaN] expecting NaN
✓ multiplies [42, Infinity] expecting Infinity
✓ divides [84, 2] expecting 42 (1 ms)
✓ divides [168, 2, 2] expecting 42
✓ divides [168, 2, 2] expecting 42
✓ divides [42, 0] expecting Infinity
✕ divides [42, NaN] expecting Infinity (1 ms)
● Calculator › adds [1, 2, NaN] expecting Infinity
expect(received).toEqual(expected) // deep equality
Expected: Infinity
Received: NaN
8 | [[1, 2, Infinity], Infinity],
9 | ])('adds %p expecting %p', (numbers: number[], result: number) => {
> 10 | expect(calculator('+', numbers)).toEqual(result);
| ^
11 | });
12 |
13 | it.each([
at src/parameterized/calculatorParameterized1.test.ts:10:42
● Calculator › divides [42, NaN] expecting Infinity
expect(received).toEqual(expected) // deep equality
Expected: Infinity
Received: NaN
36 | [[42, NaN], Infinity],
37 | ])('divides %p expecting %p', (numbers: number[], result: number) => {
> 38 | expect(calculator('/', numbers)).toEqual(result);
| ^
39 | });
40 | });
41 |
at src/parameterized/calculatorParameterized1.test.ts:38:42
Test Suites: 1 failed, 1 total
Tests: 2 failed, 15 passed, 17 total
Snapshots: 0 total
Time: 2.493 s, estimated 3 s
test.each`table`(name, fn)
In this example, data is provided with template literal, where the first row represents name of variables and the subsequent rows provide test data object injected into the test function for each row. The unique test names are created by injecting parameters by their name.
import calculator from './calculator';
describe('Calculator', () => {
it.each`
numbers | result
${[1, 41]} | ${42}
${[1, 2, 39]} | ${42}
${[1, 2, NaN]} | ${NaN}
${[1, 2, Infinity]} | ${Infinity}
`('adds $numbers expecting $result', ({ numbers, result }) => {
expect(calculator('+', numbers)).toEqual(result);
});
it.each`
numbers | result
${[43, 1]} | ${42}
${[44, 1, 1]} | ${42}
${[1, 2, NaN]} | ${NaN}
${[1, 2, Infinity]} | ${-Infinity}
`('subtracts $numbers expecting $result', ({ numbers, result }) => {
expect(calculator('-', numbers)).toEqual(result);
});
it.each`
numbers | result
${[21, 2]} | ${42}
${[3, 7, 2]} | ${42}
${[42, NaN]} | ${NaN}
${[42, Infinity]} | ${Infinity}
`('multiples $numbers expecting $result', ({ numbers, result }) => {
expect(calculator('*', numbers)).toEqual(result);
});
it.each`
numbers | result
${[84, 2]} | ${42}
${[168, 2, 2]} | ${42}
${[42, 0]} | ${Infinity}
${[42, NaN]} | ${NaN}
`('divides $numbers expecting $result', ({ numbers, result }) => {
expect(calculator('/', numbers)).toEqual(result);
});
});
In this example, also 16 tests were created:
PASS src/parameterized/calculatorParameterized2.test.ts
Calculator
✓ adds [1, 41] expecting 42 (1 ms)
✓ adds [1, 2, 39] expecting 42
✓ adds [1, 2, NaN] expecting NaN (1 ms)
✓ adds [1, 2, Infinity] expecting Infinity
✓ subtracts [43, 1] expecting 42 (1 ms)
✓ subtracts [44, 1, 1] expecting 42
✓ subtracts [1, 2, NaN] expecting NaN
✓ subtracts [1, 2, Infinity] expecting -Infinity
✓ multiples [21, 2] expecting 42
✓ multiples [3, 7, 2] expecting 42 (1 ms)
✓ multiples [42, NaN] expecting NaN (1 ms)
✓ multiples [42, Infinity] expecting Infinity
✓ divides [84, 2] expecting 42 (1 ms)
✓ divides [168, 2, 2] expecting 42
✓ divides [42, 0] expecting Infinity
✓ divides [42, NaN] expecting NaN
Test Suites: 1 passed, 1 total
Tests: 16 passed, 16 total
Snapshots: 0 total
Time: 2.432 s, estimated 3 s
Ran all test suites matching /src\/parameterized\/calculatorParameterized2.test.ts/i.
✨ Done in 3.36s.
Ultimate parameterized test for the Calculator
The previous example could be further improved by adding an additional test param: operator which in the end reduces the code repeatition:
import calculator from './calculator';
describe('Calculator', () => {
it.each`
numbers | operator | result
${[1, 41]} | ${"+"} | ${42}
${[1, 2, 39]} | ${"+"} | ${42}
${[1, 2, NaN]} | ${"+"} | ${NaN}
${[1, 2, Infinity]} | ${"+"} | ${Infinity}
${[43, 1]} | ${"-"} | ${42}
${[44, 1, 1]} | ${"-"} | ${42}
${[1, 2, NaN]} | ${"-"} | ${NaN}
${[1, 2, Infinity]} | ${"-"} | ${-Infinity}
${[21, 2]} | ${"*"} | ${42}
${[3, 7, 2]} | ${"*"} | ${42}
${[42, NaN]} | ${"*"} | ${NaN}
${[42, Infinity]} | ${"*"} | ${Infinity}
${[84, 2]} | ${"/"} | ${42}
${[168, 2, 2]} | ${"/"} | ${42}
${[42, 0]} | ${"/"} | ${Infinity}
${[42, NaN]} | ${"/"} | ${NaN}
`('verifies "$operator" on $numbers expecting $result', ({ numbers, operator, result }) => {
expect(calculator(operator, numbers)).toEqual(result);
});
});
And the test run:
PASS src/parameterized/calculatorParameterized3.test.ts
Calculator
✓ verifies "+" on [1, 41] expecting 42
✓ verifies "+" on [1, 2, 39] expecting 42
✓ verifies "+" on [1, 2, NaN] expecting NaN
✓ verifies "+" on [1, 2, Infinity] expecting Infinity
✓ verifies "-" on [43, 1] expecting 42
✓ verifies "-" on [44, 1, 1] expecting 42
✓ verifies "-" on [1, 2, NaN] expecting NaN
✓ verifies "-" on [1, 2, Infinity] expecting -Infinity
✓ verifies "*" on [21, 2] expecting 42
✓ verifies "*" on [3, 7, 2] expecting 42
✓ verifies "*" on [42, NaN] expecting NaN
✓ verifies "*" on [42, Infinity] expecting Infinity
✓ verifies "/" on [84, 2] expecting 42
✓ verifies "/" on [168, 2, 2] expecting 42
✓ verifies "/" on [42, 0] expecting Infinity
✓ verifies "/" on [42, NaN] expecting NaN
Test Suites: 1 passed, 1 total
Tests: 16 passed, 16 total
Snapshots: 0 total
Time: 2.463 s, estimated 3 s
✨ Done in 3.66s.
In review
- Use parameterized tests when you duplicate test logic for different test data.
- Don’t overuse parameterized tests especially in slower ones like integration or e2e.
- Generate unique test names for better error messages and easier debugging of failed tests.
- Remember, that each data row creates a new test with a default test lifecycle.
