pomwright 1.2.0 → 1.3.0

package/dist/index.js

@@ -18,8 +18,8 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // index.ts
-var POMWright_exports = {};
-__export(POMWright_exports, {
+var index_exports = {};
+__export(index_exports, {
   BaseApi: () => BaseApi,
   BasePage: () => BasePage,
   GetByMethod: () => GetByMethod,
@@ -27,7 +27,7 @@ __export(POMWright_exports, {
   PlaywrightReportLogger: () => PlaywrightReportLogger,
   test: () => test3
 });
-module.exports = __toCommonJS(POMWright_exports);
+module.exports = __toCommonJS(index_exports);
 
 // src/basePage.ts
 var import_test3 = require("@playwright/test");
@@ -427,6 +427,11 @@ var GetLocatorBase = class {
    * Throws an error if a schema already exists at that path.
    */
   addSchema(locatorSchemaPath, schemaDetails) {
+    if (locatorSchemaPath.length === 0 || locatorSchemaPath.startsWith(".") || locatorSchemaPath.endsWith(".") || locatorSchemaPath.includes("..")) {
+      throw new Error(
+        `[${this.pageObjectClass.pocName}] Invalid LocatorSchemaPath '${locatorSchemaPath}'. LocatorSchemaPath must not be empty, start or end with a '.', or contain consecutive '.'.`
+      );
+    }
     const newLocatorSchema = this.createLocatorSchema(schemaDetails, locatorSchemaPath);
     const existingSchemaFunc = this.safeGetLocatorSchema(locatorSchemaPath);
     if (existingSchemaFunc) {
@@ -807,7 +812,7 @@ var SessionStorage = class {
           const item = sessionStorage.getItem(key);
           try {
             storage[key] = item ? JSON.parse(item) : null;
-          } catch (e) {
+          } catch (_e) {
             storage[key] = item;
           }
         }
@@ -857,7 +862,7 @@ var SessionStorage = class {
       contextExists = await this.page.evaluate(() => {
         return typeof window !== "undefined" && window.sessionStorage !== void 0;
       });
-    } catch (e) {
+    } catch (_e) {
       contextExists = false;
     }
     if (contextExists) {
@@ -888,7 +893,7 @@ var SessionStorage = class {
       const allData = await this.readFromSessionStorage();
       if (keys && keys.length > 0) {
         for (const key of keys) {
-          if (Object.prototype.hasOwnProperty.call(allData, key)) {
+          if (Object.hasOwn(allData, key)) {
             result[key] = allData[key];
           }
         }
@@ -1000,7 +1005,7 @@ var BasePage = class {
    * Ensures a flexible approach to URL matching (string or regex-based).
    */
   constructFullUrl(baseUrl, urlPath) {
-    const escapeStringForRegExp = (str) => str.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&");
+    const escapeStringForRegExp = (str) => str.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
     if (typeof baseUrl === "string" && typeof urlPath === "string") {
       return `${baseUrl}${urlPath}`;
     }
@@ -1234,7 +1239,7 @@ ${args.join("\n\n")}`
         const parsedMessage = JSON.parse(log.message);
         messageContentType = "application/json";
         messageBody = JSON.stringify(parsedMessage, null, 2);
-      } catch (error) {
+      } catch (_error) {
         messageContentType = "text/plain";
         messageBody = log.message;
       }

package/dist/index.mjs

@@ -396,6 +396,11 @@ var GetLocatorBase = class {
    * Throws an error if a schema already exists at that path.
    */
   addSchema(locatorSchemaPath, schemaDetails) {
+    if (locatorSchemaPath.length === 0 || locatorSchemaPath.startsWith(".") || locatorSchemaPath.endsWith(".") || locatorSchemaPath.includes("..")) {
+      throw new Error(
+        `[${this.pageObjectClass.pocName}] Invalid LocatorSchemaPath '${locatorSchemaPath}'. LocatorSchemaPath must not be empty, start or end with a '.', or contain consecutive '.'.`
+      );
+    }
     const newLocatorSchema = this.createLocatorSchema(schemaDetails, locatorSchemaPath);
     const existingSchemaFunc = this.safeGetLocatorSchema(locatorSchemaPath);
     if (existingSchemaFunc) {
@@ -776,7 +781,7 @@ var SessionStorage = class {
           const item = sessionStorage.getItem(key);
           try {
             storage[key] = item ? JSON.parse(item) : null;
-          } catch (e) {
+          } catch (_e) {
             storage[key] = item;
           }
         }
@@ -826,7 +831,7 @@ var SessionStorage = class {
       contextExists = await this.page.evaluate(() => {
         return typeof window !== "undefined" && window.sessionStorage !== void 0;
       });
-    } catch (e) {
+    } catch (_e) {
       contextExists = false;
     }
     if (contextExists) {
@@ -857,7 +862,7 @@ var SessionStorage = class {
       const allData = await this.readFromSessionStorage();
       if (keys && keys.length > 0) {
         for (const key of keys) {
-          if (Object.prototype.hasOwnProperty.call(allData, key)) {
+          if (Object.hasOwn(allData, key)) {
             result[key] = allData[key];
           }
         }
@@ -969,7 +974,7 @@ var BasePage = class {
    * Ensures a flexible approach to URL matching (string or regex-based).
    */
   constructFullUrl(baseUrl, urlPath) {
-    const escapeStringForRegExp = (str) => str.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&");
+    const escapeStringForRegExp = (str) => str.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
     if (typeof baseUrl === "string" && typeof urlPath === "string") {
       return `${baseUrl}${urlPath}`;
     }
@@ -1203,7 +1208,7 @@ ${args.join("\n\n")}`
         const parsedMessage = JSON.parse(log.message);
         messageContentType = "application/json";
         messageBody = JSON.stringify(parsedMessage, null, 2);
-      } catch (error) {
+      } catch (_error) {
         messageContentType = "text/plain";
         messageBody = log.message;
       }

package/docs/BaseApi-explanation.md

@@ -0,0 +1,63 @@
+# BaseApi
+
+The `BaseApi` class offers a minimal foundation for writing API helpers in POMWright.  It wraps Playwright's `APIRequestContext` and integrates with the shared [`PlaywrightReportLogger`](./PlaywrightReportLogger-explanation.md).
+
+## Constructor
+
+```ts
+constructor(baseUrl: string, apiName: string, context: APIRequestContext, pwrl: PlaywrightReportLogger)
+```
+
+* `baseUrl` – root address used to build request URLs.
+* `apiName` – human‑readable identifier; also used as a logging prefix.
+* `context` – Playwright [`APIRequestContext`](https://playwright.dev/docs/api/class-apirequestcontext).
+* `pwrl` – logger instance supplied by the test fixtures.  A child logger is created for the API class.
+
+The class stores these values on the instance and exposes the `request` and `log` properties for use in subclasses.
+
+## Example
+
+```ts
+import type { APIRequestContext } from "@playwright/test";
+import { BaseApi, type PlaywrightReportLogger } from "pomwright";
+
+class MyApi extends BaseApi {
+  constructor(baseUrl: string, context: APIRequestContext, pwrl: PlaywrightReportLogger) {
+    super(baseUrl, MyApi.name, context, pwrl);
+  }
+
+  v1 = {
+    users: {
+      id: {
+        get: async (id: string, status: number = 200) => {
+          const response = await this.request.get(`/api/users/${id}`);
+          expect(response.status(), "should have status code: 200").toBe(status);
+          const body = await response.json();
+          return body;
+        },
+        //...etc.
+      }
+    },
+    products: {
+      //...etc.
+    }
+  }
+}
+```
+
+Then in a test you'd do:
+
+```ts
+test("some test", { tag: ["@api", "@user"] }, async ({ myApi }) => {
+  // Create user
+
+  const existingUser = await myApi.v1.users.id.get(userId); // 200 (default) user found
+  
+  // Delete user
+
+  const deletedUser = await myApi.v1.users.id.get(userId, 204); // 204 user not found successfully
+
+})
+```
+
+`BaseApi` does not dictate how requests are made; you are free to add domain‑specific methods using the provided `request` context and logger.

package/docs/BasePage-explanation.md

@@ -0,0 +1,96 @@
+# BasePage
+
+`BasePage` is the foundation for all Page Object Classes (POCs) in POMWright.  It provides common plumbing for Playwright pages, logging, locator management and session storage.
+
+## Generics
+
+```ts
+BasePage<LocatorSchemaPathType, Options = { urlOptions: { baseUrlType: string; urlPathType: string } }, LocatorSubstring>
+```
+
+* **LocatorSchemaPathType** – union of valid locator paths for the POC.
+* **Options** – optional configuration that allows the `baseUrl` or `urlPath` to be typed as a `RegExp` when dynamic values are required for mapping certain resource paths. See [intTest/page-object-models/testApp/with-options/base/baseWithOptions.page.ts](../intTest/page-object-models/testApp/with-options/base/baseWithOptions.page.ts)
+* **LocatorSubstring** – internal type used when working with sub paths; normally left undefined.
+
+## Constructor
+
+```ts
+constructor(
+  page: Page,
+  testInfo: TestInfo,
+  baseUrl: ExtractBaseUrlType<Options>,
+  urlPath: ExtractUrlPathType<Options>,
+  pocName: string,
+  pwrl: PlaywrightReportLogger
+)
+```
+
+The base class stores these values and derives `fullUrl`.  A child [`PlaywrightReportLogger`](./PlaywrightReportLogger-explanation.md) is created for the POC and a [`SessionStorage`](./sessionStorage-methods-explanation.md) helper is exposed as `sessionStorage`.
+
+## Required implementation
+
+Every POC extending `BasePage` must:
+
+1. Define a `LocatorSchemaPath` union describing available locators.
+2. Implement the `initLocatorSchemas()` method which adds schemas to the internal `GetLocatorBase` instance.
+
+```ts
+// login.page.ts
+import type { Page, TestInfo } from "@playwright/test";
+import { BasePage, type PlaywrightReportLogger } from "pomwright";
+import { test } from "@fixtures/all.fixtures";
+import { type LocatorSchemaPath, initLocatorSchemas } from "./login.locatorSchema";
+
+export default class Login extends BasePage<LocatorSchemaPath> {
+  constructor(page: Page, testInfo: TestInfo, pwrl: PlaywrightReportLogger) {
+    super(page, testInfo, "https://example.com", "/login", Login.name, pwrl);
+  }
+
+  protected initLocatorSchemas() {
+    initLocatorSchemas(this.locators);
+  }
+
+  public async login(user: string, pass: string) {
+    await test.step(`${this.pocName}: Fill login form and login`, async () => {
+
+      await test.step(`${this.pocName}: Fill username field`, async () => {
+        const locator = await this.getNestedLocator("main.section@login.form.textbox@username");
+        await locator.fill(user);
+        await locator.blur();
+      });
+
+      await test.step(`${this.pocName}: Fill password field`, async () => {
+        const locator = await this.getNestedLocator("main.section@login.form.textbox@password");
+        await locator.fill(pass);
+        await locator.blur();
+      });
+
+      await test.step(`${this.pocName}: Click login button`, async () => {
+        const locator = await this.getNestedLocator("main.section@login.button@login");
+        await locator.click();
+      });
+
+      /** 
+       * We probably don't want to await navigation here, instead we do it in the test, 
+       * using the POC representing the page we are navigated to (e.g. /profile) 
+       */
+    });
+  }
+}
+```
+
+## Helper methods
+
+`BasePage` exposes a small API built around `LocatorSchema` definitions:
+
+* `getLocatorSchema(path)` – returns a chainable object; see [locator methods](./get-locator-methods-explanation.md).
+* `getLocator(path)` – wrapper method for `getLocatorSchema(path).getLocator();` - resolves the locator for the final segment of a path, e.g. the Locator created from the LocatorSchema the full LocatorSchemaPath references.
+* `getNestedLocator(path, indices?)` – wrapper method for `getLocatorSchema(path).getNestedLocator();` - automatically chains locators along the path and optionally selects nth occurrences.
+
+All locators are strongly typed, giving compile‑time suggestions and preventing typos in `LocatorSchemaPath` strings.
+
+## Recommendation
+
+Instead of extending each of your POC's with BasePage from POMWright, opt instead to create an abstract BasePage class for your domain and have it extend BasePage from POMWright. Then have each of your POC's extend your abstract POC instead. This allows us to easily sentralize common helper methods, LocatorSchema, etc. and reuse it across all our POC's for the given domain.
+
+For examples see [intTest/page-object-models/testApp](../intTest/page-object-models/testApp)

package/docs/LocatorSchema-explanation.md

@@ -0,0 +1,271 @@
+# LocatorSchema
+
+A `LocatorSchema` describes how to find an element in the DOM. Instead of storing Playwright `Locator` objects directly, POMWright keeps these schema definitions and resolves them only when a test requests the locator. The same schema can be reused across multiple page objects and test files without risking stale references.
+
+Every schema must set `locatorMethod` to one of the [`GetByMethod`](../src/helpers/locatorSchema.interface.ts) enum values. The matching selector fields listed below determine which Playwright API call is executed under the hood. You can provide more than one selector field, but the method chosen by `locatorMethod` is the one that will be used when the locator is created.
+
+When you register a schema with `GetLocatorBase.addSchema(path, schemaDetails)` the `locatorSchemaPath` is stored automatically and becomes part of the structured logs produced by POMWright.
+
+## Selector strategies
+
+> Note: You can define both "role" and "locator" on the same LocatorSchema, but which one is used is dictated by "locatorMethod". Too keep things clean I recommend only defining the actual type of Playwright Locator you'll be using.
+
+Each selector strategy maps directly to a Playwright locator helper. The snippets below show the POMWright configuration alongside the equivalent raw Playwright call.
+
+### `role` and `roleOptions`
+
+Use [ARIA roles](https://playwright.dev/docs/api/class-page#page-get-by-role) as your primary selector. The optional `roleOptions` map to the options object accepted by `page.getByRole()`.
+
+```ts
+locators.addSchema("content.button@edit", {
+  role: "button",
+  roleOptions: { name: "Edit" },
+  locatorMethod: GetByMethod.role
+});
+```
+
+Playwright equivalent:
+
+```ts
+page.getByRole("button", { name: "Edit" });
+```
+
+### `text` and `textOptions`
+
+Match visible text using the same semantics as [`page.getByText()`](https://playwright.dev/docs/api/class-page#page-get-by-text).
+
+```ts
+locators.addSchema("content.link.help", {
+  text: "Need help?",
+  textOptions: { exact: true },
+  locatorMethod: GetByMethod.text
+});
+```
+
+Playwright equivalent:
+
+```ts
+page.getByText("Need help?", { exact: true });
+```
+
+### `label` and `labelOptions`
+
+Reference form controls by their accessible label. `labelOptions` accepts the same arguments as [`page.getByLabel()`](https://playwright.dev/docs/api/class-page#page-get-by-label).
+
+```ts
+locators.addSchema("content.form.password", {
+  label: "Password",
+  locatorMethod: GetByMethod.label
+});
+```
+
+Playwright equivalent:
+
+```ts
+page.getByLabel("Password");
+```
+
+### `placeholder` and `placeholderOptions`
+
+Target elements by placeholder text via [`page.getByPlaceholder()`](https://playwright.dev/docs/api/class-page#page-get-by-placeholder).
+
+```ts
+locators.addSchema("content.form.search", {
+  placeholder: "Search",
+  placeholderOptions: { exact: true },
+  locatorMethod: GetByMethod.placeholder
+});
+```
+
+Playwright equivalent:
+
+```ts
+page.getByPlaceholder("Search", { exact: true });
+```
+
+### `altText` and `altTextOptions`
+
+Resolve images and other elements with alternative text via [`page.getByAltText()`](https://playwright.dev/docs/api/class-page#page-get-by-alt-text).
+
+```ts
+locators.addSchema("content.hero.image", {
+  altText: "Company logo",
+  locatorMethod: GetByMethod.altText
+});
+```
+
+Playwright equivalent:
+
+```ts
+page.getByAltText("Company logo");
+```
+
+### `title` and `titleOptions`
+
+Tap into the [`title` attribute](https://playwright.dev/docs/api/class-page#page-get-by-title) of an element.
+
+```ts
+locators.addSchema("content.tooltip.info", {
+  title: "More information",
+  locatorMethod: GetByMethod.title
+});
+```
+
+Playwright equivalent:
+
+```ts
+page.getByTitle("More information");
+```
+
+### `locator` and `locatorOptions`
+
+Fallback to raw selectors or locator chaining with [`page.locator()`](https://playwright.dev/docs/api/class-page#page-locator). `locatorOptions` is passed straight through to the Playwright call.
+
+```ts
+locators.addSchema("content.main", {
+  locator: "main",
+  locatorOptions: { hasText: "Profile" },
+  locatorMethod: GetByMethod.locator
+});
+```
+
+Playwright equivalent:
+
+```ts
+page.locator("main", { hasText: "Profile" });
+```
+
+### `frameLocator`
+
+Create [`FrameLocator`](https://playwright.dev/docs/api/class-page#page-frame-locator) instances when your DOM interaction starts inside an iframe.
+
+```ts
+locators.addSchema("iframe.login", {
+  frameLocator: "#auth-frame",
+  locatorMethod: GetByMethod.frameLocator
+});
+```
+
+Playwright equivalent:
+
+```ts
+page.frameLocator("#auth-frame");
+```
+
+### `testId`
+
+Call [`page.getByTestId()`](https://playwright.dev/docs/api/class-page#page-get-by-test-id) by setting the `testId` field.
+
+```ts
+locators.addSchema("content.button.reset", {
+  testId: "reset-btn",
+  locatorMethod: GetByMethod.testId
+});
+```
+
+Playwright equivalent:
+
+```ts
+page.getByTestId("reset-btn");
+```
+
+### `dataCy`
+
+`dataCy` is a POMWright convenience for the legacy `data-cy` attribute used in Cypress-based projects. Under the hood it still calls `page.locator()` with the [`data-cy=` selector engine](https://playwright.dev/docs/extensibility#custom-selector-engines) registered by `BasePage`.
+
+```ts
+locators.addSchema("content.card.actions", {
+  dataCy: "card-actions",
+  locatorMethod: GetByMethod.dataCy
+});
+```
+
+Playwright equivalent:
+
+```ts
+page.locator("data-cy=card-actions");
+```
+
+If you prefer to control the selector string yourself you can pass the full expression (`"data-cy=card-actions"`) and it will be used verbatim.
+
+### `id`
+
+`id` is the second POMWright-specific helper. Provide either the raw id string or a `RegExp`. Strings are normalised to CSS id selectors, so `"details"`, `"#details"`, and `"id=details"` all resolve to the same element. A regular expression matches the start of the `id` attribute, allowing you to capture generated identifiers.
+
+```ts
+locators.addSchema("content.region.details", {
+  id: "profile-details",
+  locatorMethod: GetByMethod.id
+});
+
+locators.addSchema("content.region.dynamic", {
+  id: /^region-/,
+  locatorMethod: GetByMethod.id
+});
+```
+
+Playwright equivalent:
+
+```ts
+page.locator("#profile-details");
+page.locator('*[id^="region-"]');
+```
+
+### `filter`
+
+Any schema can define a `filter` object with the same shape as [`locator.filter()`](https://playwright.dev/docs/api/class-locator#locator-filter). Filters are applied immediately after the initial Playwright locator is created.
+
+```ts
+locators.addSchema("content.list.item", {
+  role: "listitem",
+  locatorMethod: GetByMethod.role,
+  filter: { hasText: /Primary Colors/i }
+});
+```
+
+Playwright equivalent:
+
+```ts
+page.getByRole("listitem").filter({ hasText: /Primary Colors/i });
+```
+
+## Putting it together
+
+Schemas are typically registered inside `initLocatorSchemas()` of a `BasePage` subclass. The example below demonstrates reusable fragments and multiple selector strategies working together.
+
+```ts
+import { GetByMethod, type GetLocatorBase, type LocatorSchemaWithoutPath } from "pomwright";
+type LocatorSchemaPath =
+  | "main"
+  | "main.button"
+  | "main.button@continue"
+  | "main.button@back";
+
+export function initLocatorSchemas(locators: GetLocatorBase<LocatorSchemaPath>) {
+  locators.addSchema("main", {
+    locator: "main",
+    locatorMethod: GetByMethod.locator
+  });
+
+  const button: LocatorSchemaWithoutPath = {
+    role: "button",
+    locatorMethod: GetByMethod.role
+  };
+
+  locators.addSchema("main.button", {
+    ...button
+    });
+
+  locators.addSchema("main.button@continue", {
+    ...button,
+    roleOptions: { name: "Continue" }
+  });
+
+  locators.addSchema("main.button@back", {
+    ...button,
+    roleOptions: { name: "Back" }
+  });
+}
+```
+
+Once registered, the schemas can be consumed through the BasePage helpers documented in [`docs/get-locator-methods-explanation.md`](./get-locator-methods-explanation.md).