agentic-playwright fixtures.instructions.md

Fixtures and Dependency Injection

Critical

• ALWAYS use fixtures for dependency injection. NEVER instantiate a page object manually in a test file (new AppPage(page) is forbidden).
• ALWAYS import test and expect from fixtures/pom/test-options.ts. NEVER import them from @playwright/test in spec files.
• Page object fixtures live in fixtures/pom/page-object-fixture.ts. Do not create per-page fixture files.
• Lifecycle (setup/teardown) fixtures live in fixtures/helper/helper-fixture.ts. They use the Playwright use() callback pattern.
• Plain utility functions (no fixture lifecycle) live in helpers/ — not in fixtures/. See the helpers skill.
• Every new fixture must be typed: extend FrameworkFixtures (for page objects) or HelperFixtures (for lifecycle) — do not add untyped fixtures.
• Teardown uses use(). Setup runs before use(), data is yielded via use(data), teardown runs after use() — even if the test fails.
• New fixture categories (not page objects, not lifecycle helpers) must be declared in their own fixtures/{category}/{name}-fixture.ts file and merged into test-options.ts via mergeTests().
• Do not promote one-off API calls to helper fixtures. Helper fixtures are reserved for setup/teardown reused across 3+ spec files — see the api-testing skill (Phase 8).

Fixture Architecture

fixtures/pom/test-options.ts              ← Single import point (merges all fixtures)
    ├── fixtures/pom/page-object-fixture.ts       ← Page object fixtures
    ├── fixtures/api/api-request-fixture.ts       ← API request fixture (apiRequest for tests)
    └── fixtures/helper/helper-fixture.ts         ← Setup/teardown fixtures (important recurring operations)

test-options.ts uses mergeTests() to combine fixture layers:

import { test as base, mergeTests, request } from '@playwright/test';
import { test as pageObjectFixture } from './page-object-fixture';
import { test as apiRequestFixture } from '../api/api-request-fixture';
import { test as helperFixture } from '../helper/helper-fixture';

const test = mergeTests(pageObjectFixture, apiRequestFixture, helperFixture);
const expect = base.expect;
export { test, expect, request };