Jest Theories

1.5.1 · maintenance · verified Tue Apr 21

jest-theories is a utility library for the Jest testing framework that enables data-driven test cases, inspired by concepts from XUnit and Jasmine Theories. It allows developers to write a single test function and execute it multiple times with varying inputs, known as 'theories.' This significantly reduces boilerplate and improves test maintainability by centralizing test logic while parameterizing data. The current stable version is 1.5.1, and its release cadence is typically driven by community contributions and specific feature or bug fix requirements, rather than a fixed schedule, indicating a maintenance-focused approach given its last publish date. A key differentiator is its use of `string-format` for flexible test naming, including the ability to use theory properties, `$idx` (index), and `$no` (number) within the test description string, or even provide a custom function for dynamic naming. It seamlessly integrates with Jest's `describe` and `test` structure, shipping with TypeScript types for enhanced developer experience.

Common errors

```
ReferenceError: theoretically is not defined
```
cause The `theoretically` function was not imported from 'jest-theories' in the test file.

fix Add `import theoretically from 'jest-theories';` at the top of your test file to make the function available.
```
TypeError: Cannot read properties of undefined (reading 'input')
```
cause The `theory` object passed to the test callback is missing the expected property (e.g., 'input'), or the `theories` array is malformed, leading to an undefined access.

fix Verify that your `theories` array contains objects with the correct property names, and that you are accessing them accurately (e.g., `theory.input`). Inspect the `theory` object using `console.log(theory)` inside the test callback.
```
The first argument must be a string or a function.
```
cause The first argument provided to `theoretically` was neither a string for the test name template nor a function for dynamic naming. Often, the `theories` array is mistakenly passed as the first argument.

fix Ensure the first argument is either a string (your test name template, e.g., `'the number {input}...'`) or a function that returns the test name, and the second argument is your array of theory objects.

Warnings

gotcha Carefully review test name formatting strings. The library uses `string-format` syntax, which expects placeholders like `{propertyName}`. Mismatched property names or incorrect syntax will result in unformatted test names or errors.
Fix: Ensure that placeholders in the test name string precisely match properties in your theory objects or use `$idx`/`$no` for index-based naming. Alternatively, provide a function for dynamic naming.
gotcha Using a very large number of theories (e.g., hundreds or thousands) in a single `theoretically` block can significantly increase test execution time and memory consumption, potentially impacting CI/CD performance.
Fix: Consider splitting extremely large theory sets into smaller, more focused groups or using Jest's built-in `test.each` if `jest-theories` specific features like dynamic formatting are not strictly required for all cases.
gotcha The `theory` object passed to the test callback is specific to each iteration. Variables declared outside the callback but intended to be part of the test data should be explicitly included in the theory object.
Fix: Always access test data directly from the `theory` parameter within the test callback to ensure correct scoping for each test run. If external data is needed, ensure it's accessible within the closure or passed as part of the theory.

Install

npm install jest-theories npm
yarn add jest-theories yarn
pnpm add jest-theories pnpm

Imports

theoretically
wrong:
```
const theoretically = require('jest-theories')
```
correct:
```
import theoretically from 'jest-theories'
```
The library provides a default export. While `require` works in CommonJS environments, using `import` is the idiomatic approach in modern JavaScript/TypeScript projects.

Quickstart

Demonstrates how to use `theoretically` with an array of objects to run a single test block with multiple data inputs, using property names for dynamic test descriptions.

import theoretically from 'jest-theories';

// Mock function for demonstration purposes
const NumberToLongString = (num: number): string => {
  if (num === 100) return 'One hundred';
  if (num === 1000) return 'One thousand';
  if (num === 10000) return 'Ten thousand';
  if (num === 100000) return 'One hundred thousand';
  return 'Unknown';
};

describe('NumberToLongString conversion', () => {
    const theories = [
        { input: 100, expected: 'One hundred' },
        { input: 1000, expected: 'One thousand' },
        { input: 10000, expected: 'Ten thousand' },
        { input: 100000, expected: 'One hundred thousand' }
    ];

    theoretically('the number {input} is correctly translated to string', theories, theory => {
        const output = NumberToLongString(theory.input);
        expect(output).toBe(theory.expected);
    });
});

view raw JSON →