pomwright 1.5.0 → 2.0.0

package/docs/v2/PageObject.md

@@ -1,293 +0,0 @@
-# PageObject (v2)
-
-## Overview
-
-`PageObject` is the core v2 abstraction that wires a Playwright `Page` to:
-
-- A typed locator registry (`add`, `getLocator`, `getNestedLocator`, `getLocatorSchema`).
-- The navigation helper (`navigation`).
-- The session storage helper (`sessionStorage`).
-
-It is intentionally minimal: you provide locator definitions and any post-navigation actions, then compose additional behavior on top.
-
----
-
-## Constructor and generics
-
-```ts
-export abstract class PageObject<
-  LocatorSchemaPathType extends string,
-  Options extends UrlTypeOptions = { baseUrlType: string; urlPathType: string },
-> {
-  protected constructor(
-    page: Page,
-    baseUrl: BaseUrlTypeFromOptions<Options>,
-    urlPath: UrlPathTypeFromOptions<Options>,
-    options?: { label?: string; navOptions?: NavigationOptions },
-  )
-}
-```
-
-### `LocatorSchemaPathType`
-
-A literal union of dot-delimited locator paths. The registry validates this union at compile time and runtime.
-
-```ts
-type Paths =
-  | "common.spinner"
-  | "main"
-  | "main.form@login"
-  | "main.form@login.input@username"
-  | "main.form@login.input@password"
-  | "main.button@login";
-```
-
-### `Options` (`UrlTypeOptions`)
-
-`UrlTypeOptions` controls how `baseUrl`, `urlPath`, and `fullUrl` are typed and interpreted:
-
-```ts
-type UrlTypeOptions = {
-  baseUrlType?: string | RegExp;
-  urlPathType?: string | RegExp;
-};
-```
-
-- If both are strings, `fullUrl` is a string and all navigation methods are available.
-- If either is `RegExp`, `fullUrl` is a `RegExp`, and navigation is limited to URL assertions (`expectThisPage`, `expectAnotherPage`).
-
-### Constructor options
-
-- `label`: Optional label used in navigation and session storage step titles. Defaults to the class name.
-- `navOptions`: Default `NavigationOptions` (`waitUntil`, `waitForLoadState`) used by the navigation helper.
-
----
-
-## Required abstract methods
-
-### `defineLocators()`
-
-Define every locator path for the page using the v2 registry DSL (`add(...).getByRole(...)`, etc.). This is called in the constructor before navigation is created.
-
-### `pageActionsToPerformAfterNavigation()`
-
-Return a list of async callbacks to run after `gotoThisPage()` and `expectThisPage()`.
-
-- Return `[]` to run no actions.
-- Return `null` to skip the actions list entirely.
-
----
-
-## Public properties
-
-| Property | Type | Purpose |
-| --- | --- | --- |
-| `page` | `Page` | Playwright `Page` instance. |
-| `baseUrl` / `urlPath` / `fullUrl` | `string` or `RegExp` | URL values typed based on `UrlTypeOptions`. |
-| `label` | `string` | Label used for navigation and session storage steps. |
-| `sessionStorage` | `SessionStorage` | Session storage helper, labeled with `label`. |
-| `navigation` | `ExtractNavigationType<FullUrlType>` | Navigation helper (methods vary by URL type). |
-| `add` | `AddAccessor<Paths>` | Registry `add` method for locator definitions. |
-| `getLocator` | `GetLocatorAccessor<Paths>` | Terminal locator resolver. |
-| `getNestedLocator` | `GetNestedLocatorAccessor<Paths>` | Full chained locator resolver. |
-| `getLocatorSchema` | `GetLocatorSchemaAccessor<Paths>` | Builder clone for filters/indices/updates. |
-
----
-
-## Example: basic `PageObject` class
-
-```ts
-import { expect, type Page } from "@playwright/test";
-import { PageObject, step } from "pomwright";
-import type { User } from "testData";
-
-type Paths =
-  | "common.spinner"
-  | "main"
-  | "main.form@login"
-  | "main.form@login.input@username"
-  | "main.form@login.input@password"
-  | "main.button@login";
-
-export class LoginPage extends PageObject<Paths> {
-  constructor(page: Page) {
-    super(page, "https://example.com", "/login", { label: "LoginPage" });
-  }
-
-  protected defineLocators(): void {
-    this.add("common.spinner").getByTestId("loading-spinner");
-    this.add("main").locator("main");
-    this.add("main.form@login").getByRole("form", { name: "Login" });
-    this.add("main.form@login.input@username").getByLabel("Username");
-    this.add("main.form@login.input@password").getByLabel("Password");
-    this.add("main.button@login").getByRole("button", { name: "Login" });
-  }
-
-  protected pageActionsToPerformAfterNavigation() {
-    return [
-      async () => {
-        await expect(this.getLocator("common.spinner")).toHaveCount(0);
-        await this.getNestedLocator("main.form@login").waitFor({ state: "visible" });
-      },
-    ];
-  }
-
-  @step()
-  async loginAsUser(user: User) {
-    await this.getNestedLocator("main.form@login.input@username").fill(user.username);
-    await this.getNestedLocator("main.form@login.input@password").fill(user.password);
-    await this.getNestedLocator("main.button@login").click();
-  }
-}
-```
-
----
-
-## Navigation helper details
-
-The navigation helper is created automatically and exposed as `pageObject.navigation`.
-
-### When `fullUrl` is a string
-
-Available methods:
-
-- `goto(urlPathOrUrl, options?)` – resolves paths starting with `/` against `baseUrl`.
-- `gotoThisPage(options?)` – navigates to `fullUrl` and runs `pageActionsToPerformAfterNavigation()`.
-- `expectThisPage(options?)` – waits for `fullUrl` and runs actions.
-- `expectAnotherPage(options?)` – waits for a non-matching URL.
-
-### When `fullUrl` is a `RegExp`
-
-Available methods:
-
-- `expectThisPage(options?)` – matches against the regex.
-- `expectAnotherPage(options?)` – asserts URL does not match.
-
-### Default vs per-call options
-
-You can pass `navOptions` into the `PageObject` constructor and override per call:
-
-```ts
-class OrdersPage extends PageObject<"main"> {
-  constructor(page: Page) {
-    super(page, "https://example.com", "/orders", {
-      label: "OrdersPage",
-      navOptions: { waitUntil: "domcontentloaded", waitForLoadState: "domcontentloaded" },
-    });
-  }
-
-  protected defineLocators() {
-    this.add("main").locator("main");
-  }
-
-  protected pageActionsToPerformAfterNavigation() {
-    return [];
-  }
-}
-
-await ordersPage.navigation.gotoThisPage({ waitUntil: "load" });
-```
-
----
-
-## URL typing examples
-
-### All-string URLs (full navigation support)
-
-```ts
-class ProfilePage extends PageObject<"main"> {
-  constructor(page: Page) {
-    super(page, "https://example.com", "/profile", { label: "ProfilePage" });
-  }
-
-  protected defineLocators() {
-    this.add("main").locator("main");
-  }
-
-  protected pageActionsToPerformAfterNavigation() {
-    return [];
-  }
-}
-```
-
-### RegExp URL path (assert-only navigation)
-
-```ts
-type UrlOptions = { baseUrlType: string; urlPathType: RegExp };
-
-class AccountPage extends PageObject<"main", UrlOptions> {
-  constructor(page: Page) {
-    super(page, "https://example.com", /\/account\/.+/, { label: "AccountPage" });
-  }
-
-  protected defineLocators() {
-    this.add("main").locator("main");
-  }
-
-  protected pageActionsToPerformAfterNavigation() {
-    return [];
-  }
-}
-
-await accountPage.navigation.expectThisPage();
-```
-
----
-
-## Accessing locators
-
-- `getLocator(path)` returns the **terminal** locator only (no ancestor chaining).
-- `getNestedLocator(path)` returns the **fully chained** locator.
-- `getLocatorSchema(path)` returns a mutable clone to add filters, indices, or update/replace definitions before resolving.
-
-```ts
-const terminal = loginPage.getLocator("main.form@login.input@username");
-const chained = loginPage.getNestedLocator("main.form@login.input@username");
-
-const filtered = loginPage
-  .getLocatorSchema("main.form@login.input@username")
-  .filter("main.form@login.input@username", { hasText: /User/i })
-  .getNestedLocator();
-```
-
----
-
-## SessionStorage helper
-
-`PageObject` constructs `SessionStorage` with `label` as a prefix, so step titles are easy to track.
-
-```ts
-await loginPage.sessionStorage.set({ token: "abc" }, { reload: true });
-await loginPage.sessionStorage.setOnNextNavigation({ theme: "dark" });
-const data = await loginPage.sessionStorage.get(["token", "theme"], { waitForContext: true });
-await loginPage.sessionStorage.clear(["token"], { waitForContext: true });
-```
-
----
-
-## Fixture wiring example
-
-```ts
-import { test as base } from "@playwright/test";
-import type { Page } from "@playwright/test";
-import { LoginPage } from "./login.page";
-
-type Fixtures = { loginPage: LoginPage };
-
-export const test = base.extend<Fixtures>({
-  loginPage: async ({ page }, use) => {
-    await use(new LoginPage(page as Page));
-  },
-});
-```
-
----
-
-## Key differences vs v1
-
-- `PageObject` replaces `BasePage` and does **not** carry Playwright `testInfo` or a logger.
-- Registry APIs are fluent (`add(...).getByRole(...)`) instead of schema objects.
-- `getLocator`/`getNestedLocator` are synchronous and do not accept index maps; use `getLocatorSchema(...).nth(...)`.
-- Navigation is built into the base class and depends on URL typing.
-
-See the migration docs in `docs/v1-to-v2-migration` for a step-by-step guide.

