pomwright 1.5.1 → 2.0.0

package/docs/v1/sessionStorage-methods-explanation.md

@@ -1,38 +0,0 @@
-# SessionStorage helper
-
-Every `BasePage` exposes a `sessionStorage` property that wraps common operations on `window.sessionStorage`.  The helper records each action as a Playwright `test.step` for better reporting.
-
-## set(states, reload)
-
-Writes key/value pairs to session storage.  Passing `true` for `reload` refreshes the page to apply the new state immediately.
-
-```ts
-await page.sessionStorage.set({ token: "abc", theme: "dark" }, true);
-```
-
-## setOnNextNavigation(states)
-
-Queues values that are written just before the next navigation event.  Multiple calls merge their state.
-
-```ts
-await login.sessionStorage.setOnNextNavigation({ token: "abc" });
-await login.page.goto(login.fullUrl); // queued values are applied before navigation completes
-```
-
-## get(keys?)
-
-Retrieves data from session storage.  When `keys` are provided only those values are returned; otherwise all stored keys are returned.
-
-```ts
-const { theme } = await page.sessionStorage.get(["theme"]);
-```
-
-## clear()
-
-Removes everything from session storage:
-
-```ts
-await page.sessionStorage.clear();
-```
-
-These helpers are especially useful when tests need to prime application state without going through the UI.

package/docs/v1/tips-folder-structure.md

@@ -1,38 +0,0 @@
-# Folder Structure
-
-How you structure your project is ultimately up to you and what makes sense often differ between projects, but I've found the following structure works quite well in most cases.
-
-```text
-./playwright
-  /fixtures
-    /app1
-      app1.fixtures.ts
-    /app2
-    /automatic
-    /custom-expects
-    all.fixtures.ts
-  /pom
-    /app1
-      /common
-        /basePage
-          app1.basePage.ts
-        /helpers
-      /pages
-        homepage.locatorSchema.ts
-        homepage.page.ts
-        /profile
-          profile.locatorSchema.ts
-          profile.page.ts
-    /app2
-  /tests
-    /app1
-      /byFeature
-        login.spec.ts
-      /byResourcePath
-        homepage.spec.ts
-        /profile
-          profile.spec.ts
-      /e2e
-    /app2
-    /e2e
-```

package/docs/v1-to-v2-migration/bridge-migration-guide.md

