{"id":15347,"library":"jest-theories","title":"Jest Theories","description":"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.","status":"maintenance","version":"1.5.1","language":"javascript","source_language":"en","source_url":"https://github.com/RobPethick/jest-theories","tags":["javascript","typescript"],"install":[{"cmd":"npm install jest-theories","lang":"bash","label":"npm"},{"cmd":"yarn add jest-theories","lang":"bash","label":"yarn"},{"cmd":"pnpm add jest-theories","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; jest-theories extends Jest's testing capabilities and requires Jest to be installed in the project for execution.","package":"jest","optional":false},{"reason":"Runtime dependency for parsing and formatting test description strings used in `theoretically`'s first argument.","package":"string-format","optional":false}],"imports":[{"note":"The library provides a default export. While `require` works in CommonJS environments, using `import` is the idiomatic approach in modern JavaScript/TypeScript projects.","wrong":"const theoretically = require('jest-theories')","symbol":"theoretically","correct":"import theoretically from 'jest-theories'"}],"quickstart":{"code":"import theoretically from 'jest-theories';\n\n// Mock function for demonstration purposes\nconst NumberToLongString = (num: number): string => {\n  if (num === 100) return 'One hundred';\n  if (num === 1000) return 'One thousand';\n  if (num === 10000) return 'Ten thousand';\n  if (num === 100000) return 'One hundred thousand';\n  return 'Unknown';\n};\n\ndescribe('NumberToLongString conversion', () => {\n    const theories = [\n        { input: 100, expected: 'One hundred' },\n        { input: 1000, expected: 'One thousand' },\n        { input: 10000, expected: 'Ten thousand' },\n        { input: 100000, expected: 'One hundred thousand' }\n    ];\n\n    theoretically('the number {input} is correctly translated to string', theories, theory => {\n        const output = NumberToLongString(theory.input);\n        expect(output).toBe(theory.expected);\n    });\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Add `import theoretically from 'jest-theories';` at the top of your test file to make the function available.","cause":"The `theoretically` function was not imported from 'jest-theories' in the test file.","error":"ReferenceError: theoretically is not defined"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'input')"},{"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.","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.","error":"The first argument must be a string or a function."}],"ecosystem":"npm"}