Merge pull request #3 from sergeyshmakov/2026-03-18-decoupling-decorators

2026 03 18 decoupling decorators

Author: sergeyshmakov

.github/dependabot.yml

@@ -8,6 +8,8 @@ updates:
       day: "monday"
       time: "06:00"
       timezone: "UTC"
+    allow:
+      - dependency-type: "direct"
     open-pull-requests-limit: 5
     labels:
       - "dependencies"

.lintstagedrc

@@ -1,3 +1,3 @@
 {
-	"*.{ts,tsx,js,jsx,json}": "npx @biomejs/biome check --write"
+	"*.{js,jsx,ts,tsx,cjs,mjs,cts,mts,json,jsonc,md}": "biome check --write --no-errors-on-unmatched"
 }

README.md

@@ -0,0 +1,36 @@
+import { test } from "./fixtures";
+
+/**
+ * E2E tests demonstrating external controls (not extending PageObject)
+ * used via trailing constructor/factory decorator metadata.
+ */
+
+test.beforeEach(async ({ page }) => {
+	await page.goto("/");
+});
+
+test("constructor/factory metadata — PromoCode fills and Apply button clicks via external controls", async ({
+	externalCheckoutPage,
+}) => {
+	// PromoCode uses ExternalInputControl as the trailing decorator argument.
+	await externalCheckoutPage.PromoCode.fill("SAVE20");
+
+	// ApplyPromoButton uses a trailing factory function.
+	await externalCheckoutPage.ApplyPromoButton.locator.click();
+});
+
+test("constructor metadata — ExternalButtonControl is constructed with the resolved locator", async ({
+	externalCheckoutPage,
+}) => {
+	// We use .first() since there are multiple Remove buttons on the page.
+	await externalCheckoutPage.FirstRemoveButton.locator
+		.first()
+		.waitFor({ state: "visible" });
+	await externalCheckoutPage.FirstRemoveButton.locator.first().click();
+});
+
+test("applyPromoCode helper uses both external control creation paths", async ({
+	externalCheckoutPage,
+}) => {
+	await externalCheckoutPage.applyPromoCode("DISCOUNT10");
+});

example/e2e/external-controls.spec.ts

@@ -1,9 +1,14 @@
 import { test as base } from "@playwright/test";
 import { createFixtures } from "playwright-page-object";
 import { CheckoutPage } from "./page-objects/CheckoutPage";
+import { ExternalCheckoutPage } from "./page-objects/ExternalCheckoutPage";
 
-export const test = base.extend<{ checkoutPage: CheckoutPage }>(
+export const test = base.extend<{
+	checkoutPage: CheckoutPage;
+	externalCheckoutPage: ExternalCheckoutPage;
+}>(
 	createFixtures({
 		checkoutPage: CheckoutPage,
+		externalCheckoutPage: ExternalCheckoutPage,
 	}),
 );

example/e2e/fixtures.ts

@@ -3,6 +3,7 @@ import {
 	ListPageObject,
 	ListStrictSelector,
 	PageObject,
+	RootPageObject,
 	RootSelector,
 	Selector,
 	SelectorByRole,
@@ -11,7 +12,7 @@ import { CartItemControl } from "./CartItemControl";
 import { ButtonControl } from "./controls/ButtonControl";
 
 @RootSelector("CheckoutPage")
-export class CheckoutPage extends PageObject {
+export class CheckoutPage extends RootPageObject {
 	/** PageObject approach: use PromoCode.$.fill() */
 	@Selector("PromoCodeInput")
 	accessor PromoCode = new PageObject();

example/e2e/page-objects/CheckoutPage.ts

@@ -0,0 +1,52 @@
+import type { Page } from "@playwright/test";
+import { RootSelector, Selector, SelectorByRole } from "playwright-page-object";
+import { ExternalButtonControl } from "./controls/ExternalButtonControl";
+import { ExternalInputControl } from "./controls/ExternalInputControl";
+
+/**
+ * Demonstrates a root page object that does NOT extend `PageObject`.
+ *
+ * The class has the standard Playwright POM constructor `(page: Page)`.
+ * `@RootSelector` wires the page object context automatically, so `this.page`
+ * is fully preserved on the class itself.
+ *
+ * Child selector decorators then construct external controls from the resolved
+ * locator using the trailing constructor/factory argument.
+ *
+ * Two child control patterns shown:
+ * 1. Constructor as the last decorator arg
+ * 2. Factory function as the last decorator arg
+ */
+@RootSelector("CheckoutPage")
+export class ExternalCheckoutPage {
+	constructor(readonly page: Page) {}
+
+	/**
+	 * Constructor signature.
+	 * `new ExternalInputControl(resolvedLocator)` is called at access time.
+	 */
+	@Selector("PromoCodeInput", ExternalInputControl)
+	accessor PromoCode = undefined as unknown as ExternalInputControl;
+
+	/**
+	 * Factory function signature.
+	 * Useful when the construction logic should stay inline with the selector.
+	 */
+	@SelectorByRole(
+		"button",
+		{ name: "Apply" },
+		(locator) => new ExternalButtonControl(locator),
+	)
+	accessor ApplyPromoButton = undefined as unknown as ExternalButtonControl;
+
+	/**
+	 * Constructor signature again, with a different selector.
+	 */
+	@SelectorByRole("button", { name: "Remove" }, ExternalButtonControl)
+	accessor FirstRemoveButton = undefined as unknown as ExternalButtonControl;
+
+	async applyPromoCode(code: string) {
+		await this.PromoCode.fill(code);
+		await this.ApplyPromoButton.locator.click();
+	}
+}

example/e2e/page-objects/ExternalCheckoutPage.ts

@@ -0,0 +1,23 @@
+import type { Locator } from "@playwright/test";
+
+/**
+ * An example of an external control that does NOT extend `PageObject`.
+ * The selector decorator constructs it with the resolved locator.
+ */
+export class ExternalButtonControl {
+	constructor(private readonly _locator: Locator) {}
+
+	/** The resolved Playwright locator for this button. */
+	get locator(): Locator {
+		return this._locator;
+	}
+
+	async click() {
+		await this.locator.click();
+	}
+
+	async expectVisible() {
+		const { expect } = await import("@playwright/test");
+		await expect(this.locator).toBeVisible();
+	}
+}

example/e2e/page-objects/controls/ExternalButtonControl.ts

@@ -0,0 +1,23 @@
+import type { Locator } from "@playwright/test";
+
+/**
+ * An external input control that accepts the locator as a constructor argument.
+ * Compatible with selector decorators that pass the constructor as metadata.
+ * Does NOT extend `PageObject`.
+ */
+export class ExternalInputControl {
+	constructor(private readonly _locator: Locator) {}
+
+	get locator(): Locator {
+		return this._locator;
+	}
+
+	async fill(value: string) {
+		await this._locator.fill(value);
+	}
+
+	async expectVisible() {
+		const { expect } = await import("@playwright/test");
+		await expect(this._locator).toBeVisible();
+	}
+}