@@ -1,159 +0,0 @@
-# Bridge Migration Guide (BasePage ➜ BasePageV1toV2 ➜ PageObject)
-
-This guide is for teams that want a **two-step migration**:
-
-1. Move from `BasePage` (v1) to `BasePageV1toV2` (bridge).
-2. Then move from `BasePageV1toV2` to `PageObject` (v2).
-
-The bridge preserves v1 locator schema ingestion while exposing v2 registries, allowing gradual conversion.
-
-> `BasePageV1toV2` is deprecated and will be removed in 2.0.0. Use it only as a temporary bridge.
-
----
-
-## Step 1: Migrate `BasePage` to `BasePageV1toV2`
-
-### v1 BasePage
-
-```ts
-class LoginPage extends BasePage<Paths> {
-  constructor(page: Page, testInfo: TestInfo, log: PlaywrightReportLogger) {
-    super(page, testInfo, "https://example.com", "/login", "LoginPage", log);
-  }
-
-  protected initLocatorSchemas() {
-    this.locators.addSchema({
-      locatorSchemaPath: "main.button@login",
-      locatorMethod: GetByMethod.role,
-      role: "button",
-      roleOptions: { name: "Login" },
-    });
-  }
-}
-```
-
-### Bridge: BasePageV1toV2
-
-```ts
-class LoginPage extends BasePageV1toV2<Paths> {
-  constructor(page: Page, testInfo: TestInfo, log: PlaywrightReportLogger) {
-    super(page, testInfo, "https://example.com", "/login", "LoginPage", log);
-  }
-
-  protected defineLocators(): void {
-    // Start migrating here with v2 add(...) calls.
-    this.add("main.button@login").getByRole("button", { name: "Login" });
-  }
-
-  protected initLocatorSchemas(): void {
-    // Keep v1 schemas temporarily until you migrate them all.
-    this.locators.addSchema({
-      locatorSchemaPath: "main.form@login",
-      locatorMethod: GetByMethod.role,
-      role: "form",
-      roleOptions: { name: "Login" },
-    });
-  }
-}
-```
-
-Key points:
-
-- `BasePageV1toV2` still requires `testInfo` and `PlaywrightReportLogger`.
-- It exposes **both** v1 schema ingestion (`initLocatorSchemas`) and v2 accessors (`add`, `getLocator`, `getNestedLocator`, `getLocatorSchema`).
-- You can migrate locators incrementally by moving schemas from `initLocatorSchemas` to `defineLocators`.
-
----
-
-## Step 2: Gradually migrate locators to v2 DSL
-
-### Convert one schema at a time
-
-```ts
-// v1 schema
-this.locators.addSchema({
-  locatorSchemaPath: "main.form@login.input@username",
-  locatorMethod: GetByMethod.label,
-  label: "Username",
-});
-
-// v2 DSL (preferred)
-this.add("main.form@login.input@username").getByLabel("Username");
-```
-
-### Replace v1 mutations
-
-```ts
-// v1
-await page
-  .getLocatorSchema("main.form@login.input@username")
-  .addFilter("main.form@login", { hasText: "Login" })
-  .getNestedLocator();
-
-// v2
-page
-  .getLocatorSchema("main.form@login.input@username")
-  .filter("main.form@login", { hasText: "Login" })
-  .getNestedLocator();
-```
-
----
-
-## Step 3: Remove v1 schema ingestion entirely
-
-When all schemas are converted to `defineLocators`, delete `initLocatorSchemas` and switch to `PageObject`.
-
-```ts
-class LoginPage extends PageObject<Paths> {
-  constructor(page: Page) {
-    super(page, "https://example.com", "/login", { label: "LoginPage" });
-  }
-
-  protected defineLocators(): void {
-    this.add("main.form@login.input@username").getByLabel("Username");
-  }
-
-  protected pageActionsToPerformAfterNavigation() {
-    return [];
-  }
-}
-```
-
----
-
-## Step 4: Update API usage
-
-After switching to `PageObject`, update the remaining call sites:
-
-- `getLocator` / `getNestedLocator` are synchronous and the latter no longer accept index maps.
-- `SessionStorage` signatures changed (`set(states, { reload, waitForContext })`).
-- PageObject does not implement `testInfo` and `PlaywrightReportLogger` while v1 `BasePage` does, if you want them in your POCs you'll need to add them.
-
----
-
-## Bridge checklist
-
-- [ ] Replace extend `BasePage` with extend `BasePageV1toV2`.
-- [ ] Add `defineLocators()` and start migrating schemas.
-- [ ] Migrate all locator schemas to `defineLocators`.
-  - [ ] Update FrameLocators (see [v1-to-v2-comparison.md](docs/v1-to-v2-migration/v1-to-v2-comparison.md))
-  - [ ] Update getById regex patterns (see [v1-to-v2-comparison.md](docs/v1-to-v2-migration/v1-to-v2-comparison.md))
-- [ ] Replace v1 `getLocatorSchema(path).addFilter(...)` with v2 `getLocatorSchema(path).filter(...)`.
-- [ ] Replace v1 getNestedLocator index maps with v2 `getLocatorSchema(path).nth(...)`.
-- [ ] Update v1 `getLocatorSchema(path).update(...)` with v2 `getLocatorSchema(path)`... `.update(...)` / `.nth(...)` / `.filter(...)` etc.
-- [ ] Replace extend `BasePageV1toV2` with extend `PageObject`. See [direct-migration-guide.md](docs/v1-to-v2-migration/direct-migration-guide.md)
-- [ ] Update logging and session storage usage.
-
----
-
-## When to avoid the bridge
-
-Skip `BasePageV1toV2` if:
-
-- You can migrate all locators and method calls quickly.
-- You want to adopt v2 URL typing and navigation immediately.
-- You do not need the old `GetLocatorBase` or schema objects.
-
----
-
-For a full feature comparison and method mapping, see [v1-to-v2-comparison.md](docs/v1-to-v2-migration/v1-to-v2-comparison.md).

