pomwright 1.5.0 → 2.0.0

package/skills/pomwright-v2-migration/references/class-migration.md

@@ -1,266 +0,0 @@
-# Class Migration: Inheritance, Constructor, Generics, Abstract Methods
-
-## Inheritance change
-
-```ts
-// v1
-import { BasePage } from "pomwright";
-class MyPage extends BasePage<Paths> { ... }
-
-// v1.5 bridge
-import { BasePageV1toV2 } from "pomwright";
-class MyPage extends BasePageV1toV2<Paths> { ... }
-
-// v2
-import { PageObject } from "pomwright";
-class MyPage extends PageObject<Paths> { ... }
-```
-
-## Constructor signature
-
-v1/bridge constructor:
-
-```ts
-constructor(
-  page: Page,
-  testInfo: TestInfo,
-  baseUrl: string | RegExp,
-  urlPath: string | RegExp,
-  pocName: string,
-  pwrl: PlaywrightReportLogger,
-)
-```
-
-v2 constructor:
-
-```ts
-constructor(
-  page: Page,
-  baseUrl: string | RegExp,
-  urlPath: string | RegExp,
-  options?: { label?: string; navOptions?: NavigationOptions },
-)
-```
-
-Changes:
-- `testInfo` removed entirely (not needed by PageObject).
-- `pocName` replaced by `options.label`. Defaults to `this.constructor.name`, so it can usually be omitted unless the v1 pocName differed from the class name.
-- `PlaywrightReportLogger` removed from constructor; use the `log` fixture from `pomwright` in tests instead.
-- Optional `navOptions` added for configuring `waitUntil` and `waitForLoadState` defaults.
-
-### Migration example: concrete page object
-
-```ts
-// v1
-import type { Page, TestInfo } from "@playwright/test";
-import { BasePage, type PlaywrightReportLogger } from "pomwright";
-
-export default class LoginPage extends BasePage<Paths> {
-  constructor(page: Page, testInfo: TestInfo, pwrl: PlaywrightReportLogger) {
-    super(page, testInfo, "https://example.com", "/login", "LoginPage", pwrl);
-  }
-}
-
-// v2
-import type { Page } from "@playwright/test";
-import { PageObject } from "pomwright";
-
-export default class LoginPage extends PageObject<Paths> {
-  constructor(page: Page) {
-    super(page, "https://example.com", "/login");
-    // label defaults to "LoginPage" (class name), so no need to pass it
-  }
-}
-```
-
-If pocName differed from the class name:
-
-```ts
-// v1
-super(page, testInfo, "https://example.com", "/login", "MyCustomLabel", pwrl);
-
-// v2
-super(page, "https://example.com", "/login", { label: "MyCustomLabel" });
-```
-
-### Migration example: abstract base class
-
-v1 abstract base classes typically wrap `baseUrl` and forward the rest:
-
-```ts
-// v1
-import type { Page, TestInfo } from "@playwright/test";
-import { BasePage, type PlaywrightReportLogger } from "pomwright";
-
-export default abstract class AppBase<Paths extends string> extends BasePage<Paths> {
-  constructor(page: Page, testInfo: TestInfo, urlPath: string, pocName: string, pwrl: PlaywrightReportLogger) {
-    super(page, testInfo, "http://localhost:8080", urlPath, pocName, pwrl);
-  }
-}
-
-// v2
-import type { Page } from "@playwright/test";
-import { type NavigationOptions, PageObject, type UrlPathTypeFromOptions, type UrlTypeOptions } from "pomwright";
-
-type BaseOptions<Options extends UrlTypeOptions> = {
-  baseUrlType: string;
-  urlPathType: UrlPathTypeFromOptions<Options>;
-};
-
-export default abstract class AppBase<
-  Paths extends string,
-  Options extends UrlTypeOptions = { baseUrlType: string; urlPathType: string },
-> extends PageObject<Paths, BaseOptions<Options>> {
-  protected constructor(
-    page: Page,
-    urlPath: UrlPathTypeFromOptions<BaseOptions<Options>>,
-    options?: { label?: string; navOptions?: NavigationOptions },
-  ) {
-    super(page, "http://localhost:8080", urlPath, options);
-  }
-}
-```
-
-Concrete subclass in v2:
-
-```ts
-import type { Page } from "@playwright/test";
-import AppBase from "../base/appBase";
-
-export default class LoginPage extends AppBase<Paths> {
-  constructor(page: Page) {
-    super(page, "/login");
-  }
-}
-```
-
-## Generic type parameters
-
-### Simple case (string baseUrl, string urlPath)
-
-```ts
-// v1
-class MyPage extends BasePage<Paths> { ... }
-
-// v2 (identical shape, just different base class)
-class MyPage extends PageObject<Paths> { ... }
-```
-
-### With URL type options (e.g. RegExp urlPath)
-
-```ts
-// v1
-import { type BasePageOptions, type ExtractUrlPathType, BasePage } from "pomwright";
-
-class ColorPage extends BasePage<
-  Paths,
-  { urlOptions: { baseUrlType: string; urlPathType: RegExp } }
-> { ... }
-
-// v2 (flattened options shape, renamed types)
-import { type UrlTypeOptions, type UrlPathTypeFromOptions, PageObject } from "pomwright";
-
-class ColorPage extends PageObject<
-  Paths,
-  { baseUrlType: string; urlPathType: RegExp }
-> { ... }
-```
-
-### URL type helper renames
-
-| v1 | v2 |
-|---|---|
-| `BasePageOptions` | `UrlTypeOptions` |
-| `ExtractBaseUrlType<T>` | `BaseUrlTypeFromOptions<T>` |
-| `ExtractUrlPathType<T>` | `UrlPathTypeFromOptions<T>` |
-| `ExtractFullUrlType<T>` | `FullUrlTypeFromOptions<T>` |
-
-The options shape itself flattened:
-
-```ts
-// v1
-{ urlOptions: { baseUrlType: string; urlPathType: RegExp } }
-
-// v2
-{ baseUrlType: string; urlPathType: RegExp }
-```
-
-## Required abstract methods
-
-v2 `PageObject` requires two abstract methods:
-
-### defineLocators()
-
-Same as bridge. See [locator-registration.md](locator-registration.md) for the full DSL mapping.
-
-```ts
-protected defineLocators(): void {
-  this.add("main").locator("main");
-  this.add("main.button@login").getByRole("button", { name: "Login" });
-}
-```
-
-### pageActionsToPerformAfterNavigation()
-
-New in v2. Returns an array of async callbacks to run after `navigation.gotoThisPage()`, or `null` if none are needed.
-
-```ts
-// No post-navigation actions
-protected pageActionsToPerformAfterNavigation(): (() => Promise<void>)[] | null {
-  return null;
-}
-
-// With post-navigation actions (e.g., wait for loading state)
-protected pageActionsToPerformAfterNavigation(): (() => Promise<void>)[] | null {
-  return [
-    async () => {
-      await this.getNestedLocator("main.spinner").waitFor({ state: "hidden" });
-    },
-  ];
-}
-```
-
-If the v1 page object had post-navigation logic scattered in tests (e.g., waiting for elements after `page.goto`), consider moving it here.
-
-## Properties available on PageObject
-
-| Property | Description |
-|---|---|
-| `this.page` | Playwright `Page` instance |
-| `this.baseUrl` | Base URL (string or RegExp) |
-| `this.urlPath` | URL path (string or RegExp) |
-| `this.fullUrl` | Composed full URL |
-| `this.label` | PageObject identifier (defaults to class name) |
-| `this.sessionStorage` | SessionStorage helper |
-| `this.navigation` | Navigation helper (type depends on URL types) |
-| `this.locatorRegistry` | Internal LocatorRegistry (for sharing with external `defineLocators` functions) |
-| `this.add` | Locator registration accessor |
-| `this.getLocator` | Terminal locator accessor |
-| `this.getNestedLocator` | Chained locator accessor |
-| `this.getLocatorSchema` | Schema query builder accessor |
-
-## Removed v1 properties
-
-| v1 property | v2 replacement |
-|---|---|
-| `this.testInfo` | Not available; use test fixture if needed |
-| `this.log` | Not built-in; use `log` fixture from `pomwright` |
-| `this.pocName` | `this.label` |
-| `this.selector` | Not available; locator strategies are in the registry |
-| `this.locators` (GetLocatorBase) | `this.locatorRegistry` / `this.add` / `this.getLocator` etc. |
-
-## Import changes
-
-```ts
-// v1
-import { BasePage, GetByMethod, type BasePageOptions, type ExtractUrlPathType,
-         type ExtractBaseUrlType, type ExtractFullUrlType, type GetLocatorBase,
-         type PlaywrightReportLogger, type LocatorSchemaWithoutPath } from "pomwright";
-
-// v2
-import { PageObject, type UrlTypeOptions, type UrlPathTypeFromOptions,
-         type BaseUrlTypeFromOptions, type FullUrlTypeFromOptions,
-         type LocatorRegistry, type NavigationOptions } from "pomwright";
-```
-
-Remove imports that no longer exist: `GetByMethod`, `BasePage`, `BasePageV1toV2`, `BasePageOptions`, `ExtractUrlPathType`, `ExtractBaseUrlType`, `ExtractFullUrlType`, `GetLocatorBase`, `LocatorSchemaWithoutPath`.

