pomwright 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # pomwright
 
+## 1.4.0
+
+### Minor Changes
+
+- [#36](https://github.com/DyHex/POMWright/pull/36) [`e307d0e`](https://github.com/DyHex/POMWright/commit/e307d0e871bce4b69f12fa17fa673af3dad8f874) Thanks [@DyHex](https://github.com/DyHex)! - # v1.4.0
+
+  ## Removed
+
+  - Dropped deprecated locator schema helpers (legacy numeric indexing and update/updates overloads). Use sub-path keyed indices and `update(subPath, updates)` instead.
+
+  ## Changed
+
+  - Simplified nested locator debug logging to count-only checks to avoid CSP-restricted pages failing when `evaluateAll` is blocked.
+
+## 1.3.0
+
+### Minor Changes
+
+- [#33](https://github.com/DyHex/POMWright/pull/33) [`ca192bf`](https://github.com/DyHex/POMWright/commit/ca192bf587725a0eeba623e074d2e2e8347a5766) Thanks [@DyHex](https://github.com/DyHex)! - # Highlights
+
+  Updated the README to surface the expanded documentation set, making it easier to discover the new onboarding and reference guides from the project landing page.
+
+  ## Documentation
+
+  ### Onboarding & Patterns
+
+  - Added a comprehensive “Using POMWright” tutorial that walks through building a page object, defining locator schemas, moving definitions into shared files, wiring custom fixtures, and extracting common logic into abstract base classes for reuse across domains.
+
+  ### Reference Guides
+
+  - Documented the BasePage API, covering its generics, constructor contract, required overrides, helper methods, and recommendations for layering domain-specific base classes.
+  - Explained LocatorSchemaPath rules, duplication safeguards, readability conventions (including @ suffixes), and how sub-paths power IntelliSense and targeted updates.
+  - Expanded the LocatorSchema reference with Playwright parity for every selector strategy, POMWright-specific helpers like dataCy and id, the new filter property, and a reusable schema example.
+  - Clarified how to use getLocator, getNestedLocator, and getLocatorSchema chains, including update/filter patterns, index migration guidance, and reuse techniques.
+  - Added focused primers for the BaseApi helper, the shared PlaywrightReportLogger, and the sessionStorage wrapper so teams can integrate API utilities, logging, and state management consistently.
+  - Shared a recommended folder layout for fixtures, page objects, and tests to help teams standardise project structure as they adopt the framework.
+
+  ## Other improvements
+
+  - Fix: Intended LocatorSchemaPath string format now fully enforced.
+  - Add new tests, updated and fixed some existing tests
+  - CI/CD improvements
+
 ## 1.2.0
 
 ### Minor Changes

package/README.md

@@ -1,514 +1,58 @@
----
-"pomwright": minor
----
-
 # POMWright
 
-![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/DyHex/POMWright/main.yaml?label=CI%20on%20main) [![NPM Version](https://img.shields.io/npm/v/pomwright)](https://www.npmjs.com/package/pomwright) ![NPM Downloads](https://img.shields.io/npm/dt/pomwright) ![GitHub License](https://img.shields.io/github/license/DyHex/POMWright) [![NPM dev or peer Dependency Version](https://img.shields.io/npm/dependency-version/pomwright/peer/%40playwright%2Ftest)](https://www.npmjs.com/package/playwright) [![Static Badge](https://img.shields.io/badge/created%40-ICE-ffcd00)](https://www.ice.no/)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/DyHex/POMWright/main.yaml?label=CI%20on%20main)
+[![NPM Version](https://img.shields.io/npm/v/pomwright)](https://www.npmjs.com/package/pomwright)
+![NPM Downloads](https://img.shields.io/npm/dt/pomwright)
+![GitHub License](https://img.shields.io/github/license/DyHex/POMWright)
+[![NPM dev or peer Dependency Version](https://img.shields.io/npm/dependency-version/pomwright/peer/%40playwright%2Ftest)](https://www.npmjs.com/package/playwright)
+[![Static Badge](https://img.shields.io/badge/created%40-ICE-ffcd00)](https://www.ice.no/)
 
-POMWright is a TypeScript-based framework that implements the Page Object Model Design Pattern, designed specifically to augment Playwright's testing capabilities.
+POMWright is a lightweight TypeScript framework that layers the Page Object Model on top of Playwright.  It keeps locators, page objects, and fixtures organised so that UI tests stay readable and maintainable.
 
 POMWright provides a way of abstracting the implementation details of a web page and encapsulating them into a reusable page object. This approach makes the tests easier to read, write, and maintain, and helps reduce duplicated code by breaking down the code into smaller, reusable components, making the code more maintainable and organized.
 
-## Features
-
-### Easy Creation of Page Object Classes
-
-Simply extend a class with `BasePage` to create a Page Object Class (POC).
-
-### Support for Multiple Domains/BaseURLs
-
-Define different base URLs by extending an abstract class with `BasePage` per domain and have your POCs for each domain extend the abstract classes.
-
-### Custom Playwright Fixture Integration
-
-Seamlessly integrate custom Playwright Fixtures with your POMWright POCs.
-
-### LocatorSchema Interface
-
-Define comprehensive locators for each POC and share common locators between them.
-
-### Advanced Locator Management
+## Key capabilities
 
-Efficiently manage and chain locators through `LocatorSchemaPath`s.
+- Quickly build maintainable Page Object Classes.
+- Define any Playwright Locator through type-safe LocatorSchemas.
+- Automatic chaining of locators with dot-delimited paths that map directly to Playwright locator methods.
+- Auto-completion of LocatorSchemaPaths and sub-paths.
+- Adjust locators on the fly without mutating the original definitions.
+- Attach structured logs directly to the Playwright HTML report.
+- Manage `sessionStorage` for browser setup and state hand‑off.
+- Multiple Domains/BaseURLs
+- Validate elements position in DOM through chaining
 
-### Dynamic Locator Schema Updates
+## Why POMWright?
 
-Modify single or multiple locators within a chained locator dynamically during tests using the new `.update()` and `.addFilter()` methods.
-
-### Deep Copy of LocatorSchemas
-
-Ensure that original `LocatorSchemas` remain immutable and reusable across tests.
-
-### Custom HTML Logger
-
-Gain insights with detailed logs for nested locators, integrated with Playwright's HTML report. Or use the Log fixture throughout your own POCs and tests to easily attach them to the HTML report based on log levels.
-
-### SessionStorage Handling
-
-Enhance your tests with advanced `sessionStorage` handling capabilities.
-
-### Enhanced Locator Filtering
-
-- **New `filter` Property**: Apply filters across various locator types beyond just the `locator` method.
-- **New `.addFilter()` Method**: Dynamically add filters to any part of the locator chain.
+- **Stronger reliability** – centralised locator definitions reduce brittle inline selectors and make refactors visible at compile time.
+- **Faster authoring** – strongly typed schema paths provide instant auto-complete, even for deeply nested segments and reusable fragments.
+- **Easier maintenance** – shared helper patterns keep page objects, fixtures, and API clients aligned so teams can extend coverage without duplicating boilerplate.
+- **Incremental adoption** – each helper sits on top of Playwright primitives, making it straightforward to migrate existing tests component by component.
 
 ## Installation
 
-Ensure you have Node.js installed, then run:
-
-```bash
-npm install pomwright --save-dev
-```
-
-or
-
-```bash
-pnpm i -D pomwright
-```
-
-## Playwright Example Project
-
-Explore POMWright in action by diving into the example project located in the "example" folder. Follow these steps to get started:
-
-### Install
-
-Navigate to the "example" folder and install the necessary dependencies:
-
-```bash
-pnpm install
-```
-
-### Playwright Browsers
-
-Install or update Playwright browsers:
-
-```bash
-pnpm playwright install --with-deps
-```
-
-### Run Tests
-
-Execute tests across Chromium, Firefox, and WebKit:
+Install POMWright alongside Playwright:
 
 ```bash
-pnpm playwright test
+pnpm add -D pomwright
+# or
+npm install --save-dev pomwright
 ```
 
-### Parallelism
-
-Control parallel test execution. By default, up to 4 tests run in parallel. Modify this setting as needed:
-
-```bash
-pnpm playwright test --workers 2  # Set the number of parallel workers
-```
-
-### Reports
-
-After the tests complete, a Playwright HTML report is available in `./example/playwright-report`. Open the `index.html` file in your browser to view the results.
-
-## Usage
-
-Dive into using POMWright with these examples:
-
-### Create a Page Object Class (POC)
-
-```typescript
-import { Page, TestInfo } from "@playwright/test";
-import { BasePage, PlaywrightReportLogger, GetByMethod } from "pomwright";
-
-type LocatorSchemaPath = 
-  | "content"
-  | "content.heading"
-  | "content.region.details"
-  | "content.region.details.button.edit";
-
-export default class Profile extends BasePage<LocatorSchemaPath> {
-  constructor(page: Page, testInfo: TestInfo, pwrl: PlaywrightReportLogger) {
-    super(page, testInfo, "https://someDomain.com", "/profile", Profile.name, pwrl);
-  }
-
-  protected initLocatorSchemas() {
-    this.locators.addSchema("content", {
-      locator: ".main-content",
-      locatorMethod: GetByMethod.locator
-    });
-
-    this.locators.addSchema("content.heading", {
-      role: "heading",
-      roleOptions: {
-        name: "Your Profile"
-      },
-      locatorMethod: GetByMethod.role
-    });
-
-    this.locators.addSchema("content.region.details", {
-      role: "region",
-      roleOptions: {
-        name: "Profile Details"
-      },
-      locatorMethod: GetByMethod.role
-    });
-
-    this.locators.addSchema("content.region.details.button.edit", {
-      role: "button",
-      roleOptions: {
-        name: "Edit"
-      },
-      locatorMethod: GetByMethod.role
-    });
-  }
-
-  // add your helper methods here...
-}
-```
-
-### Creating a Custom Playwright Fixture
-
-```typescript
-import { test as base } from "pomwright";
-import Profile from "...";
-
-type fixtures = {
-  profile: Profile;
-}
-
-export const test = base.extend<fixtures>({
-  profile: async ({ page, log }, use, testInfo) => {
-    const profile = new Profile(page, testInfo, log);
-    await use(profile);
-  }
-});
-```
-
-### Using the Fixture in Playwright Tests
-
-#### Click Edit Button with a Single Locator
-
-```typescript
-import { test } from ".../fixtures";
-
-test("click edit button with a single locator", async ({ profile }) => {
-  // perform setup/navigation...
-
-  await profile.page.waitForURL(profile.fullUrl);
-
-  /** 
-   * returns the locator resolving to the full locatorSchemaPath
-   */
-  const editBtn = await profile.getLocator("content.region.details.button.edit");
-
-  await editBtn.click();
-});
-```
-
-#### Click Edit Button with a Nested Locator
-
-```typescript
-import { test } from ".../fixtures";
-
-test("click edit button with a nested locator", async ({ profile }) => {
-  // perform setup/navigation...
-
-  await profile.page.waitForURL(profile.fullUrl);
-
-  /** 
-   * returns a nested/chained locator consisting of the 3 locators: 
-   * content, 
-   * content.region.details
-   * content.region.details.button.edit
-   */
-  const editBtn = await profile.getNestedLocator("content.region.details.button.edit");
-
-  await editBtn.click();
-});
-```
-
-#### Specify Index for Nested Locators
-
-```typescript
-import { test } from ".../fixtures";
+## Documentation
 
-test("specify index for nested locator(s)", async ({ profile }) => {
-  // perform setup/navigation...
+Start with the introduction and continue through the topics:
 
-  await profile.page.waitForURL(profile.fullUrl);
-
-  /** 
-   * returns a nested/chained locator consisting of the 3 locators: 
-   * content 
-   * content.region.details with .first()
-   * content.region.details.button.edit with .nth(1)
-   */
-  const editBtn = await profile.getNestedLocator("content.region.details.button.edit", {
-    "content.region.details": 0, 
-    "content.region.details.button.edit": 1
-  });
-
-  await editBtn.click();
-});
-```
-
-#### Update a Locator Before Use
-
-```typescript
-import { test } from ".../fixtures";
-
-test("update a locator before use", async ({ profile }) => {
-  // perform setup/navigation...
-
-  await profile.page.waitForURL(profile.fullUrl);
-
-  /** 
-   * returns a nested/chained locator consisting of the 3 locators: 
-   * content, 
-   * content.region.details
-   * content.region.details.button.edit (updated)
-   */
-  const editBtn = await profile.getLocatorSchema("content.region.details.button.edit")
-    .update("content.region.details.button.edit", { 
-      roleOptions: { name: "Edit details" }
-    })
-    .getNestedLocator();
-
-  await editBtn.click();
-});
-```
-
-#### Update a Nested Locator Before Use
-
-```typescript
-import { test } from ".../fixtures";
-
-test("update a nested locator before use", async ({ profile }) => {
-  // perform setup/navigation...
-
-  await profile.page.waitForURL(profile.fullUrl);
-
-  /** 
-   * returns a nested/chained locator consisting of the 3 locators: 
-   * content, 
-   * content.region.details (updated)
-   * content.region.details.button.edit
-   */
-  const editBtn = await profile.getLocatorSchema("content.region.details.button.edit")
-    .update("content.region.details", { 
-      locator: ".profile-details",
-      locatorMethod: GetByMethod.locator
-    })
-    .getNestedLocator();
-
-  await editBtn.click();
-});
-```
-
-#### Make Multiple Versions of a Locator
-
-```typescript
-import { test } from ".../fixtures";
-
-test("make multiple versions of a locator", async ({ profile }) => {
-  // perform setup/navigation...
-
-  await profile.page.waitForURL(profile.fullUrl);
-
-  const editBtnSchema = profile.getLocatorSchema("content.region.details.button.edit");
-
-  const editBtn = await editBtnSchema.getLocator();
-  await editBtn.click();
-
-  editBtnSchema.update("content.region.details.button.edit", { roleOptions: { name: "Edit details" } });
-
-  const editBtnUpdated = await editBtnSchema.getNestedLocator();
-  await editBtnUpdated.click();
-
-  /**
-   * Calling profile.getLocatorSchema("content.region.details.button.edit") again 
-   * will return a new deepCopy of the original LocatorSchema
-   */
-});
-```
-
-## Deprecations
-
-### 1. Deprecated `.update` and `.updates` Methods
-
-- **Old `.update(updates: Partial<LocatorSchemaWithoutPath>): LocatorSchemaWithMethods`**
-- **Old `.updates(indexedUpdates: { [index: number]: Partial<LocatorSchemaWithoutPath> | null }): LocatorSchemaWithMethods`**
-
-**Reason:**  
-The `.updates` method relied on index-based updates, which are prone to errors and require manual maintenance, especially when `LocatorSchemaPath` strings are renamed or restructured. Additionally, the old `.update` method could only update the last `LocatorSchema` in the chain, making it less flexible.
-
-**Replacement:**  
-Use the new `.update(subPath, modifiedSchema)` method, which leverages valid `subPath`s of `LocatorSchemaPath` strings for more intuitive and maintainable updates.
-
-**Removal Schedule:**  
-These methods are deprecated and will be removed in version 2.0.0.
-
-### 2. Deprecated Old `getNestedLocator` Method
-
-- **Old `getNestedLocator(indices?: { [key: number]: number | null }): Promise<Locator>`**
-
-**Reason:**  
-Index-based indexing is less readable and requires manual updates when `LocatorSchemaPath` strings change.
-
-**Replacement:**  
-Use the updated `getNestedLocator(subPathIndices?: { [K in SubPaths<LocatorSchemaPathType, LocatorSubstring>]: number | null }): Promise<Locator>` method, which utilizes `LocatorSchemaPath` strings for indexing.
-
-**Removal Schedule:**  
-This method is deprecated and will be removed in version 2.0.0.
-
-## Migration Guide
-
-### Updating `.update` and `.updates` Methods
-
-**Old Usage:**
-```typescript
-const allCheckboxes = await poc
-  .getLocatorSchema("main.products.searchControls.filterType.label.checkbox")
-  .updates({ 3: { locatorOptions: { hasText: /Producer/i } } })
-  .getNestedLocator();
-```
-
-**New Usage:**
-```typescript
-const allCheckboxes = await poc
-  .getLocatorSchema("main.products.searchControls.filterType.label.checkbox")
-  .update("main.products.searchControls.filterType", { locatorOptions: { hasText: /Producer/i } })
-  .getNestedLocator();
-```
-
-### Updating `getNestedLocator` Method
-
-**Old Usage (Deprecated):**
-```typescript
-const saveBtn = await profile.getNestedLocator("content.region.details.button.save", { 4: 2 });
-
-const editBtn = await profile.getLocatorSchema("content.region.details.button.edit")
-  .getNestedLocator({ 2: index });
-```
-
-**New Usage:**
-```typescript
-const saveBtn = await profile.getNestedLocator("content.region.details.button.save", {
-  "content.region.details.button.save": 2 
-});
-
-const editBtn = await profile.getLocatorSchema("content.region.details.button.edit")
-  .getNestedLocator({ "content.region.details": index });
-```
-
-### Utilizing `LocatorSchemaPath` Instead of Indices
-
-Transition from index-based to `LocatorSchemaPath`-based indexing to improve code readability and maintainability.
-
-**Old Example:**
-```typescript
-const allCheckboxes = await poc
-  .getLocatorSchema("main.form.item.checkbox")
-  .updates({ 3: { locatorOptions: { hasText: /Producer/i } } })
-  .getNestedLocator();
-```
-
-**New Example:**
-```typescript
-const allCheckboxes = await poc
-  .getLocatorSchema("main.form.item.checkbox")
-  .update("main.form.item", { locatorOptions: { hasText: /Producer/i } })
-  .getNestedLocator();
-```
-
-## Example in Context
-
-### Defining a LocatorSchema with `filter` and Using `.addFilter()`
-
-```typescript
-// Defining LocatorSchemas
-this.locators.addSchema("body.main.section@userInfo", {
-  role: "region",
-  roleOptions: { name: "Contact Info" },
-  filter: { hasText: /e-mail/i },
-  locatorMethod: GetByMethod.role
-});
-
-// Dynamically adding additional filters using `.addFilter()`
-const specificSection = await poc
-  .getLocatorSchema("body.main.section@userInfo")
-  .addFilter("body.main.section@userInfo", { hasText: "Additional Services" })
-  .getNestedLocator();
-```
-
-### Updating LocatorSchemas with the New `.update()` Method
-
-```typescript
-const editBtn = await profile
-  .getLocatorSchema("content.region.details.button.edit")
-  .update("content.region.details.button.edit", { 
-    roleOptions: { name: "new accessibility name" }
-  })
-  .getNestedLocator();
-```
-
-### Reusing LocatorSchemas with `LocatorSchemaWithoutPath`
-
-```typescript
-import { GetByMethod, LocatorSchemaWithoutPath } from "pomwright";
-import { missingInputError } from "@common/page-components/errors.locatorSchema.ts";
-
-export type LocatorSchemaPath =
-  | "body"
-  | "body.main"
-  | "body.main.section"
-  | "body.main.section@products"
-  | "body.main.section@userInfo"
-  | "body.main.section@userInfo.input@email"
-  | "body.main.section@userInfo.inputError"
-  | "body.main.section@deliveryInfo";
-
-export function initLocatorSchemas(locators: GetLocatorBase<LocatorSchemaPath>) {
-  locators.addSchema("body", {
-    locator: "body",
-    locatorMethod: GetByMethod.locator,
-  });
-
-  locators.addSchema("body.main", {
-    locator: "main",
-    locatorMethod: GetByMethod.locator,
-  });
-
-  const region: LocatorSchemaWithoutPath = { role: "region", locatorMethod: GetByMethod.role };
-
-  locators.addSchema("body.main.section", {
-    ...region,
-  });
-
-  locators.addSchema("body.main.section@products", {
-    ...region,
-    roleOptions: { name: "Products" },
-  });
-
-  locators.addSchema("body.main.section@userInfo", {
-    ...region,
-    roleOptions: { name: "Contact Info" },
-    filter: { hasText: /e-mail/i },
-  });
-
-  locators.addSchema("body.main.section@userInfo.input@email", {
-    role: "textbox",
-    roleOptions: { name: "Input your e-mail" },
-    locatorMethod: GetByMethod.role,
-  });
-
-  locators.addSchema("body.main.section@userInfo.inputError", {
-    ...missingInputError,
-  });
-
-  locators.addSchema("body.main.section@deliveryInfo", {
-    ...region,
-    roleOptions: { name: "Delivery Info" },
-  });
-}
-```
+1. [Intro to using POMWright](./docs/intro-to-using-pomwright.md)
+2. [BasePage](./docs/BasePage-explanation.md)
+3. [LocatorSchemaPath](./docs/LocatorSchemaPath-explanation.md)
+4. [LocatorSchema](./docs/LocatorSchema-explanation.md)
+5. [Locator schema helper methods](./docs/get-locator-methods-explanation.md)
+6. [BaseApi](./docs/BaseApi-explanation.md)
+7. [PlaywrightReportLogger](./docs/PlaywrightReportLogger-explanation.md)
+8. [Session storage helpers](./docs/sessionStorage-methods-explanation.md)
+9. [Tips for structuring locator files](./docs/tips-folder-structure.md)
 
 ## Troubleshooting and Support
 
@@ -520,4 +64,4 @@ Pull Requests are welcome! Please open an issue or submit a pull request for any
 
 ## License
 
-POMWright is open-source software licensed under the [Apache-2.0 license](https://github.com/DyHex/POMWright/blob/main/LICENSE).
+POMWright is open-source software licensed under the [Apache-2.0 license](https://github.com/DyHex/POMWright/blob/main/LICENSE).