package/docs/v1-to-v2-migration/direct-migration-guide.md

@@ -1,238 +0,0 @@
-# Direct v1 ➜ v2 Migration Guide
-
-This guide shows how to migrate directly from `BasePage` (v1) to `PageObject` (v2). It focuses on the structural changes, locator conversion, and API differences you must address.
-
-> v1 is deprecated and will be removed in 2.0.0. v1.5.0 is the final v1 release.
-
----
-
-## 1) Inventory your v1 usage
-
-Before changing code, list where the following appear:
-
-- `BasePage` subclasses.
-- `initLocatorSchemas` definitions.
-- `LocatorSchema` objects and `GetByMethod` usage.
-- `getLocatorSchema(...).update(...)` and `addFilter(...)` chains.
-- `getLocator` / `getNestedLocator` wrappers.
-- `SessionStorage` usage (old signatures).
-- `PlaywrightReportLogger` usage in constructors.
-- Any `data-cy` selectors or custom selector engines.
-
----
-
-## 2) Convert `BasePage` to `PageObject`
-
-### v1
-
-```ts
-class LoginPage extends BasePage<Paths> {
-  constructor(page: Page, testInfo: TestInfo, log: PlaywrightReportLogger) {
-    super(page, testInfo, "https://example.com", "/login", "LoginPage", log);
-  }
-
-  protected initLocatorSchemas() {
-    this.locators.addSchema({
-      locatorSchemaPath: "main.button@login",
-      locatorMethod: GetByMethod.role,
-      role: "button",
-      roleOptions: { name: "Login" },
-    });
-  }
-}
-```
-
-### v2
-
-```ts
-class LoginPage extends PageObject<Paths> {
-  constructor(page: Page) {
-    super(page, "https://example.com", "/login", { label: "LoginPage" });
-  }
-
-  protected defineLocators(): void {
-    this.add("main.button@login").getByRole("button", { name: "Login" });
-  }
-
-  protected pageActionsToPerformAfterNavigation() {
-    return [];
-  }
-}
-```
-
-Key changes:
-
-- Remove `testInfo`, `PlaywrightReportLogger`, and `pocName` constructor args.
-- Use `defineLocators()` instead of `initLocatorSchemas()`.
-- Provide `pageActionsToPerformAfterNavigation()`.
-
----
-
-## 3) Translate v1 locator schemas to v2 `add(...)`
-
-### v1 locator schema
-
-```ts
-this.locators.addSchema({
-  locatorSchemaPath: "main.form@login.input@username",
-  locatorMethod: GetByMethod.label,
-  label: "Username",
-});
-```
-
-### v2 registry DSL
-
-```ts
-this.add("main.form@login.input@username").getByLabel("Username");
-```
-
-Mapping guide:
-
-| v1 `locatorMethod` | v2 method |
-| --- | --- |
-| `role` | `getByRole(...)` |
-| `text` | `getByText(...)` |
-| `label` | `getByLabel(...)` |
-| `placeholder` | `getByPlaceholder(...)` |
-| `altText` | `getByAltText(...)` |
-| `title` | `getByTitle(...)` |
-| `locator` | `locator(...)` |
-| `frameLocator` | `frameLocator(...)` |
-| `testId` | `getByTestId(...)` |
-| `id` (custom) | `getById(...)` (custom) |
-| `dataCy` (custom) | `locator('[data-cy="..."]')` |
-
----
-
-## 4) Replace `getLocator` / `getNestedLocator`
-
-In v1 these were async wrappers and accepted index maps. In v2 they are synchronous and do not accept index maps.
-
-### v1
-
-```ts
-const submit = await poc.getNestedLocator("main.form.button@submit", {
-  "main.form": 0,
-});
-```
-
-### v2
-
-```ts
-const submit = poc
-  .getLocatorSchema("main.form.button@submit")
-  .nth("main.form", 0)
-  .getNestedLocator();
-```
-
----
-
-## 5) Replace v1 `getLocatorSchema().update()` and `addFilter()`
-
-### v1
-
-```ts
-const submit = await poc
-  .getLocatorSchema("main.form.button@submit")
-  .update("main.form.button@submit", { roleOptions: { name: "Sign in" } })
-  .addFilter("main.form.button@submit", { hasText: /Sign in/i })
-  .getNestedLocator();
-```
-
-### v2
-
-```ts
-const submit = poc
-  .getLocatorSchema("main.form.button@submit")
-  .update("main.form.button@submit")
-  .getByRole({ name: "Sign in" })
-  .filter("main.form.button@submit", { hasText: /Sign in/i })
-  .getNestedLocator();
-```
-
----
-
-## 6) Update SessionStorage usage
-
-### v1
-
-```ts
-await poc.sessionStorage.set({ token: "abc" }, true);
-const data = await poc.sessionStorage.get(["token"]);
-await poc.sessionStorage.clear();
-```
-
-### v2
-
-```ts
-await poc.sessionStorage.set({ token: "abc" }, { reload: true });
-const data = await poc.sessionStorage.get(["token"], { waitForContext: true });
-await poc.sessionStorage.clear({ waitForContext: true });
-```
-
----
-
-## 7) Replace BasePage logging
-
-In v1, `BasePage` receives `PlaywrightReportLogger` and keeps it internally. In v2, logging is provided by the `test` fixture.
-
-### v2 fixture
-
-```ts
-import { test } from "pomwright";
-
-test("login flow", async ({ page, log }) => {
-  log.info("starting login");
-});
-```
-
-If you want logging inside POMs, pass a child logger explicitly.
-
----
-
-## 8) Update navigation flows
-
-v2 adds a navigation helper to `PageObject` and expects a `pageActionsToPerformAfterNavigation()` method.
-
-```ts
-protected pageActionsToPerformAfterNavigation() {
-  return [
-    async () => {
-      await this.getNestedLocator("main.form@login").waitFor({ state: "visible" });
-    },
-  ];
-}
-
-await loginPage.navigation.gotoThisPage();
-await loginPage.navigation.expectAnotherPage();
-```
-
----
-
-## 9) Remove v1-only APIs
-
-- `BaseApi` is deprecated and not part of v2. Use your own API base class.
-- `GetBy` and `LocatorSchema` objects are replaced by the registry DSL.
-- `data-cy` selector engine is removed; use `locator('[data-cy="..."]')` or register your own selector engine in Playwright.
-
----
-
-## 10) Validate after migration
-
-- Run tests.
-- Check all POMs compile with strict types.
-- Confirm registry paths match the new dot-delimited rules (no whitespace).
-
----
-
-## Summary checklist
-
-- [ ] Replace `BasePage` with `PageObject`.
-- [ ] Move `initLocatorSchemas` → `defineLocators`.
-- [ ] Convert `LocatorSchema` objects to `add(...).getBy...` calls.
-- [ ] Replace `addFilter` and index maps with `filter` + `nth`.
-- [ ] Update `SessionStorage` signatures.
-- [ ] Remove `data-cy` and custom selector engine assumptions.
-- [ ] Adopt the v2 `test` fixture for logging or implement it directly, see docs/v2/logging.md.
-
-For the bridge option, see `bridge-migration-guide.md`.