Merge pull request #6 from sergeyshmakov/2026-03-18-fix-list-page-object-api

fix: fix ambiguous list page object api

Author: sergeyshmakov

README.md

@@ -227,11 +227,14 @@ Use `RootPageObject` for root-decorated classes that are created directly from P
 class CheckoutPage extends RootPageObject {}
 ```
 
+Root page objects remain page-first: construct them with `new CheckoutPage(page)`.
+
 ### `PageObject`
 
 Use `PageObject` for nested controls. It provides:
 
 - raw locator access via `$`
+- `page` derived from the current root context via `root.page()`
 - Playwright assertions via `.expect()`
 - wait helpers such as `.waitVisible()` and `.waitCount()`
 - nested control composition through selector decorators
@@ -244,6 +247,8 @@ await control.expect().toBeVisible();
 await cartItems.waitCount(0);
 ```
 
+Nested `PageObject` subclasses use the default constructor shape `(root?: Locator, selector?: SelectorType)`. If a nested subclass needs custom constructor arguments, implement `cloneWithContext()` so it can rebuild itself with the new `root` and `selector`.
+
 Wait helpers:
 
 | Method | Description |
@@ -277,8 +282,12 @@ Useful APIs:
 - `list.items.at(-1)`
 - `for await (const item of list.items) { ... }`
 - `await list.count()`
-- `await list.first()`
-- `await list.filterByText("Apple")`
+- `list.first()`
+- `list.second()`
+- `list.filterByText("Apple")`
+- `list.filterByText("Apple").first()`
+
+Indexing and search helpers such as `first()`, `second()`, `at()`, `getItemByText()`, and `getItemByRole()` return a single item page object. Filter helpers such as `filter()`, `filterByText()`, and `filterByTestId()` return a narrower `ListPageObject`, so chain `.first()` or `.at(...)` when you need one matched item.
 
 ## Fixtures
 

example/README.md

