pom-conventions

Create one Page Object class per page or component with readonly locators in the constructor and action methods like goto, clickX, and fillY. Tests import these classes, instantiate them with new XxxPage(page), and keep all assertions in the spec file.

Use getByRole first, then getByLabel or getByPlaceholder, then getByText, with getByTestId only as a commented escape hatch. Avoid CSS selectors and XPath, and disambiguate multiple matches with .filter({ hasText }) instead of .first().

No. Page Object methods perform actions only; all expect() calls belong in test files. Use auto-retrying web-first assertions like toBeVisible() or toHaveText() rather than expect(await locator.isVisible()).toBe(true).

waitForTimeout introduces fixed delays that make tests slow and flaky. Callers should instead wait with web-first expects such as toBeVisible() or toBeEnabled(), which auto-retry until the condition holds or the timeout expires.

Compose Page Objects by having a parent page class hold instances of component classes, such as ProgramsPage containing a NewProgramModal. Each component manages its own locators and actions independently.