Composing Modular Playwright Fixtures with mergeTests and Boxed Steps

Fixture files usually become difficult for organizational reasons before they become difficult for TypeScript. Authentication, database setup, feature flags, API clients, and page models accumulate in one base.extend call. Every change then appears to affect the whole runner, even when the capability belongs to one team or test domain.

Modular fixtures give each capability a clear lifecycle and owner. mergeTests composes those modules into a supported test surface, while fixture boxing controls how much setup detail reaches reports. The goal is not maximum fragmentation; it is a dependency graph that a reviewer can understand without reading a thousand-line fixture registry.

Draw Boundaries Around Capabilities

A fixture module should deliver a coherent capability. An account module might lease a test user and expose credentials. A billing module might create an API client and seeded invoice. A page-model module might depend on the authenticated page. Split by lifecycle and ownership, not by putting every fixture in its own file.

The Playwright fixture guide states that dependencies determine setup and teardown order: when fixture A depends on B, B is prepared first and torn down after A. Non-automatic fixtures are lazy. These rules let modules compose safely only when dependencies remain explicit in fixture parameters.

If two modules need each other's fixtures, the boundary is probably wrong. Move their shared prerequisite into a lower-level module or combine the tightly coupled capability rather than creating a circular conceptual dependency.

Build Small Typed Fixture Modules

Each module extends the Playwright base or a deliberate lower-level test object. Keep resource creation around await use() so teardown ownership remains local.

// fixtures/account-test.ts
import { test as base } from '@playwright/test'

export type Account = {
  id: string
  email: string
}

type AccountFixtures = {
  account: Account
}

export const accountTest = base.extend<AccountFixtures>({
  account: async ({ request }, use) => {
    const response = await request.post('/api/test-support/accounts', {
      data: { role: 'buyer' },
    })
    if (!response.ok()) throw new Error(`Account setup failed: ${response.status()}`)

    const account = (await response.json()) as Account
    await use(account)

    const cleanup = await request.delete(`/api/test-support/accounts/${account.id}`)
    if (!cleanup.ok()) throw new Error(`Account cleanup failed: ${cleanup.status()}`)
  },
})

This module owns the account from creation through cleanup. A consumer does not need to know its endpoint, but a trace or error still names which setup phase failed. Avoid returning partially initialized resources and completing setup in a separate automatic fixture; that makes the lifecycle harder to reason about.

A second module can expose an independent capability:

// fixtures/a11y-test.ts
import { test as base } from '@playwright/test'

type A11yFixtures = {
  accessibilityTags: string[]
}

export const a11yTest = base.extend<A11yFixtures>({
  accessibilityTags: async ({}, use) => {
    await use(['wcag2a', 'wcag2aa'])
  },
})

Configuration-only values may be better expressed as option fixtures when projects need to override them. Do not create setup work for a static constant just to make every value look like a resource.

Compose One Public Test Surface

Use mergeTests in a narrow aggregator. Tests import from this module rather than knowing which capability files exist.

// test-support/index.ts
import { mergeExpects, mergeTests } from '@playwright/test'
import { accountTest } from '../fixtures/account-test'
import { a11yTest } from '../fixtures/a11y-test'
import { accessibilityExpect } from '../assertions/accessibility-expect'
import { orderExpect } from '../assertions/order-expect'

export const test = mergeTests(accountTest, a11yTest)
export const expect = mergeExpects(accessibilityExpect, orderExpect)

The same boundary can merge custom expect objects, giving the suite one import for fixtures and assertions. This is easier to enforce with linting and makes framework features discoverable in editor completion.

Do not expose every fixture to every suite by default. A lightweight unit-like browser project may use a smaller aggregator, while end-to-end tests use the complete domain surface. Composition should reflect needed capabilities, not create a universal dependency bundle.

Make Dependencies Explicit Across Modules

Suppose an authenticated page depends on the leased account. Express that relationship in the fixture signature. Playwright then owns ordering regardless of which module's source file appears first.

// fixtures/session-test.ts
import { test as base, type Page } from '@playwright/test'
import type { Account } from './account-test'

type RequiredFixtures = { account: Account }
type SessionFixtures = { signedInPage: Page }

export const sessionTest = base.extend<RequiredFixtures & SessionFixtures>({
  signedInPage: async ({ page, account }, use) => {
    await page.goto('/sign-in')
    await page.getByLabel('Email').fill(account.email)
    await page.getByRole('button', { name: 'Sign in' }).click()
    await page.getByTestId('current-account').waitFor()
    await use(page)
  },
})

