Skip to content

Parameterized Tests

Run the same assertion over many inputs with it.each and describe.each.

What you'll learn

  • Why parameterized tests beat copy-pasted test cases
  • Using it.each and describe.each with arrays and tables
  • Naming parameterized tests clearly from the data
  • Keeping parameterized tests readable and debuggable

Concept

DRY Your Test Cases

When a function should behave the same way for many inputs, copy-pasting a test for each case bloats the file and hides the pattern. A parameterized test defines the assertion once and feeds it a table of inputs and expected outputs. The runner generates one test case per row, each with its own name and pass/fail status, so you get the coverage of many tests with the maintenance of one.

it.each

In Vitest and Jest, it.each(table)(name, fn) creates a test per row. The table can be an array of arrays, an array of objects, or a tagged template literal that reads like a table. The name string can interpolate %$ placeholders so each generated test has a descriptive title showing its inputs. describe.each does the same at the describe level, grouping a whole block of tests per row.

Naming Matters

A parameterized test is only useful if each generated case is identifiable when it fails. Use the name template to include the inputs: it.each(cases)("add(%i, %i) -> %i", (a, b, expected) => ...). When case 47 fails, the report should show add(2, 3) -> 5 not case 47. Good names turn a wall of failures into a readable list of broken scenarios.

Readability and Limits

Parameterized tests shine for pure functions and data transformations. They are less helpful when each case needs different setup or different assertions — forcing those into a table makes the test harder to read than separate tests. If the setup diverges, split into multiple parameterized groups or fall back to individual tests. Always include edge cases (empty, zero, negative, boundary) in the table.

In Practice

When building a parameterized table, include the obvious cases, the boundary values, and the edge cases that have bitten you before — empty arrays, zero, negative numbers, very large inputs, unicode strings. Use the tagged-template form of it.each for readability when the table is wide: it reads like a spreadsheet and reviewers can scan the rows. If a single row fails, the runner reports the row's name, so invest in naming. For async cases, make the test function async and await inside the body — the runner handles each row as its own test. When the table grows past twenty rows, consider whether some rows are testing the same thing with different data and could be consolidated, or whether the function has too many branches and should be simplified.

Example

              import { describe, it, expect } from "vitest";

function classify(n: number): "negative" | "zero" | "positive" {
  if (n < 0) return "negative";
  if (n === 0) return "zero";
  return "positive";
}

describe("classify", () => {
  it.each([
    [-5, "negative"],
    [-1, "negative"],
    [0, "zero"],
    [1, "positive"],
    [42, "positive"],
  ])("classify(%i) returns %s", (input, expected) => {
    expect(classify(input)).toBe(expected);
  });
});
            

One assertion, five generated test cases. Each case's name shows its input and expected output, so a failure pinpoints exactly which scenario broke.

Try it

  • JSON Formatter

    Format the input tables you feed to it.each.

  • Code Diff

    Compare expected vs actual for each parameterized row.

Common mistakes

The mistake

Generic names like 'case %i' for parameterized tests

The fix

Interpolate the inputs into the name so failures are self-describing: 'add(%i, %i) -> %i' beats 'case 3'.

The mistake

Forcing divergent setups into one parameterized table

The fix

If each row needs different setup, split into separate tests or groups. A table that branches on row type is harder to read than individual tests.

Practice Parameterized Tests

4 exercises

Practice Parameterized Tests

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors