feat(test): add test.each and test.for

Merged
BA
5h ago
+1050-34

Adds test.each(rows) and test.for(rows), the Vitest shape: one test per row, titled from the row.

test.each([{ user: 'Ada' }, { user: 'Grace' }])('signs in as $user', async ({ user }, { app }) => { ... });
test.each([[1, 2, 3]])('%i + %i = %i', async (a, b, sum, { app }) => { ... });
test.for([[1, 2]])('pair %i and %i', async ([a, b], { app }) => { ... });
  • Titles: $name / $name.path read an object row; %s %d %i %f %j %o take an array row's items in order; %# is the index, %$ the row number, %% a percent sign. Formatting is one pass, so a value is never read as a token (packages/e2e/src/collect/each.ts). A title is always one line: an Error shows as its name and message, not its stack.
  • test.each spreads the rows into the body's args when every row is an array (decided once per table, as Vitest does); test.for passes the row whole. The fixtures come last in both.
  • Fixtures are set up on demand since #1891, from the names a body destructures. A row body takes its row first, so its names are read from the parameter after the row (fixtureNames(fn, what, source, position) in packages/e2e/src/collect/fixture-names.ts). (row, fixtures) => {} and (...args) => {} are a COLLECTION_ERROR, as (fixtures) => {} is for a plain test.
  • Each row goes through the same registration as test() (packages/e2e/src/collect/registry.ts), so options (skip, tags, timeout), serial groups, and duplicate-title checks work as for a plain test. Every row is located at its test.each call, through a helper too: the source location now reads the whole stack, not the default 10 frames.
  • Empty or non-array rows, and a tagged template table, throw COLLECTION_ERROR.
  • Types: TestAPI.each / TestAPI.for in packages/core/src/types.ts; pinned in tests/types/sdk-types.ts, incl. tuple rows typed per position.

Out of scope: describe.each, and .each chained after skip/only/skipIf.

Issue

Part of #1855 (Test runner row).

Verified

Ran it locally: yes

  • testbed, built CLI, scratch file tests/zz-each.e2e.ts: object rows and spread rows that fill the real todos page under a beforeEach, test.for, rows that name no fixture, an Error row, and skipped rows.
node node_modules/e2e/dist/cli/bin.js run tests/zz-each.e2e.ts
   ↓ |web| tests/zz-each.e2e.ts > skipped left [not this one]
   ↓ |web| tests/zz-each.e2e.ts > skipped right [not this one]
   ✓ |web| tests/zz-each.e2e.ts > each > adds todo Buy milk 347ms
   ✓ |web| tests/zz-each.e2e.ts > each > adds todo Walk dog 117ms
   ✓ |web| tests/zz-each.e2e.ts > each > adds One and Two, 2 todos 127ms
   ✓ |web| tests/zz-each.e2e.ts > each > adds Three and Four, 2 todos 114ms
   ✓ |web| tests/zz-each.e2e.ts > each > adds Ship runner (row 1) 102ms
   ✓ |web| tests/zz-each.e2e.ts > 1 + 2 = 3 3ms
   ✓ |web| tests/zz-each.e2e.ts > 2 + 3 = 5 4ms
   ✓ |web| tests/zz-each.e2e.ts > rejects with RangeError: too far 9ms
 Test Files  1 passed (1)
      Tests  8 passed | 2 skipped (10)
  • e2e list shows one entry per row with the formatted title.
  • Failure path: a body that takes the fixtures whole, a rest parameter, and a template table each exit 2 before anything runs.
tests/zz-each-bad.e2e.ts:3: test "signs in as Ada" must destructure parameter 2, where it takes the fixtures, as in ({ app, screen }) => {}; it takes "fixtures". e2e sets up only the fixtures a function names there
tests/zz-each-bad.e2e.ts:3: test "adds 1 and 2" must destructure parameter 3, where it takes the fixtures, as in ({ app, screen }) => {}; it takes "...numbers". e2e sets up only the fixtures a function names there
tests/zz-each-bad.e2e.ts: test.each() takes an array of rows, not a template literal table; write each row as an object or an array

Checklist

  • Changeset added (pnpm changeset) for any change to a published package, or the change is testbed, docs, or CI only.
  • Breaking change: title carries !, the changeset body names what breaks and what replaces it, and the deprecation warning landed a window earlier (stability policy in CONTRIBUTING.md).
  • Docs updated in the same PR: the docs/**/*.mdx page for the behavior, and skills/e2e/ if the skill describes it.
  • Contract change: emitted .d.ts reviewed, tests/types/sdk-types.ts updated; wire change edits the schema and both fixtures.
  • Engine contract change (e2e/engine): changesets for e2e, @e2e-dev/web, and @e2e-dev/mobile.