In a real package, make sure the merged object provides account; the type should not pretend an absent runtime fixture exists. A composition smoke spec that requests every public fixture is valuable because TypeScript intersections alone cannot prove the runtime graph was assembled as intended.

Keep fixture scope visible in the implementation. A worker-scoped resource cannot depend on a test-scoped fixture because its lifetime is longer. When a module changes scope, review parallel isolation and teardown, not only compile errors.

Box Fixtures Without Erasing the Story

Fixtures normally appear as steps in UI mode, traces, reports, and errors. Routine helper setup can dominate the report. Tuple options let a fixture use box: true to hide its fixture step. box: 'self' hides the fixture wrapper while preserving explicit steps inside it.

const test = base.extend<{ preparedCatalog: void }>({
  preparedCatalog: [
    async ({ request }, use) => {
      await test.step('Seed searchable products', async () => {
        const response = await request.post('/api/test-support/catalog/reset')
        if (!response.ok()) throw new Error('Catalog seed failed')
      })

      await use()
    },
    { auto: true, box: 'self', title: 'catalog baseline' },
  ],
})

This keeps the meaningful seed step while removing an extra wrapper. Use box: true for stable, uninteresting plumbing whose errors already explain themselves. Do not box new or flaky setup until the team understands its failure modes; report noise is preferable to invisible ownership.

Custom fixture titles can make reports clearer than internal property names. Choose a user-facing capability label, but keep source names sufficiently explicit for code navigation.

Prevent Names, Overrides, and Auto Fixtures From Colliding

Fixture names are an API. Two modules exporting account with different roles or scopes create ambiguous composition. Use names such as buyerAccount, adminAccount, or a typed role option plus one account fixture. Do not depend on merge order as an undocumented override policy.

Automatic fixtures deserve extra scrutiny because they run even when tests do not request them. An auto fixture in a widely shared module can add network calls and failure surface to unrelated specs. Restrict automatic behavior to cross-cutting requirements such as failure artifacts, and document its scope and cost.

Overriding a built-in fixture such as page can be powerful but broad. A fixture named signedInPage makes authentication opt-in and visible. Override page only when every consumer of that aggregator truly requires the altered behavior.

Evolve the Composition Surface Carefully

Treat the aggregator as a framework API. Renaming a fixture, changing its scope, adding an automatic dependency, or replacing a page override can alter many tests even if TypeScript still compiles. Review those changes with a small contract suite that records setup order, confirms isolation, and checks the public fixture names available to representative projects.

Package boundaries need compatibility discipline too. A domain module should declare which Playwright peer version and base test surface it expects, and consumers should upgrade merged modules together when their fixture assumptions change. Avoid importing a private fixture from inside another package just to satisfy one test; promote a supported capability or keep the scenario within that package's own aggregator.

For gradual migration, let old and new aggregators coexist briefly with distinct import paths. Move one test domain, compare reports and runtime behavior, then retire the old surface. A silent alias that points both names at changing implementations makes ownership unclear during the transition.

Analyze Composition Failures

Modularization moves risk from file size to integration boundaries. Diagnose those boundaries directly.

Merge APIs reduce hand-written inheritance chains, but they do not replace architecture. Teams still need rules for naming, scope, dependency direction, and public exports.

Operational Checklist for Fixture Modules

• Group fixtures by cohesive capability and responsible owner.
• Keep setup and cleanup around the same use() boundary.
• Declare fixture dependencies in parameters, including cross-module needs.
• Export one or more intentional aggregators instead of every capability globally.
• Use unique capability-oriented fixture and matcher names.
• Limit automatic fixtures and worker scope to justified cases.
• Add a composition smoke test that requests the public surface.
• Box only stable setup, preserving meaningful internal steps when needed.
• Enforce canonical imports for the merged test and expect objects.

Action Plan

Take the largest fixture registry and map each fixture by owner, scope, dependencies, and cleanup responsibility. Extract one cohesive capability without changing its behavior, merge it through a small test-support module, and run a smoke spec plus representative domain tests. Then inspect the report and apply boxing only where repeated setup obscures the scenario. Continue one capability at a time; the migration is successful when tests request clear resources and a failure still reveals exactly which lifecycle stage broke.