Agent Detection Checklist

Relevant source files

The following files were used as context for generating this wiki page:

• skills/playwright-page-object/SKILL.md
• README.md
• src/page-objects/PageObject.ts
• src/tests/page-objects/PageObject.advanced.spec.ts
• example/README.md

The Agent Detection Checklist is a framework within the playwright-page-object library designed to help developers and AI agents identify the existing architectural patterns in a codebase. Because the library supports multiple implementation styles—ranging from raw Playwright locators to fully encapsulated Page Object Models (POM)—detecting the current state is critical for maintaining consistency during incremental adoption or refactoring.

This checklist ensures that new tests or page objects align with the project's established "Root Style," "Child Output Style," and "Instantiation Style."

Sources: skills/playwright-page-object/SKILL.md:20-25, README.md:16-25

1. Detection of Root Style

The first step in analyzing a playwright-page-object implementation is determining how top-level classes are structured. The library allows for two primary root styles: plain decorated classes and built-in root objects.

• Plain Decorated Class: A standard class where the first constructor argument is a Playwright Page. It uses @RootSelector(...) but does not inherit from library base classes.
• Built-in Root (RootPageObject): A class that extends RootPageObject. This is typically used when the project requires out-of-the-box helpers like assertions and waits at the root level.

Root Style Comparison

Feature	Plain Decorated Class	RootPageObject
Inheritance	None (Plain Class)	Extends RootPageObject
Constructor	(page: Page, ...rest)	Handled by base class
Usage Context	Incremental adoption	Full POM framework

Sources: skills/playwright-page-object/SKILL.md:27-31, README.md:120-125

The diagram above illustrates the logic used to identify the root architecture of a page object class.
Sources: skills/playwright-page-object/SKILL.md:46-52, README.md:47-55

2. Detection of Child Output Style

The library is flexible regarding what a decorated accessor returns. Identifying this style is crucial for determining how to interact with elements in tests.

1. Locator-first: Accessors return a raw Playwright Locator. Interaction is done via standard Playwright methods (e.g., this.PromoCodeInput.fill()).
2. External Controls: Accessors return a custom class (not extending PageObject) that typically accepts a Locator in its constructor.
3. Built-in PageObject: Accessors return a PageObject instance, providing the $ property and built-in wait/assertion methods.
4. ListPageObject: Used for collections of repeated elements, providing async iteration and filtering.

Sources: skills/playwright-page-object/SKILL.md:32-37, README.md:73-85

Implementation Patterns

// Locator-first (README.md:94)
@Selector("PromoCodeInput")
accessor PromoCodeInput!: Locator;

// External Control (README.md:112)
@Selector("PromoCodeInput", ExternalInputControl)
accessor PromoCode!: ExternalInputControl;

// Built-in POM (README.md:138)
@Selector("PromoCodeInput")
accessor PromoCode = new PageObject();

3. Instantiation and Fixture Detection

The checklist requires identifying how page objects are brought into tests. This affects how the "Agent" should write new test files.

• createFixtures(...): Look for base.extend(createFixtures({ ... })) in fixture files. This is the preferred method for automatic dependency injection.
• Manual Instantiation: Look for new MyPage(page) inside test blocks or beforeEach hooks.

Sources: skills/playwright-page-object/SKILL.md:38-40, example/README.md:46-55

The sequence diagram demonstrates the two ways instances are provided to the test environment.
Sources: README.md:173-188, src/tests/fixtures.spec.ts:38-45

4. Custom Component Rules

If the detection reveals custom PageObject subclasses, the following rules must be verified:

• Constructor Shape: If a subclass of PageObject uses a custom constructor that deviates from (page, root, selector), it must implement cloneWithContext().
• Nesting constraints: @RootSelector must never be used on a class extending PageObject directly; it is reserved for the root class or RootPageObject.
• Lazy Resolution: All decorated properties must use the accessor keyword to ensure selectors remain lazy and are rebuilt only when accessed.

Sources: skills/playwright-page-object/SKILL.md:41-43, src/page-objects/PageObject.ts:88-92, src/tests/page-objects/PageObject.advanced.spec.ts:87-95

Summary of Decision Rules

Situation	Recommended Action	Source
User has existing standard classes	Use Plain Decorated Root	SKILL.md:70
Codebase uses helpers consistently	Use RootPageObject	SKILL.md:85
Repeated UI patterns found	Use External Controls	SKILL.md:106
Element requires built-in waits	Use PageObject	SKILL.md:94
Repeated list items found	Use ListPageObject	SKILL.md:101

The Agent Detection Checklist ensures that regardless of the entry point, the implementation maintains the structural integrity and chosen abstraction level of the project.

Sources: skills/playwright-page-object/SKILL.md:68-115, README.md:190-205