package/docs/v2/composing-locator-modules.md

@@ -1,93 +0,0 @@
-# Composing locator modules
-
-When you split locator registration across `*.locators.ts` files, type child modules with
-an inline generic so they accept parent registries with supersets of paths while keeping full fluent
-type precision:
-
-```ts
-// alert.locator.ts
-import type { LocatorRegistry } from "pomwright";
-
-type Paths = "common.alert" | "common.alert.message";
-
-export function defineLocators<Extra extends string = never>(registry: LocatorRegistry<Paths | Extra>) {
-  registry.add("common.alert").locator(".alert-container");
-  registry.add("common.alert.message").locator(".alert-message");
-}
-```
-
-```ts
-// nav.locator.ts
-```
-
-```ts
-// footer.locator.ts
-```
-
-Intermediary parent modules can then pass their full registry directly without casts:
-
-```ts
-// common.locators.ts
-import type { LocatorRegistry } from "pomwright";
-import { type Paths as Alert, defineLocators as addAlert } from "./alert.locators";
-import { type Paths as Nav, defineLocators as addNav } from "./nav.locators";
-import { type Paths as Footer, defineLocators as addFooter } from "./footer.locators";
-
-type Paths = Alert | Nav | Footer | "main";
-
-export function defineLocators<Extra extends string = never>(registry: LocatorRegistry<Paths | Extra>) {
-  addAlert(registry);
-  addNav(registry);
-  addFooter(registry);
-  registry.add("main").locator("main");
-}
-```
-
-Parent modules can then pass their full registry directly without casts:
-
-```ts
-// login.locators.ts
-import type { LocatorRegistry } from "pomwright";
-import { type Paths as Common, defineLocators as addCommon } from "../common.locators";
-
-export type Paths =
-  | Common
-  | "main.form@login"
-  | "main.form@login.input@username"
-  | "main.form@login.input@password"
-  | "main.button@login";
-
-export function defineLocators(registry: LocatorRegistry<Paths>) {
-  addCommon(registry);
-  registry.add("main.form@login").getByRole("form", { name: "Login" });
-  registry.add("main.form@login.input@username").getByLabel("Username");
-  registry.add("main.form@login.input@password").getByLabel("Password");
-  registry.add("main.button@login").getByRole("button", { name: "Login" });
-}
-```
-
-```ts
-// login.page.ts
-import { type Page, expect } from "@playwright/test";
-import { PageObject } from "pomwright";
-import { type Paths, defineLocators } from "./login.locators.ts";
-
-export class LoginPage extends PageObject<Paths> {
-  constructor(page: Page) {
-    super(page, "https://example.com", "/login");
-  }
-
-  protected defineLocators(): void {
-    defineLocators(this.locatorRegistry);
-  }
-
-  protected pageActionsToPerformAfterNavigation() {
-    return [
-      async () => {
-        await this.getNestedLocator("common.nav.logo").waitFor({ state: "visible" });
-        await this.getNestedLocator("main.form@login").waitFor({ state: "visible" });
-      },
-    ];
-  }
-}
-```