pomwright 1.4.0 → 1.5.0

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

@@ -0,0 +1,159 @@
+# 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

@@ -0,0 +1,238 @@
+# 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`.