package/skills/pomwright-v2-migration/references/fixture-and-helpers.md

@@ -1,423 +0,0 @@
-# Fixtures and Helpers: Navigation, SessionStorage, @step, Logging
-
-## Fixture migration
-
-v1 fixtures inject `page`, `log`, and `testInfo` into PageObject constructors. v2 fixtures only inject `page`.
-
-```ts
-// v1
-import TestPage from "./testPage.page";
-import { test as base } from "pomwright";
-
-type Fixtures = {
-  testPage: TestPage;
-};
-
-const test = base.extend<Fixtures>({
-  testPage: async ({ page, log }, use, testInfo) => {
-    const testPage = new TestPage(page, testInfo, log);
-    await use(testPage);
-  },
-});
-
-export { test };
-
-// v2
-import TestPage from "./testPage.page";
-import { test as base } from "pomwright";
-
-type Fixtures = {
-  testPage: TestPage;
-};
-
-const test = base.extend<Fixtures>({
-  testPage: async ({ page }, use) => {
-    const testPage = new TestPage(page);
-    await use(testPage);
-  },
-});
-
-export { test };
-```
-
-Key changes:
-- Remove `testInfo` parameter from fixture callback (no longer needed by PageObject).
-- Remove `log` parameter from fixture callback (no longer injected into PageObject).
-- Constructor call simplified to `new TestPage(page)`.
-- The `log` fixture from `pomwright` is still available in tests if needed for test-level logging.
-
-## Navigation helper
-
-v2 `PageObject` exposes a `navigation` property with URL-based navigation methods. This replaces manual `page.goto()` patterns from v1.
-
-### Available when fullUrl is string (baseUrl: string, urlPath: string)
-
-```ts
-// Navigate to the PageObject's own URL
-await poc.navigation.gotoThisPage();
-
-// Navigate to a different path under the same baseUrl
-await poc.navigation.goto("/other-path");
-
-// Assert current page matches this PageObject's URL
-await poc.navigation.expectThisPage();
-
-// Assert current page does NOT match this PageObject's URL
-await poc.navigation.expectAnotherPage();
-```
-
-### Available when fullUrl is RegExp (baseUrl or urlPath is RegExp)
-
-```ts
-// Only assertion methods available (no goto - can't construct URL from RegExp)
-await poc.navigation.expectThisPage();
-await poc.navigation.expectAnotherPage();
-```
-
-### Navigation options
-
-```ts
-// At construction time (defaults for all navigation calls)
-super(page, "https://example.com", "/login", {
-  navOptions: {
-    waitUntil: "networkidle",
-    waitForLoadState: "domcontentloaded",
-  },
-});
-
-// Per navigation call (overrides defaults)
-await poc.navigation.gotoThisPage({
-  waitUntil: "commit",
-  waitForLoadState: "load",
-});
-```
-
-### Post-navigation actions
-
-The `pageActionsToPerformAfterNavigation()` method runs automatically after `navigation.gotoThisPage()` and `navigation.expectThisPage()`:
-
-```ts
-protected pageActionsToPerformAfterNavigation(): (() => Promise<void>)[] | null {
-  return [
-    async () => {
-      // Wait for page to be ready
-      await this.getNestedLocator("main.spinner").waitFor({ state: "hidden" });
-    },
-    async () => {
-      // Additional setup
-      await this.getNestedLocator("main.content").waitFor({ state: "visible" });
-    },
-  ];
-}
-```
-
-### Migration from v1 navigation patterns
-
-```ts
-// v1 (manual navigation in tests)
-test("login flow", async ({ loginPage }) => {
-  await loginPage.page.goto(loginPage.fullUrl);
-  await loginPage.page.waitForLoadState("networkidle");
-  // ... test logic
-});
-
-// v2 (navigation helper)
-test("login flow", async ({ loginPage }) => {
-  await loginPage.navigation.gotoThisPage();
-  // post-navigation actions run automatically
-  // ... test logic
-});
-```
-
-## SessionStorage helper
-
-Available on PageObject as `this.sessionStorage`. API changed from v1.
-
-### Constructor
-
-```ts
-// v1: SessionStorage was instantiated internally by BasePage
-// v2: SessionStorage is instantiated internally by PageObject
-// Both expose it as this.sessionStorage
-
-// v2 also supports standalone usage:
-import { SessionStorage } from "pomwright";
-const sessionStorage = new SessionStorage(page, { label: "MyLabel" });
-```
-
-### Method signatures
-
-```ts
-// set: write items to sessionStorage
-await poc.sessionStorage.set({ token: "abc", theme: "dark" });
-await poc.sessionStorage.set({ token: "abc" }, { reload: true });        // reload page after
-await poc.sessionStorage.set({ token: "abc" }, { waitForContext: true }); // wait for page context
-
-// setOnNextNavigation: queue items to be written on next page navigation
-await poc.sessionStorage.setOnNextNavigation({ token: "abc" });
-
-// get: read items from sessionStorage
-const all = await poc.sessionStorage.get();                              // all items
-const specific = await poc.sessionStorage.get(["token", "theme"]);       // specific keys
-const waited = await poc.sessionStorage.get(["token"], { waitForContext: true });
-
-// clear: remove items from sessionStorage
-await poc.sessionStorage.clear();                                        // all items
-await poc.sessionStorage.clear("token");                                 // specific key
-await poc.sessionStorage.clear(["token", "theme"]);                      // specific keys
-await poc.sessionStorage.clear("token", { waitForContext: true });       // with wait
-```
-
-### v1 -> v2 signature changes
-
-| v1 | v2 |
-|---|---|
-| `.set(states, reload: boolean)` | `.set(states, { reload?: boolean; waitForContext?: boolean })` |
-| `.get()` | `.get(keys?, { waitForContext?: boolean })` |
-| `.clear()` | `.clear(keys?, { waitForContext?: boolean })` |
-
-## @step decorator
-
-v2 provides a `@step` decorator that wraps methods in `test.step()` for Playwright reporting.
-
-```ts
-import { step } from "pomwright";
-
-class LoginPage extends PageObject<Paths> {
-  // Step title defaults to "LoginPage.login"
-  @step
-  async login(username: string, password: string) {
-    await this.getNestedLocator("main.form.input@username").fill(username);
-    await this.getNestedLocator("main.form.input@password").fill(password);
-    await this.getNestedLocator("main.form.button@submit").click();
-  }
-
-  // Custom step title
-  @step("Perform logout")
-  async logout() {
-    await this.getNestedLocator("topMenu.button@logout").click();
-  }
-
-  // With Playwright step options
-  @step({ box: true })
-  async waitForDashboard() {
-    await this.getNestedLocator("main.dashboard").waitFor({ state: "visible" });
-  }
-
-  // Custom title + options
-  @step("Submit login form", { box: true, timeout: 5000 })
-  async submitForm() {
-    await this.getNestedLocator("main.form.button@submit").click();
-  }
-}
-```
-
-### Decorator forms
-
-| Form | Description |
-|---|---|
-| `@step` | No parentheses; title defaults to `ClassName.methodName` |
-| `@step()` | Empty call; same as `@step` |
-| `@step("title")` | Custom step title |
-| `@step({ box: true })` | Playwright step options |
-| `@step("title", { box: true })` | Custom title + options |
-
-### Migration from v1 manual test.step patterns
-
-```ts
-// v1 (manual step wrapping in the POC)
-async login(username: string) {
-  await test.step("LoginPage.login", async () => {
-    const input = await this.getNestedLocator("main.form.input@username");
-    await input.fill(username);
-  });
-}
-
-// v2 (decorator)
-@step()
-async login(username: string) {
-  await this.getNestedLocator("main.form.input@username").fill(username);
-}
-```
-
-## Logging
-
-### v1: Logger injected into constructor
-
-```ts
-// v1
-class LoginPage extends BasePage<Paths> {
-  constructor(page: Page, testInfo: TestInfo, pwrl: PlaywrightReportLogger) {
-    super(page, testInfo, "https://example.com", "/login", "LoginPage", pwrl);
-  }
-
-  async doSomething() {
-    this.log.info("Doing something");  // this.log available on BasePage
-  }
-}
-
-// v1 fixture
-const test = base.extend<Fixtures>({
-  loginPage: async ({ page, log }, use, testInfo) => {
-    await use(new LoginPage(page, testInfo, log));
-  },
-});
-```
-
-### v2: Logger decoupled from PageObject
-
-PageObject does not have a built-in `this.log`. If logging is needed:
-
-**Option A: Use the `log` fixture in tests (recommended)**
-
-```ts
-import { test } from "pomwright";
-
-test("login flow", async ({ page, log }) => {
-  log.info("Starting login flow");
-  const loginPage = new LoginPage(page);
-  // ...
-});
-```
-
-**Option B: Pass logger to PageObject manually**
-
-```ts
-import { type PlaywrightReportLogger, PageObject } from "pomwright";
-
-class LoginPage extends PageObject<Paths> {
-  constructor(page: Page, private log: PlaywrightReportLogger) {
-    super(page, "https://example.com", "/login");
-  }
-
-  @step()
-  async doSomething() {
-    this.log.info("Doing something");
-  }
-}
-
-// Fixture
-const test = base.extend<Fixtures>({
-  loginPage: async ({ page, log }, use) => {
-    await use(new LoginPage(page, log));
-  },
-});
-```
-
-**Option C: Create a child logger in the fixture**
-
-```ts
-const test = base.extend<Fixtures>({
-  loginPage: async ({ page, log }, use) => {
-    const childLog = log.getNewChildLogger("LoginPage");
-    await use(new LoginPage(page, childLog));
-  },
-});
-```
-
-## Complete migration example
-
-### v1 (before)
-
-```ts
-// loginPage.page.ts
-import type { Page, TestInfo } from "@playwright/test";
-import { BasePage, GetByMethod, type PlaywrightReportLogger } from "pomwright";
-
-type Paths = "main" | "main.form" | "main.form.input@username" | "main.form.button@submit";
-
-export default class LoginPage extends BasePage<Paths> {
-  constructor(page: Page, testInfo: TestInfo, pwrl: PlaywrightReportLogger) {
-    super(page, testInfo, "https://example.com", "/login", "LoginPage", pwrl);
-  }
-
-  protected initLocatorSchemas() {
-    this.locators.addSchema("main", { locator: "main", locatorMethod: GetByMethod.locator });
-    this.locators.addSchema("main.form", { locator: "form.login", locatorMethod: GetByMethod.locator });
-    this.locators.addSchema("main.form.input@username", { label: "Username", locatorMethod: GetByMethod.label });
-    this.locators.addSchema("main.form.button@submit", {
-      role: "button", roleOptions: { name: "Submit" }, locatorMethod: GetByMethod.role,
-    });
-  }
-
-  async login(username: string) {
-    const input = await this.getNestedLocator("main.form.input@username");
-    await input.fill(username);
-    const btn = await this.getNestedLocator("main.form.button@submit");
-    await btn.click();
-  }
-}
-
-// fixture
-const test = base.extend<Fixtures>({
-  loginPage: async ({ page, log }, use, testInfo) => {
-    await use(new LoginPage(page, testInfo, log));
-  },
-});
-
-// test
-test("login", async ({ loginPage }) => {
-  await loginPage.page.goto(loginPage.fullUrl);
-  await loginPage.login("admin");
-});
-```
-
-### v2 (after)
-
-```ts
-// loginPage.locatorSchema.ts
-import type { LocatorRegistry } from "pomwright";
-
-export type Paths = "main" | "main.form" | "main.form.input@username" | "main.form.button@submit";
-
-export function defineLocators(registry: LocatorRegistry<Paths>) {
-  registry.add("main").locator("main");
-  registry.add("main.form").locator("form.login");
-  registry.add("main.form.input@username").getByLabel("Username");
-  registry.add("main.form.button@submit").getByRole("button", { name: "Submit" });
-}
-```
-
-```ts
-// loginPage.page.ts
-import type { Page } from "@playwright/test";
-import { PageObject, step } from "pomwright";
-import { defineLocators, type Paths } from "./loginPage.locatorSchema";
-
-export default class LoginPage extends PageObject<Paths> {
-  constructor(page: Page) {
-    super(page, "https://example.com", "/login");
-  }
-
-  protected defineLocators(): void {
-    defineLocators(this.locatorRegistry);
-  }
-
-  protected pageActionsToPerformAfterNavigation(): (() => Promise<void>)[] | null {
-    return null;
-  }
-
-  @step()
-  async login(username: string) {
-    await this.getNestedLocator("main.form.input@username").fill(username);
-    await this.getNestedLocator("main.form.button@submit").click();
-  }
-}
-```
-
-```ts
-// fixture
-const test = base.extend<Fixtures>({
-  loginPage: async ({ page }, use) => {
-    await use(new LoginPage(page));
-  },
-});
-```
-
-```ts
-// test
-test("login", async ({ loginPage }) => {
-  await loginPage.navigation.gotoThisPage();
-  await loginPage.login("admin");
-});
-```