Migration v1 → v2

v2 removes deprecated APIs and tightens contracts. There is no compatibility shim — update call sites.

Breaking changes

Removed APIs

ListStrictSelector

Selector(id) already produces the same locator chain. Replace mechanically:

- @ListStrictSelector("CartItem")
+ @Selector("CartItem")
  accessor item!: Locator;

PageObject.waitProp / waitPropAbsence / waitNoValue

All three assumed an internal data-prop-* attribute convention — your framework was expected to mirror component props to data-prop-{name} attributes for testing. Both waitProp and waitNoValue used that same convention internally; waitNoValue specifically checked for the absence of data-prop-$value.

Express the same intent directly with Playwright's .expect():

- await checkout.PromoCode.waitProp("disabled", "true");
+ await checkout.PromoCode.expect().toHaveAttribute("data-prop-disabled", "true");

- await checkout.PromoCode.waitPropAbsence("disabled", "true");
+ await checkout.PromoCode.expect().not.toHaveAttribute("data-prop-disabled", "true");

- await checkout.PromoCode.waitNoValue();
+ await checkout.PromoCode.expect().not.toHaveAttribute("data-prop-$value");

If your project does not use the data-prop-* convention and you originally wanted to assert that a form control's value is empty, use Playwright's toHaveValue instead — but note this is a different assertion (DOM .value vs. an attribute):

await checkout.PromoCode.expect().toHaveValue("");

PageObject.expect() returns Playwright's assertion API bound to the underlying locator. If you prefer working with the raw locator directly, import Playwright's expect and pass control.$:

import { expect } from "@playwright/test";

await expect(checkout.PromoCode.$).toHaveAttribute("data-prop-disabled", "true");

Renamed APIs

filterByTestId → filterByItemTestId

The rename clarifies the self-vs-descendant distinction. The behavior is unchanged.

- const item = list.filterByTestId("CartItem_2");
+ const item = list.filterByItemTestId("CartItem_2");

The companion filterByHasTestId(id) matches rows that contain a descendant with data-testid={id}. See Lists for the full distinction.

getItemByIdMask → getItemByTestId(new RegExp(...))

The mask was always a regex pattern. The new form is explicit:

- const item = list.getItemByIdMask("CartItem_\\d+");
+ const item = list.getItemByTestId(/CartItem_\d+/);

Widened signatures

waitText and waitValue accept RegExp

await checkout.PromoCode.waitText(/applied/i);
await checkout.PromoCode.waitValue(/^\d{6}$/);
await checkout.PromoCode.waitValue(42);  // number → coerced to "42"

@ListSelector and @ListRootSelector accept string | RegExp

Strings are still used as regex patterns (escape metacharacters if needed). Pass a RegExp for full control:

@ListSelector("CartItem_")             // matches /CartItem_/
@ListSelector(/^CartItem_\d+$/)        // matches CartItem_1, CartItem_2, ...

New strictness

PageObject subclasses cannot be passed as factory arguments

In v1, @Selector("X", MyPageObjectSubclass) silently produced broken instances. In v2, it throws at decoration time:

- @Selector("PromoCode", PromoPageObject)
- accessor PromoCode!: PromoPageObject;

+ @Selector("PromoCode")
+ accessor PromoCode = new PromoPageObject();

Use the initializer form for PageObject subclasses. The factory-argument form is reserved for plain classes whose constructor accepts a Locator (see Custom Controls).

ListPageObject constructor validates itemType

Invalid item types throw at construction time instead of failing silently on access:

new ListPageObject("not a class");  // throws
new ListPageObject(42);              // throws
new ListPageObject(CartItemControl); // ok
new ListPageObject(new CartItemControl()); // ok

Update strategy

1. Run a grep pass for the removed and renamed APIs:

   ListStrictSelector | waitNoValue | waitProp | waitPropAbsence
   filterByTestId | getItemByIdMask

2. Apply the table above — each row is a one-line change.
3. Run TypeScript. The compiler catches most of the rest.
4. Run your test suite. Behavior of equivalent calls is unchanged.

See also

• Lists — filterByItemTestId vs filterByHasTestId.
• Custom Controls — factory-argument form.
• Built-In POM — initializer form for PageObject.