Runbook 07 — Custom fixtures + composition

Scope

Establish a single deterministic execution entrypoint for all tests.
Centralize environment targeting, authentication, and domain access in fixtures.
Inject test dependencies instead of constructing them inside tests.
Remove hidden state and ad-hoc setup logic from specs.

Fixture contract Single entrypoint

Requirement: all specs import { test, expect } from fixtures/rw. Tests do not construct contexts, API clients, page objects, or auth state directly.

Exit criteria

✔ All specs import from fixtures/rw.
✔ No direct imports from @playwright/test in specs.
✔ UI auth is created in globalSetup and reused via .auth/storageState.json.
✔ API auth is created inside fixture and JWT is owned by fixture.
✔ Domain primitives are injected: api, home, profile, auth, editor, article, settings.
✔ Worker scope and test scope are explicit.

Single entrypoint

const { test, expect } = require('../../fixtures/rw');

AC1

Specs use fixture-owned test and expect. No direct spec-level setup is allowed.

Authentication model

UI authentication

Handled in globalSetup.
API auth preflight runs before UI login.
.auth/emptyState.json is ensured before execution.
.auth/storageState.json is written after successful UI login.
Authenticated tests run under auth-chromium.

API authentication

API client is created inside fixture.
Fixture validates API_BASE_URL, RW_USER_EMAIL, and RW_USER_PASSWORD.
JWT is generated per test execution.
JWT is applied to client inside fixture.
No shared globals.
No token injection in tests.

AC2 AC3

UI auth is owned by setup. API auth is owned by fixture. Tests do not own either.

Injected domain primitives

Fixture	Provides
`api`	Authenticated API client for state seeding and verification
`home`	Home page domain object
`profile`	Profile page domain object
`auth`	Auth page domain object
`editor`	Editor page domain object
`article`	Article page domain object
`settings`	Settings page domain object

test('example', async ({ editor, api }) => {
  // fixtures injected — no setup required
});

AC4

Tests receive domain primitives as inputs. Tests do not construct page objects.

Execution model

Projects

projects: [
  { name: 'auth-chromium', storageState: '.auth/storageState.json' },
  { name: 'unauth-chromium', storageState: '.auth/emptyState.json' }
]

Tagging

@auth → authenticated project
@unauth → unauthenticated project

Project routing

Authenticated and unauthenticated execution is controlled at the project level, not through conditional logic inside tests.

Composition rules

Rule	Requirement
Single entrypoint	All tests import from `fixtures/rw`.
Forbidden	`new PageObject(...)` inside tests
Forbidden	`request.newContext()` inside tests
Forbidden	manual login flows inside tests
Forbidden	hardcoded tokens
Forbidden	environment overrides inside tests
Required	all dependencies come from fixture injection
Required	all UI auth comes from `storageState`; all API auth comes from fixture

AC5

Fixtures define what exists in the test. Tests do not manage auth state, clients, or page construction.

Run commands

Environment contract

export WEB_BASE_URL="http://sut.testlab:3000"
export API_BASE_URL="http://sut.testlab:3001/api"
export RW_USER_EMAIL="rwuser_pw@test.com"
export RW_USER_PASSWORD="password"

Run authenticated tests

npx playwright test --project=auth-chromium

Run unauthenticated tests

npx playwright test --project=unauth-chromium

Run Sprint 07

npx playwright test specs/sprint7

Project names

Valid projects: auth-chromium, unauth-chromium. Do not use --project=chromium unless it exists in config.

Expected outputs

✔ Deterministic execution across runs
✔ No test-order dependency
✔ No shared state leakage
✔ No setup logic inside tests
✔ Artifacts available when enabled: traces, screenshots, videos, junit.xml

Failure modes

Missing environment

[SCENARIO] S3.1 WRONG_ENVIRONMENT

Cause: missing API or web base URL; missing credentials.

SUT unreachable

[SCENARIO] S3.2 SUT_UNREACHABLE

Cause: network failure; DNS failure; routing failure; connection refused.

Auth rejected

[SCENARIO] S3.3 AUTH_REJECTED

Cause: invalid credentials; auth endpoint failure.

Fixture contract violation

[fixtures/rw] CONTRACT VIOLATION

Cause: missing env inputs; empty token; incorrect fixture usage.

Wrong project

Symptoms: test expects auth but runs unauth; missing UI state.

Cause: incorrect @auth / @unauth tagging or wrong selected project.

Fix fixture, environment, or project selection.
Re-run once after change.

Don’t

Do not add setup inside tests.
Do not bypass fixtures to make one test pass.

System positioning

Sprint 07 transitions the framework from tests that manage setup to tests that receive controlled execution context.

Sprint 08 → scalable page object architecture
Sprint 14+ → machine-readable failure artifacts
Sprint 17 → automated release decisions

System flow

UPSTREAM	Sprint 05 — Deterministic data (state correctness) Sprint 06 — Release gates (decision model)
DOWNSTREAM	Sprint 08 — Page object structure at scale Sprint 14 — Structured failure artifacts Sprint 15 — Failure classification (triage) Sprint 17 — Release gate automation

Why this matters

Fixtures define the execution boundary of the system. If this layer is not deterministic, all test results, classifications, and release decisions become unreliable.