Jest Test Matrix

1.2.0 · active · verified Tue Apr 21

jest-test-matrix is a utility for Jest that streamlines the process of testing functions across all possible combinations of input parameters. Instead of manually writing individual test cases for each scenario, it enables developers to define a matrix of inputs, and the utility automatically generates and executes tests for every permutation. The current stable version is 1.2.0, and as a specialized testing utility, it typically sees infrequent but stable updates. This package is particularly useful for verifying the behavior of functions with multiple arguments where comprehensive combinatorial testing is desired, significantly reducing boilerplate code. It integrates directly with Jest's snapshot testing, producing a well-formatted, tabular snapshot that clearly displays inputs and corresponding outputs for each tested combination, aiding in quick visual verification and regression detection. This approach simplifies test maintenance and ensures thorough coverage for complex input scenarios.

Common errors

```
TypeError: (0 , _jestTestMatrix.default) is not a function
```
cause `testMatrix` is a default export, but it's being imported as a named export.

fix Change the import statement to `import testMatrix from 'jest-test-matrix';`.
```
Snapshot mismatch
```
cause The generated output from `testMatrix` for your function and inputs has changed, and the current snapshot no longer matches. This could be due to a change in the function's logic, a change in the input values provided to `testMatrix`, or an uncommitted snapshot.

fix Review the proposed snapshot changes in your terminal output. If the change is intentional, update the snapshot by running Jest with the `--updateSnapshot` or `-u` flag (`jest -u`). If unintentional, debug your function or input parameters.

Warnings

gotcha The `testMatrix` function expects the tested function to accept a single object as its argument. If your function takes multiple discrete arguments (e.g., `fn(a, b)`), you must wrap it in an anonymous function that adapts the input structure (e.g., `({a, b}) => fn(a, b)`).
Fix: Wrap your function call inside an anonymous function that destructures the input object, like `testMatrix(({arg1, arg2}) => myFunction(arg1, arg2), { arg1: [...], arg2: [...] })`.
gotcha Generated snapshots can become very large and difficult to review or diff if the tested function has many parameters or many possible values for each parameter. While formatted as a table, extensive matrices still require careful attention.
Fix: Keep the number of input combinations manageable for critical functions. Consider splitting complex tests into smaller matrices, or use more targeted assertions if the generated snapshot is too verbose.

Install

npm install jest-test-matrix npm
yarn add jest-test-matrix yarn
pnpm add jest-test-matrix pnpm

Imports

testMatrix
wrong:
```
import { testMatrix } from 'jest-test-matrix';
```
correct:
```
import testMatrix from 'jest-test-matrix';
```
The primary utility function `testMatrix` is exported as a default export.
testMatrix (CommonJS)
```
const testMatrix = require('jest-test-matrix');
```
For CommonJS environments, `require` is used to import the default export.

Quickstart

This example demonstrates how to use `testMatrix` to generate all combinations for `amount`, `balance`, and `status` parameters and verify the output using Jest's snapshot testing.

import testMatrix from 'jest-test-matrix';

interface CanPayOpts {
  amount: number;
  balance: number;
  status: 'active' | 'locked' | 'expired';
}

function canPay({amount, balance, status}: CanPayOpts){
  if (status === 'locked' || status == 'expired'){
    return false;
  }
  return balance > amount;
}

describe('Payment eligibility', () => {
  it('should only allow valid payments based on various conditions', () => {
    expect(
      testMatrix(canPay, {
        amount: [20, 100],
        balance : [50],
        status: ['active', 'locked', 'expired']
      })
    ).toMatchSnapshot();
  });
});

view raw JSON →