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:
| token | becomes |
|---|---|
$key | that property of an object row |
$# or %# | the row's index, from 0 |
%$ | the row's index, from 1 |
%s, %d, %i, %f | the next value of an array row, or the row itself |
%j, %o, %p | the 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.