@@ -100,8 +100,13 @@ for await (const item of checkoutPage.CartItems.items) {
 ```typescript
 const widgetItems = checkoutPage.CartItems.filterByText("Widget");
 await widgetItems.expect().toHaveCount(2);
+
+const widgetB = checkoutPage.CartItems.filterByText("Widget B").first();
+await widgetB.RemoveButton.$.click();
 ```
 
+`filterByText()` returns a narrowed `ListPageObject`. Call `.first()`, `.second()`, or `.at(...)` when you need a single matched item.
+
 ## Full API
 
 See the [main package README](../README.md) for the complete API reference.

example/e2e/checkout.spec.ts

@@ -42,10 +42,10 @@ test("should iterate over cart items with for await", async ({
 	}
 });
 
-test("should find item by text using filterByText and remove it", async ({
+test("should narrow the list by text and remove the first matched item", async ({
 	checkoutPage,
 }) => {
-	const widgetB = checkoutPage.CartItems.filterByText("Widget B");
+	const widgetB = checkoutPage.CartItems.filterByText("Widget B").first();
 	await widgetB.waitVisible();
 	await widgetB.RemoveButton.$.click();
 	await checkoutPage.expectCartHasItemCount(2);

example/package-lock.json

@@ -47,7 +47,8 @@ When entering a codebase, detect these first:
    - `createFixtures(...)`
    - manual `new MyPage(page)`
 4. Custom nested `PageObject` constructors:
-   - if a nested `PageObject` subclass does not use the default constructor shape, it must implement `cloneWithContext()`
+   - the default nested `PageObject` constructor shape is `(root?: Locator, selector?: SelectorType)`
+   - if a nested `PageObject` subclass does not use that shape, it must implement `cloneWithContext()`
 
 Preserve the user's current style. Do not force a migration to the built-in POM if the codebase already uses plain classes or external controls successfully.
 
@@ -107,7 +108,7 @@ class CheckoutPage extends RootPageObject {}
 - the user wants built-in waits or `.expect()`
 - the control is reused compositionally under selector decorators
 
-If a nested `PageObject` subclass adds a custom constructor, either keep the default constructor shape or implement `cloneWithContext()` explicitly.
+Nested `PageObject` instances derive `page` from their current root context. If a nested `PageObject` subclass adds a custom constructor, either keep the default `(root?: Locator, selector?: SelectorType)` shape or implement `cloneWithContext()` explicitly.
 
 ### Choose `ListPageObject` when
 
@@ -191,8 +192,11 @@ class CheckoutPage extends RootPageObject {
 When using the built-in classes:
 
 - actions go through `control.$`
+- nested `PageObject` instances derive `page` from `root.page()`
 - waits and assertions come from `PageObject`
 - `ListPageObject` handles repeated child components
+- `ListPageObject` indexing/search helpers such as `first()`, `second()`, `at()`, and `getItemByText()` return one item page object
+- `ListPageObject` filter helpers such as `filter()`, `filterByText()`, and `filterByTestId()` return a narrower `ListPageObject`, so chain `.first()` or `.at(...)` when one item is needed
 - `RootPageObject` is the correct root base class
 
 Examples:
@@ -201,6 +205,7 @@ Examples:
 await control.$.click();
 await control.expect().toBeVisible();
 await items.waitCount(0);
+await items.filterByText("Apple").first().expect().toBeVisible();
 ```
 
 ## Fixtures

skills/playwright-page-object/SKILL.md

@@ -57,7 +57,6 @@ function RootSelectorBy(selector: SelectorType) {
 					constructor(...args: TArgs) {
 						const page = resolvePage(args[0], target.name);
 						super(...args);
-						this.page = page;
 						this.root = page.locator("body");
 						this.selector = selector;
 					}

src/decorators/rootSelectors.ts

@@ -1,4 +1,4 @@
-import type { Locator, Page } from "@playwright/test";
+import type { Locator } from "@playwright/test";
 import { PageObject, type SelectorType } from "./PageObject";
 
 /**
@@ -23,7 +23,6 @@ export class ListPageObject<
 	protected itemType?:
 		| TItem
 		| (new (
-				page?: Page,
 				root?: Locator,
 				selector?: SelectorType,
 		  ) => TItem);
@@ -32,23 +31,15 @@ export class ListPageObject<
 	 * @param itemType - PageObject class or instance for each list item.
 	 *   - **Class**: Use when items use the default constructor.
 	 *   - **Instance**: Use when items need a custom constructor with specific arguments.
-	 * @param page - Playwright page (optional when nested)
 	 * @param root - Root locator (set by decorators)
 	 * @param selector - Selector function (set by decorators)
 	 */
 	constructor(
-		itemType?:
-			| TItem
-			| (new (
-					page?: Page,
-					root?: Locator,
-					selector?: SelectorType,
-			  ) => TItem),
-		page?: Page,
+		itemType?: TItem | (new (root?: Locator, selector?: SelectorType) => TItem),
 		root?: Locator,
 		selector?: SelectorType,
 	) {
-		super(page, root, selector);
+		super(root, selector);
 		this.itemType = itemType;
 	}
 
@@ -57,24 +48,22 @@ export class ListPageObject<
 			itemType?:
 				| TItem
 				| (new (
-						page?: Page,
 						root?: Locator,
 						selector?: SelectorType,
 				  ) => TItem),
-			page?: Page,
 			root?: Locator,
 			selector?: SelectorType,
 		) => this;
 
-		return new ListPageObjectClass(this.itemType, root.page(), root, selector);
+		return new ListPageObjectClass(this.itemType, root, selector);
 	}
 
 	/**
 	 * Returns the item at the given index (0-based). Use `-1` for last item.
 	 * @param index - Item index
 	 * @returns PageObject for the item at that index
 	 */
-	getItemByIndex(index: number) {
+	getItemByIndex(index: number): TItem {
 		return this.resolveItem((p) => p.nth(index));
 	}
 
@@ -83,60 +72,58 @@ export class ListPageObject<
 	 * @param index - Item index (0-based; -1 = last, -2 = second-to-last, etc.)
 	 * @returns PageObject for the item at that index
 	 */
-	at(index: number) {
+	at(index: number): TItem {
 		return this.getItemByIndex(index);
 	}
 
 	/**
 	 * Returns items matching the given Playwright filter options.
 	 * @param options - Playwright locator filter (e.g. `{ hasText: 'foo' }`)
-	 * @returns PageObject for the filtered item(s)
+	 * @returns Narrowed list page object containing the filtered item(s)
 	 */
-	filter(options: Parameters<Locator["filter"]>[0]) {
-		return this.resolveItem((p) => p.filter(options));
+	filter(options: Parameters<Locator["filter"]>[0]): this {
+		return this.resolveList((p) => p.filter(options));
 	}
 
 	/**
 	 * Returns items containing the given text.
 	 * @param text - Text to match (string or regex)
-	 * @returns PageObject for the matching item(s)
+	 * @returns Narrowed list page object containing the matching item(s)
 	 */
-	filterByText(text: string) {
-		return this.resolveItem((p) => p.filter({ hasText: text }));
+	filterByText(text: string | RegExp): this {
+		return this.filter({ hasText: text });
 	}
 
 	/**
 	 * Returns items that contain an element with the given test id.
-	 * Requires `page` to be set.
 	 * @param id - Test id (string or regex)
-	 * @returns PageObject for the matching item(s)
+	 * @returns Narrowed list page object containing the matching item(s)
 	 */
-	filterByTestId(id: string | RegExp) {
-		const page = this.page;
-		if (!page) {
-			throw new Error(
-				"[ListPageObject] filterByTestId requires page to be set",
-			);
-		}
-		return this.resolveItem((p) => p.filter({ has: page.getByTestId(id) }));
+	filterByTestId(id: string | RegExp): this {
+		return this.filter({ has: this.page.getByTestId(id) });
 	}
 
 	/**
 	 * Returns the item whose test id matches the given regex pattern.
 	 * @param mask - Regex pattern string for test id
 	 * @returns PageObject for the matching item
 	 */
-	getItemByIdMask(mask: string) {
-		return this.resolveItem((p) => p.getByTestId(new RegExp(mask)));
+	getItemByIdMask(mask: string): TItem {
+		return this.filterByTestId(new RegExp(mask)).first();
 	}
 
 	/** Returns the first item (index 0). */
-	first() {
+	first(): TItem {
 		return this.at(0);
 	}
 
+	/** Returns the second item (index 1). */
+	second(): TItem {
+		return this.at(1);
+	}
+
 	/** Returns the last item (index -1). */
-	last() {
+	last(): TItem {
 		return this.at(-1);
 	}
 
@@ -145,17 +132,19 @@ export class ListPageObject<
 	 * @param text - Text to match (string or regex)
 	 * @returns PageObject for the matching item
 	 */
-	getItemByText(text: string) {
-		return this.resolveItem((p) => p.getByText(text));
+	getItemByText(text: string | RegExp): TItem {
+		return this.filterByText(text).first();
 	}
 
 	/**
 	 * Returns the item matching the given ARIA role and options.
 	 * @param args - Same as {@link Locator.getByRole}
 	 * @returns PageObject for the matching item
 	 */
-	getItemByRole(...args: Parameters<Locator["getByRole"]>) {
-		return this.resolveItem((p) => p.getByRole(...args));
+	getItemByRole(...args: Parameters<Locator["getByRole"]>): TItem {
+		return this.resolveList((p) =>
+			p.filter({ has: p.getByRole(...args) }),
+		).first();
 	}
 
 	/**
@@ -230,17 +219,21 @@ export class ListPageObject<
 		return items;
 	}
 
+	protected resolveList(selector: SelectorType): this {
+		return this.cloneWithContext(this.locator, selector);
+	}
+
 	protected resolveItem(selector: SelectorType): TItem {
 		if (!this.itemType) {
-			return new PageObject(this.page, this.locator, selector) as TItem;
+			return new PageObject(this.locator, selector) as TItem;
 		}
 
 		if (PageObject.isInstance(this.itemType)) {
 			return this.itemType.cloneWithContext(this.locator, selector) as TItem;
 		}
 
 		if (PageObject.isClass(this.itemType)) {
-			return new this.itemType(this.page, this.locator, selector);
+			return new this.itemType(this.locator, selector);
 		}
 
 		return selector(this.locator) as unknown as TItem;

src/page-objects/ListPageObject.ts

@@ -15,7 +15,6 @@ export type SelectorType = (p: Locator) => Locator;
  */
 export type PageObjectConstructor<TPageObject extends PageObject = PageObject> =
 	new (
-		page?: Page,
 		root?: Locator,
 		selector?: SelectorType,
 	) => TPageObject;
@@ -36,16 +35,13 @@ export type PageObjectConstructor<TPageObject extends PageObject = PageObject> =
  * ```
  */
 export class PageObject {
-	page?: Page;
 	root?: Locator;
 
 	/**
-	 * @param page - Playwright page (optional when nested)
 	 * @param root - Root locator (set by decorators)
 	 * @param selector - Selector function (set by decorators)
 	 */
-	constructor(page?: Page, root?: Locator, selector?: SelectorType) {
-		this.page = page;
+	constructor(root?: Locator, selector?: SelectorType) {
 		this.root = root;
 		this._selector = selector;
 	}
@@ -64,6 +60,16 @@ export class PageObject {
 		return this.locator;
 	}
 
+	get page(): Page {
+		if (!this.root) {
+			throw new Error(
+				`[PageObject] Empty root in ${this.constructor.name}. Cannot resolve page. Maybe "RootSelector" or "Selector" was skipped?`,
+			);
+		}
+
+		return this.root.page();
+	}
+
 	/**
 	 * Resolved locator for this page object.
 	 * Throws if `RootSelector` or `Selector` decorators were not applied.
@@ -124,7 +130,7 @@ export class PageObject {
 	 */
 	cloneWithContext(root: Locator, selector: SelectorType): this {
 		const PageObjectClass = this.constructor as PageObjectConstructor<this>;
-		return new PageObjectClass(root.page(), root, selector);
+		return new PageObjectClass(root, selector);
 	}
 
 	/** Waits for the element to become visible. */

src/page-objects/PageObject.ts

@@ -17,11 +17,9 @@ export type RootPageObjectConstructor<
  * Use `PageObject` for nested child controls created by selector decorators.
  */
 export class RootPageObject extends PageObject {
-	declare page: Page;
-
-	// biome-ignore lint/complexity/noUselessConstructor: constructor enforces the public Page-first root contract
 	constructor(page: Page) {
-		super(page);
+		void page;
+		super();
 	}
 
 	static isRootClass<TArgs extends [Page, ...unknown[]]>(