Playwright Fixtures Integration

The Playwright Fixtures Integration in this project provides a mechanism to automatically instantiate and inject Page Objects into Playwright tests. By using a centralized fixture factory, developers can avoid manual instantiation of classes within every test block, ensuring that each test receives a fresh, typed instance of the required Page Object bound to the current browser page.

This integration is designed to be agnostic of the class hierarchy; it works equally well with classes extending the built-in RootPageObject and plain TypeScript classes, provided they follow the standard Playwright constructor signature where the first argument is a Page object.
Sources: src/fixtures.ts:25-33, README.md:144-150, skills/playwright-page-object/SKILL.md:154-157

Architecture and Core Logic

The integration centers around the createFixtures function, which transforms a map of Page Object constructors into a set of Playwright fixture definitions. This automation ensures that the lifecycle of Page Objects is managed by the Playwright test runner.

Data Flow for Fixture Injection

When a test requests a fixture (e.g., checkoutPage), the integration performs the following steps:

1. Selection: Identifies the constructor associated with the fixture key from the provided map.
2. Instantiation: Creates a new instance of the class, passing the active Playwright page as the first constructor argument.
3. Execution: Passes the instance to the test via Playwright's use callback.

The diagram shows the lifecycle from the test runner's request to the final injection of the Page Object instance.
Sources: src/fixtures.ts:50-65, src/tests/fixtures.spec.ts:39-49

The createFixtures Function

The createFixtures function is the primary API for integrating Page Objects into the Playwright environment. It maps fixture names to their respective class constructors and returns a Fixtures object compatible with test.extend().

Type Definitions

Implementation Details

The function iterates over the input map and generates an asynchronous fixture function for each entry. This generated function extracts the page from Playwright's test arguments and handles the new keyword instantiation.

// From src/fixtures.ts:50-65
export function createFixtures<T extends PageObjectConstructorsMap>(
	pageObjects: T,
): Fixtures<FixturesFromMap<T>, EmptyFixtures, EmptyFixtures, EmptyFixtures> {
	const fixtures: Record<string, any> = {};

	for (const [key, PageObjectClass] of Object.entries(pageObjects)) {
		fixtures[key] = async ({ page }: { page: Page }, use: any) => {
			const instance = new (PageObjectClass as any)(page);
			await use(instance);
		};
	}

	return fixtures as any;
}

Sources: src/fixtures.ts:50-70

Practical Implementation

Integrating fixtures involves extending the base Playwright test object. This is typically done in a centralized fixtures.ts file within the test directory.

Configuration Example

The following structure demonstrates how to merge multiple Page Objects into the test context.

The diagram illustrates the relationship between the base Playwright test and the custom fixtures generated by the library.
Sources: example/e2e/fixtures.ts:1-12, README.md:152-164

Usage in Tests

Once extended, the Page Objects are available as destructured arguments in the test function.

// From example/e2e/fixtures.ts and README.md
import { test } from "./fixtures";

test("example test", async ({ checkoutPage }) => {
  await checkoutPage.applyPromoCode("SAVE20");
});

Sources: example/README.md:46-51, example/e2e/fixtures.ts:1-12

Requirements and Constraints

To ensure successful integration with createFixtures, the following constraints must be met:

• Constructor Signature: For plain decorated classes (those not using RootPageObject), the first constructor argument must be page: Page.
• Initialization: The createFixtures call should be passed to base.extend() to enable TypeScript type inference for the fixtures.
• Lazy Resolution: Fixtures instantiate the root class, but child selectors remain lazy and only resolve when accessed within the test.

Sources: skills/playwright-page-object/SKILL.md:42-44, README.md:144-150, src/tests/fixtures.spec.ts:52-62

Summary

The Playwright Fixtures Integration simplifies test setup by automating Page Object instantiation. Through the createFixtures utility, the project provides a typed, scalable way to manage the control graph, allowing tests to focus on business logic rather than boilerplate setup. This integration supports incremental adoption by working with both library-specific base classes and standard Playwright-compatible classes.