Using Raw Locators
Relevant source files
The following files were used as context for generating this wiki page:
Using raw locators within playwright-page-object refers to the ability to define page object accessors that return standard Playwright Locator objects instead of library-specific abstractions like PageObject. This "locator-first" approach allows developers to leverage decorator-driven selector composition while maintaining direct access to the full Playwright API without additional wrapper layers.
This feature is primary intended for incremental adoption of the framework or for scenarios where the overhead of a full Page Object Model (POM) is not required. It ensures that relative selector logic is still centralized and typed, but the end result of an accessor is the native Playwright primitive.
Sources: README.md:12-25, README.md:175-185, skills/playwright-page-object/SKILL.md:105-115
Architectural Overview
The architecture of raw locator usage relies on the library's ability to resolve selectors lazily based on the declared type of the class accessor. When an accessor is typed as Locator, the decorator logic binds a Playwright Locator to that property, resolving it relative to the class's established root context.
The diagram shows how the root decorator establishes the context, allowing child decorators to resolve native Playwright locators for direct use.
Sources: README.md:73-86, src/tests/decorators/selectors.spec.ts:50-65
Implementation Patterns
Declaring Raw Locators
To use raw locators, a class must first be decorated with a root selector (e.g., @RootSelector). Individual properties are then decorated with child selectors (e.g., @Selector, @SelectorByRole) and declared using the TypeScript accessor keyword with the Locator type.
@RootSelector("CheckoutPage")
class CheckoutPage {
constructor(readonly page: Page) {}
@Selector("PromoCodeInput")
accessor PromoCodeInput!: Locator;
}
Sources: README.md:94-105, example/e2e/page-objects/CheckoutPage.ts:18-20
Interaction and Usage
Unlike accessors returning a PageObject (which require accessing the .$ property), raw locator accessors return the locator directly. This allows for standard Playwright method chaining.
| Approach | Access Method | Example |
|---|---|---|
| Raw Locator | Direct access | this.PromoCodeInput.fill("CODE") |
| PageObject | via .$ property | this.PromoCode.$.fill("CODE") |
Sources: example/e2e/page-objects/CheckoutPage.ts:13-20, example/e2e/checkout.spec.ts:20-25
Selector Mapping and Resolution
The framework maps decorators directly to Playwright's Locator resolution methods. When using raw locators, these methods are called on the parent's context to produce the final locator.
Supported Child Decorators for Locators
The following table details how child decorators map to native Playwright calls when the accessor is a raw Locator:
| Decorator | Playwright Mapping |
|---|---|
@Selector(id) | parent.getByTestId(id) |
@Selector() | Identity (returns parent/root) |
@ListSelector(id) | parent.getByTestId(new RegExp(id)) |
@SelectorByRole(role, options) | parent.getByRole(role, options) |
@SelectorByText(text) | parent.getByText(text) |
@SelectorByLabel(label) | parent.getByLabel(label) |
Sources: README.md:213-225, src/tests/decorators/selectors.spec.ts:46-150
Sequential Resolution Flow
When a raw locator is accessed, the library follows a specific flow to ensure the locator is correctly bound to the current DOM state.
This sequence illustrates the lazy resolution of the raw locator upon accessor access.
Sources: README.md:27-35, src/tests/decorators/selectors.spec.ts:192-210
Incremental Adoption Strategy
Raw locators are the primary vehicle for the "Locator-first" adoption stage. This allows teams to:
- Decorate existing Page Object classes without changing their inheritance.
- Provide typed access to elements that previously used string-based
page.locator()calls. - Maintain compatibility with existing test logic that expects raw Playwright objects.
Sources: README.md:175-185, skills/playwright-page-object/SKILL.md:105-115
Conclusion
Using raw locators provides a lightweight entry point into the playwright-page-object framework. By returning native Playwright Locator objects, the system enforces structural organization and relative selector logic without forcing a departure from the standard Playwright API. This makes it a robust option for teams prioritizing direct Playwright access or incremental refactoring of legacy test suites.