pomwright 1.0.2 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,204 @@
 # pomwright
 
+## 1.1.1
+
+### Patch Changes
+
+- [#29](https://github.com/DyHex/POMWright/pull/29) [`14b9bff`](https://github.com/DyHex/POMWright/commit/14b9bff99ec337a4d8b8940c9904620892faae3a) Thanks [@DyHex](https://github.com/DyHex)! - Exports ExtractFullUrlType, updates devDeps and adds additional keywords
+
+## 1.1.0
+
+### Minor Changes
+
+- [#27](https://github.com/DyHex/POMWright/pull/27) [`ab778b2`](https://github.com/DyHex/POMWright/commit/ab778b268fcc77c03289f24617efa74518dcbe12) Thanks [@DyHex](https://github.com/DyHex)! - **Added optional support for dynamic URL types (`string` and/or `RegExp`) for `baseUrl` and `urlPath` via an options-based approach.**
+
+  - **WHAT**: This update allows `baseUrl` and `urlPath` to be defined as either `string` or `RegExp` using `BasePageOptions`. The `fullUrl` is automatically inferred based on the types of `baseUrl` and `urlPath`. If either `baseUrl` or `urlPath` is a `RegExp`, `fullUrl` will also be a `RegExp`.
+
+  - **WHY**: This change provides flexibility for handling dynamic URLs, such as those containing variables or patterns. It allows validating URLs that follow a predictable format but may have dynamic values that are not known before navigation.
+
+  - **HOW**:
+    - No changes are required for existing implementations since `string` remains the default type.
+    - To use `RegExp` for `baseUrl` or `urlPath`, define them explicitly in the POC using `BasePageOptions`, which will automatically infer `fullUrl`.
+    - **Note**: POCs using `RegExp` for `baseUrl` or `urlPath` cannot use `page.goto(fullUrl)` since it requires a `string`. Instead, methods like `page.waitForURL()`, which accept `RegExp`, can be used to validate navigation. This feature is ideal for scenarios where URL values are dynamic and can only be validated by format.
+
+  # Examples
+
+  ## Example: Abstract Base Class extending BasePage without BasePageOptions (default, same as prior versions)
+
+  ```ts
+  import { type Page, type TestInfo } from "@playwright/test";
+  import { BasePage, PlaywrightReportLogger } from "pomwright";
+  // import helper methods / classes etc, here... (To be used in the Base POC)
+
+  export default abstract class Base<
+    LocatorSchemaPathType extends string
+  > extends BasePage<LocatorSchemaPathType> {
+    // add properties here (available to all POCs extending this abstract Base POC)
+
+    constructor(
+      page: Page,
+      testInfo: TestInfo,
+      urlPath: string,
+      pocName: string,
+      pwrl: PlaywrightReportLogger
+    ) {
+      super(page, testInfo, "http://localhost:8080", urlPath, pocName, pwrl);
+
+      // initialize properties here (available to all POCs extending this abstract Base POC)
+    }
+
+    // add helper methods here (available to all POCs extending this abstract Base POC)
+  }
+  ```
+
+  ## Example: POC extending abstract Base Class without BasePageOptions (default, same as prior versions)
+
+  ```ts
+  import { type Page, type TestInfo } from "@playwright/test";
+  import { PlaywrightReportLogger } from "pomwright";
+  import Base from "../base/base.page";
+  import {
+    type LocatorSchemaPath,
+    initLocatorSchemas,
+  } from "./testPage.locatorSchema";
+
+  export default class TestPage extends Base<LocatorSchemaPath> {
+    constructor(page: Page, testInfo: TestInfo, pwrl: PlaywrightReportLogger) {
+      super(page, testInfo, "/", TestPage.name, pwrl);
+    }
+
+    protected initLocatorSchemas() {
+      initLocatorSchemas(this.locators);
+    }
+
+    // add your helper methods here...
+  }
+  ```
+
+  ## Example: Abstract Base Class extending BasePage with BasePageOptions, allows urlPath type as string xOR RegExp
+
+  ```ts
+  import { type Page, type TestInfo } from "@playwright/test";
+  import {
+    BasePage,
+    type BasePageOptions,
+    type ExtractUrlPathType,
+    PlaywrightReportLogger,
+  } from "pomwright";
+
+  // BaseWithOptions extends BasePage and enforces baseUrlType as string
+  export default abstract class BaseWithOptions<
+    LocatorSchemaPathType extends string,
+    Options extends BasePageOptions = {
+      urlOptions: { baseUrlType: string; urlPathType: string };
+    }
+  > extends BasePage<
+    LocatorSchemaPathType,
+    {
+      urlOptions: {
+        baseUrlType: string;
+        urlPathType: ExtractUrlPathType<Options>;
+      };
+    }
+  > {
+    constructor(
+      page: Page,
+      testInfo: TestInfo,
+      urlPath: ExtractUrlPathType<{
+        urlOptions: { urlPathType: ExtractUrlPathType<Options> };
+      }>, // Ensure the correct type for urlPath
+      pocName: string,
+      pwrl: PlaywrightReportLogger
+    ) {
+      // Pass baseUrl as a string and let urlPath be flexible
+      super(page, testInfo, "http://localhost:8080", urlPath, pocName, pwrl);
+
+      // Initialize additional properties if needed
+    }
+
+    // Add any helper methods here, if needed
+  }
+  ```
+
+  ## Example: POC extending abstract Base Class with BasePageOptions, but uses defaults (type string)
+
+  ```ts
+  import {
+    type LocatorSchemaPath,
+    initLocatorSchemas,
+  } from "@page-object-models/testApp/without-options/pages/testPage.locatorSchema"; // same page & same locator schema as above
+  import { type Page, type TestInfo } from "@playwright/test";
+  import { PlaywrightReportLogger } from "pomwright";
+  import BaseWithOptions from "../base/baseWithOptions.page";
+
+  // Note, if BasePageOptions aren't specified, default options are used
+  export default class TestPage extends BaseWithOptions<LocatorSchemaPath> {
+    constructor(page: Page, testInfo: TestInfo, pwrl: PlaywrightReportLogger) {
+      super(page, testInfo, "/", TestPage.name, pwrl);
+    }
+
+    protected initLocatorSchemas() {
+      initLocatorSchemas(this.locators);
+    }
+
+    // add your helper methods here...
+  }
+  ```
+
+  ## Example: POC extending abstract Base Class with BasePageOptions, and defines urlPath type as RegExp
+
+  ```ts
+  import { test } from "@fixtures/withOptions";
+  import BaseWithOptions from "@page-object-models/testApp/with-options/base/baseWithOptions.page";
+  import { type Page, type TestInfo, expect } from "@playwright/test";
+  import { PlaywrightReportLogger } from "pomwright";
+  import {
+    type LocatorSchemaPath,
+    initLocatorSchemas,
+  } from "./color.locatorSchema";
+
+  // By providing the urlOptions, the urlPath property now has RegExp type instead of string type (default) for this POC
+  export default class Color extends BaseWithOptions<
+    LocatorSchemaPath,
+    { urlOptions: { urlPathType: RegExp } }
+  > {
+    constructor(page: Page, testInfo: TestInfo, pwrl: PlaywrightReportLogger) {
+      /**
+       * Matches "/testpath/randomcolor/" followed by a valid 3 or 6-character hex color code.
+       */
+      const urlPathRegex = /\/testpath\/([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/;
+
+      super(page, testInfo, urlPathRegex, Color.name, pwrl);
+    }
+
+    protected initLocatorSchemas() {
+      initLocatorSchemas(this.locators);
+    }
+
+    async expectThisPage() {
+      await test.step("Expect color page", async () => {
+        await this.page.waitForURL(this.fullUrl);
+
+        const heading = await this.getNestedLocator("body.heading");
+        await heading.waitFor({ state: "visible" });
+      });
+    }
+
+    // add your helper methods here...
+  }
+  ```
+
+  # Summary of Changes
+
+  - **Dynamic URL Support**: You can now define `baseUrl` and `urlPath` as `RegExp` for dynamic URL handling.
+  - **Backward Compatibility**: No changes are required for existing implementations using `string`.
+  - **Restructuring of tests**: Unit tests moved from ./src to ./test, integration tests moved from ./test to ./intTest
+  - **New unit tests**: To cover optional-dynamic-url-types (string xOR RegExp)
+  - **New integration tests with Playwright/test**: To cover optional-dynamic-url-types (string xOR RegExp)
+  - **peerDependencies change**: Bumped minimum Playwright/test version from 1.39.0 to 1.41.0 as everything below 1.41.0 is deprecated. Also excluded v. 2.x.x as they have known bugs for chaining of locators. Limited max version to <2.0.0
+
+  Changes have additionally been tested with two seperate playwright/test projects (130+ E2E tests) without issues, and against the latest Playwright/test versions.
+
 ## 1.0.2
 
 ### Patch Changes

package/dist/index.d.mts

@@ -232,14 +232,14 @@ interface ModifiedLocatorSchema extends UpdatableLocatorSchemaProperties {
  * and for building nested locators based on these schemas.
  */
 declare class GetLocatorBase<LocatorSchemaPathType extends string> {
-    protected pageObjectClass: BasePage<LocatorSchemaPathType>;
+    protected pageObjectClass: BasePage<LocatorSchemaPathType, BasePageOptions>;
     protected log: PlaywrightReportLogger;
     private getBy;
     private locatorSchemas;
     /**
      * Initializes the GetLocatorBase class with a page object class and a logger.
      */
-    constructor(pageObjectClass: BasePage<LocatorSchemaPathType>, log: PlaywrightReportLogger);
+    constructor(pageObjectClass: BasePage<LocatorSchemaPathType, BasePageOptions>, log: PlaywrightReportLogger);
     /**
      * Retrieves a locator schema with additional methods for manipulation and retrieval of locators.
      */
@@ -363,8 +363,30 @@ declare class SessionStorage {
     clear(): Promise<void>;
 }
 
+type BasePageOptions = {
+    urlOptions?: {
+        baseUrlType?: string | RegExp;
+        urlPathType?: string | RegExp;
+    };
+};
+type ExtractBaseUrlType<T extends BasePageOptions> = T["urlOptions"] extends {
+    baseUrlType: RegExp;
+} ? RegExp : string;
+type ExtractUrlPathType<T extends BasePageOptions> = T["urlOptions"] extends {
+    urlPathType: RegExp;
+} ? RegExp : string;
+type ExtractFullUrlType<T extends BasePageOptions> = T["urlOptions"] extends {
+    baseUrlType: RegExp;
+} | {
+    urlPathType: RegExp;
+} ? RegExp : string;
 /** The BasePage class, extended by all Page Object Classes */
-declare abstract class BasePage<LocatorSchemaPathType extends string> {
+declare abstract class BasePage<LocatorSchemaPathType extends string, Options extends BasePageOptions = {
+    urlOptions: {
+        baseUrlType: string;
+        urlPathType: string;
+    };
+}> {
     /** Provides Playwright page methods */
     page: Page;
     /** Playwright TestInfo contains information about currently running test, available to any test function */
@@ -372,10 +394,10 @@ declare abstract class BasePage<LocatorSchemaPathType extends string> {
     /** Selectors can be used to install custom selector engines.*/
     selector: Selectors;
     /** The base URL of the Page Object Class */
-    baseUrl: string;
+    baseUrl: ExtractBaseUrlType<Options>;
     /** The URL path of the Page Object Class */
-    urlPath: string;
-    fullUrl: string;
+    urlPath: ExtractUrlPathType<Options>;
+    fullUrl: ExtractFullUrlType<Options>;
     /** The name of the Page Object Class */
     pocName: string;
     /** The Page Object Class' PlaywrightReportLogger instance, prefixed with its name. Log levels: debug, info, warn, and error.  */
@@ -383,7 +405,8 @@ declare abstract class BasePage<LocatorSchemaPathType extends string> {
     /** The SessionStorage class provides methods for setting and getting session storage data in Playwright.*/
     sessionStorage: SessionStorage;
     protected locators: GetLocatorBase<LocatorSchemaPathType>;
-    constructor(page: Page, testInfo: TestInfo, baseUrl: string, urlPath: string, pocName: string, pwrl: PlaywrightReportLogger);
+    constructor(page: Page, testInfo: TestInfo, baseUrl: ExtractBaseUrlType<Options>, urlPath: ExtractUrlPathType<Options>, pocName: string, pwrl: PlaywrightReportLogger);
+    private constructFullUrl;
     /**
      * getNestedLocator(indices?: { [key: number]: number | null } | null)
      * - Asynchronously retrieves a nested locator based on the LocatorSchemaPath provided by getLocatorSchema("...")
@@ -394,7 +417,7 @@ declare abstract class BasePage<LocatorSchemaPathType extends string> {
      */
     getNestedLocator: (locatorSchemaPath: LocatorSchemaPathType, indices?: {
         [key: number]: number | null;
-    } | null | undefined) => Promise<Locator>;
+    } | null) => Promise<Locator>;
     /**
      * getLocator()
      * - Asynchronously retrieves a locator based on the current LocatorSchema. This method does not perform nesting,
@@ -488,16 +511,6 @@ declare abstract class BasePage<LocatorSchemaPathType extends string> {
      * GetLocatorBase class. It enriches the returned schema with additional methods to handle updates and retrieval of
      * deep copy locators.
      *
-     * Providing a precise and powerful solution for interacting with elements through locators in a structured
-     * or hierarchical manner:
-     * - Effortless validation of any element's expected location in the DOM.
-     * - Improved readability and maintainability of tests.
-     * - Improved readability and maintainability of Page Object Classes (POCs), through the use of a single source of
-     * truth and flat locator (LocatorSchema) structure.
-     * - Improved rebustness of tests in the face of DOM changes.
-     * - Simpler debugging and maintenance as a result of limitin/scoping the number of possible resolvable elements
-     * - Highly veratile usage
-     *
      * getLocatorSchema adds the following chainable methods to the returned LocatorSchemaWithMethods object:
      *
      * update(updates: Partial< UpdatableLocatorSchemaProperties >)
@@ -558,4 +571,4 @@ declare class BaseApi {
     constructor(baseUrl: string, apiName: string, context: APIRequestContext, pwrl: PlaywrightReportLogger);
 }
 
-export { type AriaRoleType, BaseApi, BasePage, GetByMethod, GetLocatorBase, type LocatorSchema, PlaywrightReportLogger, test };
+export { type AriaRoleType, BaseApi, BasePage, type BasePageOptions, type ExtractBaseUrlType, type ExtractFullUrlType, type ExtractUrlPathType, GetByMethod, GetLocatorBase, type LocatorSchema, PlaywrightReportLogger, test };

package/dist/index.d.ts

@@ -232,14 +232,14 @@ interface ModifiedLocatorSchema extends UpdatableLocatorSchemaProperties {
  * and for building nested locators based on these schemas.
  */
 declare class GetLocatorBase<LocatorSchemaPathType extends string> {
-    protected pageObjectClass: BasePage<LocatorSchemaPathType>;
+    protected pageObjectClass: BasePage<LocatorSchemaPathType, BasePageOptions>;
     protected log: PlaywrightReportLogger;
     private getBy;
     private locatorSchemas;
     /**
      * Initializes the GetLocatorBase class with a page object class and a logger.
      */
-    constructor(pageObjectClass: BasePage<LocatorSchemaPathType>, log: PlaywrightReportLogger);
+    constructor(pageObjectClass: BasePage<LocatorSchemaPathType, BasePageOptions>, log: PlaywrightReportLogger);
     /**
      * Retrieves a locator schema with additional methods for manipulation and retrieval of locators.
      */
@@ -363,8 +363,30 @@ declare class SessionStorage {
     clear(): Promise<void>;
 }
 
+type BasePageOptions = {
+    urlOptions?: {
+        baseUrlType?: string | RegExp;
+        urlPathType?: string | RegExp;
+    };
+};
+type ExtractBaseUrlType<T extends BasePageOptions> = T["urlOptions"] extends {
+    baseUrlType: RegExp;
+} ? RegExp : string;
+type ExtractUrlPathType<T extends BasePageOptions> = T["urlOptions"] extends {
+    urlPathType: RegExp;
+} ? RegExp : string;
+type ExtractFullUrlType<T extends BasePageOptions> = T["urlOptions"] extends {
+    baseUrlType: RegExp;
+} | {
+    urlPathType: RegExp;
+} ? RegExp : string;
 /** The BasePage class, extended by all Page Object Classes */
-declare abstract class BasePage<LocatorSchemaPathType extends string> {
+declare abstract class BasePage<LocatorSchemaPathType extends string, Options extends BasePageOptions = {
+    urlOptions: {
+        baseUrlType: string;
+        urlPathType: string;
+    };
+}> {
     /** Provides Playwright page methods */
     page: Page;
     /** Playwright TestInfo contains information about currently running test, available to any test function */
@@ -372,10 +394,10 @@ declare abstract class BasePage<LocatorSchemaPathType extends string> {
     /** Selectors can be used to install custom selector engines.*/
     selector: Selectors;
     /** The base URL of the Page Object Class */
-    baseUrl: string;
+    baseUrl: ExtractBaseUrlType<Options>;
     /** The URL path of the Page Object Class */
-    urlPath: string;
-    fullUrl: string;
+    urlPath: ExtractUrlPathType<Options>;
+    fullUrl: ExtractFullUrlType<Options>;
     /** The name of the Page Object Class */
     pocName: string;
     /** The Page Object Class' PlaywrightReportLogger instance, prefixed with its name. Log levels: debug, info, warn, and error.  */
@@ -383,7 +405,8 @@ declare abstract class BasePage<LocatorSchemaPathType extends string> {
     /** The SessionStorage class provides methods for setting and getting session storage data in Playwright.*/
     sessionStorage: SessionStorage;
     protected locators: GetLocatorBase<LocatorSchemaPathType>;
-    constructor(page: Page, testInfo: TestInfo, baseUrl: string, urlPath: string, pocName: string, pwrl: PlaywrightReportLogger);
+    constructor(page: Page, testInfo: TestInfo, baseUrl: ExtractBaseUrlType<Options>, urlPath: ExtractUrlPathType<Options>, pocName: string, pwrl: PlaywrightReportLogger);
+    private constructFullUrl;
     /**
      * getNestedLocator(indices?: { [key: number]: number | null } | null)
      * - Asynchronously retrieves a nested locator based on the LocatorSchemaPath provided by getLocatorSchema("...")
@@ -394,7 +417,7 @@ declare abstract class BasePage<LocatorSchemaPathType extends string> {
      */
     getNestedLocator: (locatorSchemaPath: LocatorSchemaPathType, indices?: {
         [key: number]: number | null;
-    } | null | undefined) => Promise<Locator>;
+    } | null) => Promise<Locator>;
     /**
      * getLocator()
      * - Asynchronously retrieves a locator based on the current LocatorSchema. This method does not perform nesting,
@@ -488,16 +511,6 @@ declare abstract class BasePage<LocatorSchemaPathType extends string> {
      * GetLocatorBase class. It enriches the returned schema with additional methods to handle updates and retrieval of
      * deep copy locators.
      *
-     * Providing a precise and powerful solution for interacting with elements through locators in a structured
-     * or hierarchical manner:
-     * - Effortless validation of any element's expected location in the DOM.
-     * - Improved readability and maintainability of tests.
-     * - Improved readability and maintainability of Page Object Classes (POCs), through the use of a single source of
-     * truth and flat locator (LocatorSchema) structure.
-     * - Improved rebustness of tests in the face of DOM changes.
-     * - Simpler debugging and maintenance as a result of limitin/scoping the number of possible resolvable elements
-     * - Highly veratile usage
-     *
      * getLocatorSchema adds the following chainable methods to the returned LocatorSchemaWithMethods object:
      *
      * update(updates: Partial< UpdatableLocatorSchemaProperties >)
@@ -558,4 +571,4 @@ declare class BaseApi {
     constructor(baseUrl: string, apiName: string, context: APIRequestContext, pwrl: PlaywrightReportLogger);
 }
 
-export { type AriaRoleType, BaseApi, BasePage, GetByMethod, GetLocatorBase, type LocatorSchema, PlaywrightReportLogger, test };
+export { type AriaRoleType, BaseApi, BasePage, type BasePageOptions, type ExtractBaseUrlType, type ExtractFullUrlType, type ExtractUrlPathType, GetByMethod, GetLocatorBase, type LocatorSchema, PlaywrightReportLogger, test };