feat(test)!: set fixtures up on demand, once per worker, and in beforeAll
Merged
KR
1d ago+5866+5866+0123456789012345678901234567890123456789-1114-1114-0123456789012345678901234567890123456789
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
beforeEachandafterEachhooks, 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 aCOLLECTION_ERRORwith the file and line; a fixture that needs nothing writesasync ({}, 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 aCOLLECTION_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 ofextend. 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.beforeAllandafterAllreceive worker fixtures:platform, the worker fixtures of their chain, and on a'worker'engine the engine's fixtures,app, andscreen.SuiteFixturesandSuiteHookFnstay as deprecated aliases.- Engines declare
isolation: 'worker'(defineEngine, the protocol manifest,engine-manifest-1schema).@e2e-dev/mobiledoes: a device keeps its state between attempts. - The mobile benchmark's
buildfixture is{ scope: 'worker', auto: true }; theglobalThismap 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 touse.- It keeps the type, scope, and
autoof what it extends; ascopeorautothat differs is aCOLLECTION_ERRORnaming both. So adeviceoverride on mobile runs once per worker and reachesbeforeAll. - A name like a core fixture, an engine fixture, or an earlier
extendwas 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.tsreads names;fixture-plan.tsresolves order, scope, auto, cycles, and whether code reaches the engine;fixture-use.tsruns the plan at selection for pairs that run.packages/e2e/src/run/fixture-pool.tsreplacesextended-fixtures.ts. A worker fixture holds forwarders fordevice,app, andscreen, so its steps land in whichever test or hook is running.packages/e2e/src/run/suite-attempt.tsopens the short attempt for suite hooks and worker teardowns on a'worker'engine. A failed open is one run error in phaselaunch.- Core fixtures are one table,
CORE_FIXTURESinpackages/core/src/run/fixtures.ts, each with its scope;appandscreenfollowengine.isolation.
Decisions left to the reviewer
- Peer floors:
@e2e-dev/mobilekeepse2eand@e2e-dev/coreat>=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.