feat(test)!: set fixtures up on demand, once per worker, and in beforeAll

Merged
KR
1d ago
+5866-1114

test.extend() fixtures ran for every test registered through that test, named or not, so each setup needed its own exported test. beforeAll and afterAll saw platform only, and nothing could be set up once per worker: the mobile benchmark kept its one-install-per-device promise on globalThis. Closes ENG-1297.

Breaking: fixtures are set up on demand

  • A test sets up the fixtures its body, its beforeEach and afterEach hooks, and those fixtures name by destructuring their first parameter. A fixture nothing names no longer runs.
  • Names are read from the function's source, as Playwright and Vitest do. async (fixtures) => {}, async (_, use) => {}, a rest property, and a bound function are a COLLECTION_ERROR with the file and line; a fixture that needs nothing writes async ({}, use) => {}.
  • A fixture that exists for its side effect takes auto: true.
  • A fixture can name the fixtures declared beside it in the same extend(), in any order; a cycle is a COLLECTION_ERROR.
  • A name the target has no fixture for, and a suite hook or worker fixture that names a test fixture, fail at selection, before any engine starts. A test that does not run on a target is not checked there.
// before: two tests, one per setup
export const test = base.extend<{ project: string }>({ project: ... });
export const taskTest = test.extend<{ task: string }>({ task: ... });

// after: one test, task names project
export const test = base.extend<{ project: string; task: string }>({
  project: async ({ app, agent, screen }, use) => { ... },
  task: async ({ project, agent, screen }, use) => { ... },
});

Worker fixtures, and beforeAll gets them

  • [fn, { scope: 'worker' }], typed with the second type argument of extend. Set up once per worker and target, the first time a test or suite hook names it, torn down when the worker ends, last set up first.
  • beforeAll and afterAll receive worker fixtures: platform, the worker fixtures of their chain, and on a 'worker' engine the engine's fixtures, app, and screen. SuiteFixtures and SuiteHookFn stay as deprecated aliases.
  • Engines declare isolation: 'worker' (defineEngine, the protocol manifest, engine-manifest-1 schema). @e2e-dev/mobile does: a device keeps its state between attempts.
  • The mobile benchmark's build fixture is { scope: 'worker', auto: true }; the globalThis map is gone.
export const test = base.extend<{}, { database: Database }>({
  database: [async ({}, use) => {
    const database = await startDatabase();
    await use(database);
    await database.stop();
  }, { scope: 'worker' }],
});

test.beforeAll(async ({ database, device }) => {
  await database.seed();
  await device.setPermission('camera', 'deny'); // a mobile target
});

Extending a built-in fixture

  • extend({ app: async ({ app }, use) => { await app.open('/dashboard'); await use(app); } }) wraps a built-in, or an earlier fixture of the chain. Inside, the name is the fixture it extends; everyone else gets what it passes to use.
  • It keeps the type, scope, and auto of what it extends; a scope or auto that differs is a COLLECTION_ERROR naming both. So a device override on mobile runs once per worker and reaches beforeAll.
  • A name like a core fixture, an engine fixture, or an earlier extend was refused before.

How it runs

flowchart LR
  C[collect: fixtureNames per body, hook, fixture] --> S[select: planAttempt / planSuiteHook per target]
  S --> W[worker: bindFixtures from the plan]
  W --> T{scope}
  T -- test --> A[set up in the attempt, torn down after afterEach]
  T -- worker --> P[WorkerFixturePool: one instance per definition, torn down in dispose]
  H[beforeAll / afterAll] --> E{engine isolation}
  E -- attempt --> PL[platform + worker fixtures]
  E -- worker --> Q{serial group or e2e mcp?}
  Q -- yes --> O[the open attempt]
  Q -- no --> N[short attempt of its own, results/suite-hooks]
  N -- cannot open / interrupted --> F[hooks still run; device, app, screen throw the reason]
  • packages/e2e/src/collect/fixture-names.ts reads names; fixture-plan.ts resolves order, scope, auto, cycles, and whether code reaches the engine; fixture-use.ts runs the plan at selection for pairs that run.
  • packages/e2e/src/run/fixture-pool.ts replaces extended-fixtures.ts. A worker fixture holds forwarders for device, app, and screen, so its steps land in whichever test or hook is running.
  • packages/e2e/src/run/suite-attempt.ts opens the short attempt for suite hooks and worker teardowns on a 'worker' engine. A failed open is one run error in phase launch.
  • Core fixtures are one table, CORE_FIXTURES in packages/core/src/run/fixtures.ts, each with its scope; app and screen follow engine.isolation.

Decisions left to the reviewer

  • Peer floors: @e2e-dev/mobile keeps e2e and @e2e-dev/core at >=0.23.2, right only if this ships in 0.23.2. If 0.23.2 is cut first, raise both.
  • Code a timed-out test leaves running keeps using a worker fixture's forwarders, which point at whatever runs next. Scoping them by async context breaks teardown code after use(), which resumes in the setup's context. Left as a follow-up.
  • A worker fixture declared in a test file, not a module it imports, gets a new instance each time the file is imported again (retry, serial group, setup test); the old one stays set up until the worker ends. Documented; a collection warning is a possible follow-up.

Made with Claude Opus 5.5 (claude-opus-5-5) in Claude Code, running in T3 Code.