jest-theories

library1.5.1jsnpmunverified

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.

testing

npm install jest-theories

github ↗package ↗

INSTALL

IMPORT

SIG · JEST-THEORIES

jest-theories

testingjavascriptv1.5.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

theoretically

✓ import theoretically from 'jest-theories'

✗ const theoretically = require('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.

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

Debug

Known issues

gotchaCarefully 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.

affects: >=1.0.0

gotchaUsing 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.

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: theoretically is not defined

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

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.

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.

Upgrade

Version history

1.5.1latest on npm

Audit

Dependencies

jestrequiredPeer dependency; jest-theories extends Jest's testing capabilities and requires Jest to be installed in the project for execution.

string-formatrequiredRuntime dependency for parsing and formatting test description strings used in `theoretically`'s first argument.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/RobPethick/jest-theories ↗

packagehttps://www.npmjs.com/package/jest-theories ↗