Skip to content
Logo

Each

it.each, test.each, and describe.each declare one test or suite per row of a table. Harness builds .each itself instead of forwarding it to the runner, so it's available on every runner, including mocha and node:test, which have none.

The row is a property

A row reaches the body as row, next to the context, not as extra arguments:

it.each([
  { input: "1 + 1", expected: 2 },
  { input: "2 * 3", expected: 6 },
])("evaluates $input", ({ row }) => {
  expect(evaluate(row.input)).toBe(row.expected);
});

The context stays the body's only argument, so integration keys and row are read the same way. That's also why no integration may provide a key named row.

describe.each passes row to the suite callback next to the suite's scope:

describe.each(dialects)("$name", ({ it, row }) => {
  it("parses a select", () => {
    expect(parse("select 1", row)).toBeDefined();
  });
});

Tables

A table is an array of rows, or a tagged template whose first line is the headings:

it.each`
  a    | b    | sum
  ${1} | ${1} | ${2}
  ${2} | ${3} | ${5}
`("$a + $b", ({ row }) => {
  expect(Number(row.a) + Number(row.b)).toBe(row.sum);
});

An array row's type is inferred from the array. A tagged template's row is Record<string, unknown>, since its headings are plain text.

A table that can't produce rows throws EachTableError when you call .each, not later: an empty array, a value that's neither form, or a template whose last row is missing a cell. A table with no rows would register no tests, and the run would pass with nothing tested.

Titles

Titles are interpolated the way jest and vitest do it:

tokenbecomes
$keythat property of an object row
$# or %#the row's index, from 0
%$the row's index, from 1
%s, %d, %i, %fthe next value of an array row, or the row itself
%j, %o, %pthe same, as JSON
%%a literal %

Rows and identity

Each it.each row has its own identity: identity.row is its index. Two rows with identical titles still get different per-test state.

A describe.each row is only in the suite's name, so put a placeholder from the row in the title. Otherwise the tests in every row share a path. See Test identity.