pomwright 0.0.9 → 1.0.1

package/dist/index.js

@@ -20,12 +20,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // index.ts
 var POMWright_exports = {};
 __export(POMWright_exports, {
+  BaseApi: () => BaseApi,
+  BasePage: () => BasePage2,
   GetByMethod: () => GetByMethod,
-  POMWright: () => BasePage2,
-  POMWrightApi: () => BaseApi,
-  POMWrightGetLocatorBase: () => GetLocatorBase,
-  POMWrightLogger: () => PlaywrightReportLogger,
-  POMWrightTestFixture: () => test3
+  GetLocatorBase: () => GetLocatorBase,
+  PlaywrightReportLogger: () => PlaywrightReportLogger,
+  test: () => test3
 });
 module.exports = __toCommonJS(POMWright_exports);
 
@@ -106,6 +106,7 @@ function getLocatorSchemaDummy() {
 
 // src/helpers/playwrightReportLogger.ts
 var PlaywrightReportLogger = class _PlaywrightReportLogger {
+  // Initializes the logger with shared log level, log entries, and a context name.
   constructor(sharedLogLevel, sharedLogEntry, contextName) {
     this.sharedLogLevel = sharedLogLevel;
     this.sharedLogEntry = sharedLogEntry;
@@ -114,28 +115,16 @@ var PlaywrightReportLogger = class _PlaywrightReportLogger {
   contextName;
   logLevels = ["debug", "info", "warn", "error"];
   /**
-   * Creates a new logger instance with a new contextual name which includes a reference to the parent logger.
+   * Creates a child logger with a new contextual name, sharing the same log level and log entries with the parent logger.
    *
    * The root loggers log "level" is referenced by all child loggers and their child loggers and so on...
    * Changing the log "level" of one, will change it for all.
-   *
-   * @param prefix - The prefix to add to the new logger instance.
-   * @returns - A new logger instance with the updated prefix.
    */
   getNewChildLogger(prefix) {
-    return new _PlaywrightReportLogger(
-      this.sharedLogLevel,
-      this.sharedLogEntry,
-      `${this.contextName} -> ${prefix}`
-    );
+    return new _PlaywrightReportLogger(this.sharedLogLevel, this.sharedLogEntry, `${this.contextName} -> ${prefix}`);
   }
   /**
-   * Logs a message with the specified log level, prefix, and arguments.
-   * The message will only be recorded if the current log level allows it.
-   *
-   * @param level - The log level for the message.
-   * @param message - The log message.
-   * @param args - Additional arguments to log.
+   * Logs a message with the specified log level, prefix, and additional arguments if the current log level permits.
    */
   // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   log(level, message, ...args) {
@@ -154,9 +143,6 @@ ${args.join("\n\n")}`
   }
   /**
    * Logs a debug-level message with the specified message and arguments.
-   *
-   * @param message - The log message.
-   * @param args - Additional arguments to log.
    */
   // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   debug(message, ...args) {
@@ -164,9 +150,6 @@ ${args.join("\n\n")}`
   }
   /**
    * Logs a info-level message with the specified message and arguments.
-   *
-   * @param message - The log message.
-   * @param args - Additional arguments to log.
    */
   // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   info(message, ...args) {
@@ -174,9 +157,6 @@ ${args.join("\n\n")}`
   }
   /**
    * Logs a warn-level message with the specified message and arguments.
-   *
-   * @param message - The log message.
-   * @param args - Additional arguments to log.
    */
   // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   warn(message, ...args) {
@@ -184,54 +164,43 @@ ${args.join("\n\n")}`
   }
   /**
    * Logs a error-level message with the specified message and arguments.
-   *
-   * @param message - The log message.
-   * @param args - Additional arguments to log.
    */
   // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   error(message, ...args) {
     this.log("error", message, ...args);
   }
   /**
-   * Set logLevel during runtime.
-   *
-   * @param level - The logLevel ("debug" | "info" | "warn" | "error").
+   * Sets the current log level to the specified level during runTime.
    */
   setLogLevel(level) {
     this.sharedLogLevel.current = level;
   }
   /**
-   * Returns the current logLevel during runtime.
-   *
-   * @returns LogLevel ("debug" | "info" | "warn" | "error")
+   * Retrieves the current log level during runtime.
    */
   getCurrentLogLevel() {
     return this.sharedLogLevel.current;
   }
   /**
-   * Returns the index of the current logLevel during runtime.
+   * Retrieves the index of the current log level in the logLevels array during runtime.
    */
   getCurrentLogLevelIndex() {
     return this.logLevels.indexOf(this.sharedLogLevel.current);
   }
   /**
-   * Sets logLevel back to the initial logLevel during runtime.
+   * Resets the current log level to the initial level during runtime.
    */
   resetLogLevel() {
     this.sharedLogLevel.current = this.sharedLogLevel.initial;
   }
   /**
-   * isCurrentLogLevel is a method that checks if the input log level is equal to the current log level of the PlaywrightReportLogger instance.
-   * @param level The log level to check if it is equal to the current log level.
-   * @returns A boolean indicating whether the input log level is equal to the current log level.
+   * Checks if the input log level is equal to the current log level of the PlaywrightReportLogger instance.
    */
   isCurrentLogLevel(level) {
     return this.sharedLogLevel.current === level;
   }
   /**
-   * isLogLevelEnabled returns 'true' if the "level" parameter provided has an equal or greater index than the current logLevel.
-   * @param level
-   * @returns
+   * Returns 'true' if the "level" parameter provided has an equal or greater index than the current logLevel.
    */
   isLogLevelEnabled(level) {
     const logLevelIndex = this.logLevels.indexOf(level);
@@ -241,14 +210,10 @@ ${args.join("\n\n")}`
     return true;
   }
   /**
-   * Attaches the recorded logs to the Playwright HTML report.
-   *
-   * @param testInfo - The test information object from Playwright.
+   * Attaches the recorded log entries to the Playwright HTML report in a sorted and formatted manner.
    */
   attachLogsToTest(testInfo) {
-    this.sharedLogEntry.sort(
-      (a, b) => a.timestamp.getTime() - b.timestamp.getTime()
-    );
+    this.sharedLogEntry.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
     for (const log of this.sharedLogEntry) {
       const printTime = log.timestamp.toLocaleTimeString("nb-NO", {
         hour: "2-digit",
@@ -272,13 +237,10 @@ ${args.join("\n\n")}`
         messageContentType = "text/plain";
         messageBody = log.message;
       }
-      testInfo.attach(
-        `${printTime} ${printDate} - ${printLogLevel} ${printPrefix}`,
-        {
-          contentType: messageContentType,
-          body: Buffer.from(messageBody)
-        }
-      );
+      testInfo.attach(`${printTime} ${printDate} - ${printLogLevel} ${printPrefix}`, {
+        contentType: messageContentType,
+        body: Buffer.from(messageBody)
+      });
     }
   }
 };
@@ -316,10 +278,9 @@ var GetBy = class {
   // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   subMethodMap;
   /**
-   * Retrieves a Playwright Locator based on the method specified in the LocatorSchema.
-   *
-   * @param locatorSchema The LocatorSchema object specifying the locator method and its parameters.
-   * @returns A promise that resolves to the appropriate Playwright Locator.
+   * Retrieves a Locator based on the details provided in a LocatorSchema.
+   * The method identifies the appropriate locator creation function from methodMap and invokes it.
+   * Throws an error if the locator method is unsupported.
    */
   getLocator = (locatorSchema) => {
     const methodName = locatorSchema.locatorMethod;
@@ -329,6 +290,11 @@ var GetBy = class {
     }
     throw new Error(`Unsupported locator method: ${methodName}`);
   };
+  /**
+   * Internal method to retrieve a Locator using a specified GetByMethodSubset and LocatorSchema.
+   * It identifies the appropriate locator creation function from subMethodMap and invokes it.
+   * Throws an error if the caller is unknown or if the initial locator is not found.
+   */
   getBy = (caller, locator) => {
     const method = this.subMethodMap[caller];
     if (!method) {
@@ -345,70 +311,29 @@ var GetBy = class {
     return initialPWLocator;
   };
   /**
-   * Creates a new method that returns a Playwright Locator using the specified method name.
-   *
-   * @param methodName The name of the method to use for getting the element.
-   * @returns An async function that takes a locator and returns a Playwright Locator.
+   * Creates a method for generating a Locator using a specific GetByMethodSubset.
+   * Returns a function that takes a LocatorSchema and returns a Locator.
+   * The returned function is a locator creation function corresponding to the specified methodName.
    */
   createByMethod = (methodName) => {
     return (locator) => {
       return this.getBy(methodName, locator);
     };
   };
-  /**
-   *  Returns a {@link Locator} using the selectors 'role' (required) and 'roleOptions' (optional), from a {@link LocatorSchema} Object.
-   *
-   * @param locator - The locator.
-   * @returns - A promise that resolves to the {@link Locator}.
-   */
+  // Methods for creating locators using different locator methods.
+  // These methods are generated using createByMethod and provide a unified way to create locators based on LocatorSchema.
+  // Each method is responsible for creating a Locator based on a specific attribute (role, text, label, etc.) provided in LocatorSchema.
+  // These methods return a Locator and throw an error if the necessary attribute is not defined in the LocatorSchema.
   role = this.createByMethod("role" /* role */);
-  /**
-   * Returns a {@link Locator} using the selectors 'text' (required) and 'textOptions' (optional), from a {@link LocatorSchema} Object.
-   *
-   * @param locator - The locator.
-   * @returns - A promise that resolves to the {@link Locator}.
-   */
   text = this.createByMethod("text" /* text */);
-  /**
-   * Returns a {@link Locator} using the selectors 'label' (required) and 'labelOptions' (optional), from a {@link LocatorSchema} Object.
-   *
-   * @param locator - The locator.
-   * @returns - A promise that resolves to the {@link Locator}.
-   */
   label = this.createByMethod("label" /* label */);
-  /**
-   *  Returns a {@link Locator} using the selectors 'placeholder' (required) and 'placeholderOptions' (optional), from a {@link LocatorSchema} Object.
-   *
-   * @param locator - The locator.
-   * @returns - A promise that resolves to the {@link Locator}.
-   */
   placeholder = this.createByMethod("placeholder" /* placeholder */);
-  /**
-   *  Returns a {@link Locator} using the selectors 'altText' (required) and 'altTextOptions' (optional), from a {@link LocatorSchema} Object.
-   *
-   * @param locator - The locator.
-   * @returns - A promise that resolves to the {@link Locator}.
-   */
   altText = this.createByMethod("altText" /* altText */);
-  /**
-   *  Returns a {@link Locator} using the selectors 'title' (required) and 'titleOptions' (optional), from a {@link LocatorSchema} Object.
-   *
-   * @param locator - The locator.
-   * @returns - A promise that resolves to the {@link Locator}.
-   */
   title = this.createByMethod("title" /* title */);
-  /**
-   *  Returns a {@link Locator} using the selectors 'locator' (required), from a {@link LocatorSchema} Object.
-   *
-   * @param locator - The locator.
-   * @returns - A promise that resolves to the {@link Locator}.
-   */
   locator = this.createByMethod("locator" /* locator */);
   /**
-   *  Returns a {@link FrameLocator} using the selector string 'frameLocator' (required), from a {@link LocatorSchema} Object.
-   *
-   * @param locatorSchema - Which contains the frameLocator selector.
-   * @returns A promise that resolves to the {@link FrameLocator}.
+   * Returns a FrameLocator using the 'frameLocator' selector from a LocatorSchema.
+   * Throws an error if the frameLocator is not defined.
    */
   frameLocator = (locatorSchema) => {
     const initialFrameLocator = locatorSchema.frameLocator ? this.page.frameLocator(locatorSchema.frameLocator) : null;
@@ -420,27 +345,21 @@ var GetBy = class {
     return initialFrameLocator;
   };
   /**
-   *  Returns a {@link Locator} using the selectors 'testId' (required), from a {@link LocatorSchema} Object.
-   *
-   * @param locator - The locator.
-   * @returns - A promise that resolves to the {@link Locator}.
+   * Returns a Locator using the 'testId' selector from a LocatorSchema.
+   * Throws an error if the testId is not defined.
    */
   testId = (locator) => {
     const initialPWLocator = locator.testId ? this.page.getByTestId(locator.testId) : null;
     if (!initialPWLocator) {
       const errorText = `Locator "${locator.locatorSchemaPath}" .testId is not defined.`;
-      this.log.warn(
-        `Locator "${locator.locatorSchemaPath}" .testId is not defined.`
-      );
+      this.log.warn(`Locator "${locator.locatorSchemaPath}" .testId is not defined.`);
       throw new Error(errorText);
     }
     return initialPWLocator;
   };
   /**
-   *  Returns a {@link Locator} using the selectors 'dataCy' (required), from a {@link LocatorSchema} Object.
-   *
-   * @param locator - The locator.
-   * @returns - A promise that resolves to the {@link Locator}.
+   * Returns a Locator using the 'dataCy' selector from a LocatorSchema.
+   * Throws an error if the dataCy is undefined.
    */
   dataCy = (locator) => {
     let initialPWLocator = null;
@@ -454,10 +373,8 @@ var GetBy = class {
     return initialPWLocator;
   };
   /**
-   *  Returns a {@link Locator} using the selectors 'id' (required), from a {@link LocatorSchema} Object.
-   *
-   * @param locator - The locator.
-   * @returns - A promise that resolves to the {@link Locator}.
+   * Returns a Locator using the 'id' selector from a LocatorSchema.
+   * Throws an error if the id is not defined or the id type is unsupported.
    */
   id = (locator) => {
     let initialPWLocator = null;
@@ -490,38 +407,34 @@ var GetBy = class {
 };
 
 // src/helpers/getLocatorBase.ts
+var REQUIRED_PROPERTIES_FOR_LOCATOR_SCHEMA_WITH_METHODS = [
+  "update",
+  "updates",
+  "getNestedLocator",
+  "getLocator",
+  "locatorSchemaPath",
+  "locatorMethod",
+  "schemasMap"
+];
 var GetLocatorBase = class {
   /**
-   * Constructor for the GetLocatorBaseClass.
-   *
-   * @param {BasePage} pageObjectClass - The page object class to which the locator pertains.
-   * @param {PlaywrightReportLogger} log - The PlaywrightReportLogger child of the page object class.
+   * Initializes the GetLocatorBase class with a page object class and a logger.
    */
   constructor(pageObjectClass, log) {
     this.pageObjectClass = pageObjectClass;
     this.log = log;
     this.locatorSchemas = /* @__PURE__ */ new Map();
-    this.getBy = new GetBy(
-      this.pageObjectClass.page,
-      this.log.getNewChildLogger("GetBy")
-    );
+    this.getBy = new GetBy(this.pageObjectClass.page, this.log.getNewChildLogger("GetBy"));
   }
   getBy;
   locatorSchemas;
   /**
-   * test
-   * @param locatorSchemaPath
-   * @returns
+   * Retrieves a locator schema with additional methods for manipulation and retrieval of locators.
    */
   getLocatorSchema(locatorSchemaPath) {
     const pathIndexPairs = this.extractPathsFromSchema(locatorSchemaPath);
-    const schemasMap = this.collectDeepCopies(
-      locatorSchemaPath,
-      pathIndexPairs
-    );
-    const locatorSchemaCopy = schemasMap.get(
-      locatorSchemaPath
-    );
+    const schemasMap = this.collectDeepCopies(locatorSchemaPath, pathIndexPairs);
+    const locatorSchemaCopy = schemasMap.get(locatorSchemaPath);
     locatorSchemaCopy.schemasMap = schemasMap;
     const self = this;
     locatorSchemaCopy.update = function(updates) {
@@ -533,17 +446,17 @@ var GetLocatorBase = class {
       return this;
     };
     locatorSchemaCopy.getNestedLocator = async (indices) => {
-      return await this.buildNestedLocator(
-        locatorSchemaPath,
-        schemasMap,
-        indices
-      );
+      return await this.buildNestedLocator(locatorSchemaPath, schemasMap, indices);
     };
     locatorSchemaCopy.getLocator = async () => {
       return this.getBy.getLocator(locatorSchemaCopy);
     };
     return locatorSchemaCopy;
   }
+  /**
+   * Collects deep copies of locator schemas based on a given locator schema path and path-index pairs.
+   * It ensures that each locator schema and its sub-schemas are properly cloned and stored.
+   */
   collectDeepCopies(locatorSchemaPath, pathIndexPairs) {
     const schemasMap = /* @__PURE__ */ new Map();
     const fullSchemaFunc = this.safeGetLocatorSchema(locatorSchemaPath);
@@ -563,54 +476,81 @@ var GetLocatorBase = class {
     }
     return schemasMap;
   }
+  isLocatorSchemaWithMethods(schema) {
+    return REQUIRED_PROPERTIES_FOR_LOCATOR_SCHEMA_WITH_METHODS.every((p) => p in schema);
+  }
+  /**
+   * Applies an update to a specific locator schema within the provided map of schemas.
+   * This method ensures that the specified updates are merged into the targeted locator schema.
+   */
   applyUpdate(schemasMap, locatorSchemaPath, updateData) {
     const schema = schemasMap.get(locatorSchemaPath);
     if (schema) {
-      schemasMap.set(locatorSchemaPath, this.deepMerge(schema, updateData));
+      const updatedSchema = this.deepMerge(schema, updateData);
+      if (this.isLocatorSchemaWithMethods(schema)) {
+        Object.assign(schema, updatedSchema);
+      } else {
+        throw new Error("Invalid LocatorSchema object provided for update method.");
+      }
     }
   }
+  /**
+   * Applies multiple updates to locator schemas based on provided path-index pairs and update data.
+   * This method facilitates batch updating of nested schemas within a complex locator structure.
+   */
   applyUpdates(schemasMap, pathIndexPairs, updatesData) {
     for (const [index, updateAtIndex] of Object.entries(updatesData)) {
       const path = pathIndexPairs[parseInt(index)]?.path;
       if (path && updateAtIndex) {
         const schema = schemasMap.get(path);
         if (schema) {
-          schemasMap.set(path, this.deepMerge(schema, updateAtIndex));
+          const updatedSchema = this.deepMerge(schema, updateAtIndex);
+          if (this.isLocatorSchemaWithMethods(schema)) {
+            Object.assign(schema, updatedSchema);
+          } else {
+            schemasMap.set(path, updatedSchema);
+          }
         }
       }
     }
   }
+  /**
+   * Creates a new locator schema based on provided schema details and a schema path.
+   * This method structures a new locator schema ready for inclusion in the locator management system.
+   */
   createLocatorSchema(schemaDetails, locatorSchemaPath) {
     const schema = { ...schemaDetails, locatorSchemaPath };
     return schema;
   }
+  /**
+   * Adds a new locator schema to the internal map of locator schemas.
+   * This method ensures that the new schema is properly registered and can be referenced and used in locator generation.
+   */
   addSchema(locatorSchemaPath, schemaDetails) {
-    const newLocatorSchema = this.createLocatorSchema(
-      schemaDetails,
-      locatorSchemaPath
-    );
+    const newLocatorSchema = this.createLocatorSchema(schemaDetails, locatorSchemaPath);
     const existingSchemaFunc = this.safeGetLocatorSchema(locatorSchemaPath);
     if (existingSchemaFunc) {
       const existingLocatorSchema = existingSchemaFunc();
       throw new Error(
         `[${this.pageObjectClass.pocName}] A LocatorSchema with the path '${locatorSchemaPath}' already exists. 
-Existing Schema: ${JSON.stringify(
-          existingLocatorSchema,
-          null,
-          2
-        )} 
-Attempted to Add Schema: ${JSON.stringify(
-          newLocatorSchema,
-          null,
-          2
-        )}`
+Existing Schema: ${JSON.stringify(existingLocatorSchema, null, 2)} 
+Attempted to Add Schema: ${JSON.stringify(newLocatorSchema, null, 2)}`
       );
     }
     this.locatorSchemas.set(locatorSchemaPath, () => newLocatorSchema);
   }
+  /**
+   * Safely retrieves a locator schema function based on a given path.
+   * This method provides a secure way to access locator schemas, ensuring that only valid paths are used.
+   */
   safeGetLocatorSchema(path) {
     return this.locatorSchemas.get(path);
   }
+  /**
+   * Extracts path-index pairs from a given schema path.
+   * This utility function breaks down a complex path into manageable parts,
+   * associating each part with its corresponding index when necessary.
+   */
   extractPathsFromSchema = (paths, indices = {}) => {
     const schemaParts = paths.split(".");
     let cumulativePath = "";
@@ -645,51 +585,59 @@ Attempted to Add Schema: ${JSON.stringify(
     );
     throw error;
   };
-  // Merges 'source' into 'target', combining their properties into a new isolated object.
-  deepMerge(target, source) {
+  /** Merges 'source' into 'target', combining their properties into a new isolated object. */
+  deepMerge(target, source, schema = getLocatorSchemaDummy()) {
     const merged = { ...target };
-    const dummySchema = getLocatorSchemaDummy();
-    if (typeof source === "object" && source !== null) {
-      const filteredKeys = Object.keys(source).filter(
-        (key) => key !== "locatorSchemaPath"
-      );
-      for (const key of filteredKeys) {
-        const targetKey = key;
-        const sourceKey = key;
-        if (!(key in dummySchema)) {
-          throw new Error(
-            `Invalid property: '${key}' is not a valid property of LocatorSchema`
+    for (const key of Object.keys(source)) {
+      if (key === "locatorSchemaPath") {
+        throw new Error(
+          `[${this.pageObjectClass.pocName}] Invalid property: 'locatorSchemaPath' cannot be updated. Attempted to update LocatorSchemaPath from '${target[key]}' to '${source[key]}'.`
+        );
+      }
+      if (!(key in schema)) {
+        throw new Error(`Invalid property: '${key}' is not a valid property of LocatorSchema`);
+      }
+      const sourceValue = source[key];
+      const targetValue = target[key];
+      if (typeof sourceValue === "object" && sourceValue !== null && schema[key] && typeof schema[key] === "object") {
+        if (targetValue && typeof targetValue === "object" && !Array.isArray(targetValue)) {
+          merged[key] = this.deepMerge(
+            targetValue,
+            // Updated type here
+            sourceValue,
+            schema[key]
+          );
+        } else {
+          merged[key] = this.deepMerge(
+            {},
+            // Updated type here
+            sourceValue,
+            schema[key]
           );
         }
-        const targetValue = merged[targetKey];
-        const sourceValue = source[sourceKey];
-        if (sourceValue !== void 0) {
-          if (Array.isArray(targetValue) && Array.isArray(sourceValue)) {
-            merged[targetKey] = [
-              ...targetValue,
-              ...sourceValue
-            ];
-          } else if (sourceValue instanceof RegExp) {
-            merged[targetKey] = new RegExp(
-              sourceValue.source,
-              sourceValue.flags
-            );
-          } else if (typeof sourceValue === "object" && sourceValue !== null) {
-            merged[targetKey] = targetValue ? this.deepMerge(targetValue, sourceValue) : structuredClone(sourceValue);
-          } else {
-            merged[targetKey] = sourceValue;
-          }
+      } else {
+        if (Array.isArray(sourceValue)) {
+          merged[key] = Array.isArray(targetValue) ? targetValue.concat(sourceValue) : [...sourceValue];
+        } else if (typeof sourceValue === "object" && sourceValue !== null && Object.prototype.toString.call(sourceValue) === "[object RegExp]") {
+          merged[key] = new RegExp(
+            sourceValue.source,
+            sourceValue.flags
+          );
+        } else {
+          merged[key] = sourceValue;
         }
       }
     }
     return merged;
   }
+  /**
+   * Assembles nested locators based on a locator schema path and optional indices for locating specific elements.
+   * This method orchestrates the process of building a locator that can resolve to a specific element or set of
+   * elements in the DOM.
+   */
   buildNestedLocator = async (locatorSchemaPath, schemasMap, indices = {}) => {
     return await import_test2.test.step(`${this.pageObjectClass.pocName}: Build Nested Locator`, async () => {
-      const pathIndexPairs = this.extractPathsFromSchema(
-        locatorSchemaPath,
-        indices
-      );
+      const pathIndexPairs = this.extractPathsFromSchema(locatorSchemaPath, indices);
       let currentLocator = null;
       let currentIFrame = null;
       const nestedLocatorResults = {
@@ -732,36 +680,19 @@ Attempted to Add Schema: ${JSON.stringify(
               }
             }
             if (currentIFrame !== void 0) {
-              await this.evaluateCurrentLocator(
-                currentLocator,
-                nestedLocatorResults.NestingSteps,
-                currentIFrame
-              );
+              await this.evaluateCurrentLocator(currentLocator, nestedLocatorResults.NestingSteps, currentIFrame);
             } else {
-              await this.evaluateCurrentLocator(
-                currentLocator,
-                nestedLocatorResults.NestingSteps,
-                null
-              );
+              await this.evaluateCurrentLocator(currentLocator, nestedLocatorResults.NestingSteps, null);
             }
           }
         } catch (error) {
-          this.logError(
-            error,
-            locatorSchemaPath,
-            currentLocator,
-            path,
-            pathIndexPairs,
-            nestedLocatorResults
-          );
+          this.logError(error, locatorSchemaPath, currentLocator, path, pathIndexPairs, nestedLocatorResults);
           break;
         }
       }
       if (!currentLocator) {
         this.logError(
-          new Error(
-            `Failed to build nested locator for path: ${locatorSchemaPath}`
-          ),
+          new Error(`Failed to build nested locator for path: ${locatorSchemaPath}`),
           locatorSchemaPath,
           currentLocator,
           locatorSchemaPath,
@@ -769,10 +700,7 @@ Attempted to Add Schema: ${JSON.stringify(
         );
       }
       if (this.log.isLogLevelEnabled("debug")) {
-        this.log.debug(
-          "Nested locator evaluation results:",
-          JSON.stringify(nestedLocatorResults, null, 2)
-        );
+        this.log.debug("Nested locator evaluation results:", JSON.stringify(nestedLocatorResults, null, 2));
       }
       if (currentLocator != null) {
         currentLocator.scrollIntoViewIfNeeded().catch(() => {
@@ -781,6 +709,9 @@ Attempted to Add Schema: ${JSON.stringify(
       }
     });
   };
+  /**
+   * Evaluates the current locator, capturing details about its resolution status and the elements it resolves to.
+   */
   evaluateCurrentLocator = async (currentLocator, resultsArray, currentIFrame) => {
     if (currentIFrame) {
       resultsArray.push({
@@ -799,17 +730,13 @@ Attempted to Add Schema: ${JSON.stringify(
     }
   };
   /**
-   * Evaluates the Playwright locator, checking if it resolves to any elements, and retrieves element attributes.
-   *
-   * @param pwLocator - The Playwright locator to evaluate.
-   * @returns - A promise that resolves to an object containing the Playwright locator and an array of element attributes for each element located, or null if no elements are found.
+   * Retrieves and compiles attributes of elements resolved by a Playwright locator per nesting step.
+   * This method provides insights into the elements targeted by the locator, aiding in debugging and verification.
    */
   evaluateAndGetAttributes = async (pwLocator) => {
     return await pwLocator.evaluateAll(
       (objects) => objects.map((el) => {
-        const elementAttributes = el.hasAttributes() ? Object.fromEntries(
-          Array.from(el.attributes).map(({ name, value }) => [name, value])
-        ) : {};
+        const elementAttributes = el.hasAttributes() ? Object.fromEntries(Array.from(el.attributes).map(({ name, value }) => [name, value])) : {};
         return { tagName: el.tagName, attributes: elementAttributes };
       })
     );
@@ -819,18 +746,17 @@ Attempted to Add Schema: ${JSON.stringify(
 // src/helpers/sessionStorage.actions.ts
 var import_test3 = require("@playwright/test");
 var SessionStorage = class {
+  // Initializes the class with a Playwright Page object and a name for the Page Object Class.
   constructor(page, pocName) {
     this.page = page;
     this.pocName = pocName;
   }
+  // Defines an object to hold states to be set in session storage, allowing any value type.
   // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   queuedStates = {};
+  // Indicates if the session storage manipulation has been initiated.
   isInitiated = false;
-  /**
-   * Writes states to the sessionStorage. Private utility function.
-   *
-   * @param states An object representing the states (key/value pairs) to set.
-   */
+  /** Writes states to session storage. Accepts an object with key-value pairs representing the states. */
   // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   async writeToSessionStorage(states) {
     await this.page.evaluate((storage) => {
@@ -839,11 +765,7 @@ var SessionStorage = class {
       }
     }, states);
   }
-  /**
-   * Reads all states from the sessionStorage. Private utility function.
-   *
-   * @returns An object containing all states from the sessionStorage.
-   */
+  /** Reads all states from session storage and returns them as an object. */
   // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   async readFromSessionStorage() {
     return await this.page.evaluate(() => {
@@ -863,13 +785,12 @@ var SessionStorage = class {
     });
   }
   /**
-   * Sets the specified states in the sessionStorage.
-   *
-   * @param states An object representing the states (key/value pairs) to set in sessionStorage.
-   * @param reload If true, reloads the page after setting the sessionStorage data.
+   * Sets the specified states in session storage.
+   * Optionally reloads the page after setting the data to ensure the new session storage state is active.
    *
-   * Usage:
-   * await set({ user: 'John Doe', token: 'abc123' }, true);
+   * Parameters:
+   * states: Object representing the states to set in session storage.
+   * reload: Boolean indicating whether to reload the page after setting the session storage data.
    */
   // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   async set(states, reload) {
@@ -882,16 +803,14 @@ var SessionStorage = class {
   }
   /**
    * Queues states to be set in the sessionStorage before the next navigation occurs.
-   * This handles multiple scenarios:
+   * Handles different scenarios based on whether the context exists or multiple calls are made.
    *
    * 1. No Context, Single Call: Queues and sets states upon the next navigation.
    * 2. No Context, Multiple Calls: Merges states from multiple calls and sets them upon the next navigation.
    * 3. With Context: Directly sets states in sessionStorage if the context already exists.
    *
-   * @param states An object representing the states (key/value pairs) to set.
-   *
-   * Usage:
-   * await setOnNextNavigation({ key: 'value' });
+   * Parameters:
+   * states: Object representing the states to queue for setting in session storage.
    */
   // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   async setOnNextNavigation(states) {
@@ -922,14 +841,14 @@ var SessionStorage = class {
     }
   }
   /**
-   * Fetches all or selected states from sessionStorage.
+   * Fetches states from session storage.
+   * If specific keys are provided, fetches only those states; otherwise, fetches all states.
    *
-   * @param keys Optional array of keys to fetch from sessionStorage.
-   * @returns An object containing the fetched states.
+   * Parameters:
+   * keys: Optional array of keys to specify which states to fetch from session storage.
    *
-   * Usage:
-   * 1. To fetch all states: await get();
-   * 2. To fetch selected states: await get(['key1', 'key2']);
+   * Returns:
+   * Object containing the fetched states.
    */
   // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   async get(keys) {
@@ -950,9 +869,6 @@ var SessionStorage = class {
   }
   /**
    * Clears all states in sessionStorage.
-   *
-   * Usage:
-   * await clear();
    */
   async clear() {
     await import_test3.test.step(`${this.pocName}: clear SessionStorage`, async () => {
@@ -964,11 +880,32 @@ var SessionStorage = class {
 // src/utils/selectorEngines.ts
 function createCypressIdEngine() {
   return {
+    /**
+     * Uses the document's querySelector method to find the first element with a specific 'data-cy' attribute.
+     * Constructs a selector string for the 'data-cy' attribute and searches the DOM for the first match.
+     *
+     * Parameters:
+     * - document: An object that mimics the global document, having a querySelector method.
+     * - selector: A string representing the value of the 'data-cy' attribute to search for.
+     *
+     * Returns the first HTML element matching the 'data-cy' attribute, or null if no match is found.
+     */
     query(document, selector) {
       const attr = `[data-cy="${selector}"]`;
       const el = document.querySelector(attr);
       return el;
     },
+    /**
+     * Uses the document's querySelectorAll method to find all elements with a specific 'data-cy' attribute.
+     * Constructs a selector string for the 'data-cy' attribute and retrieves all matching elements in the DOM.
+     * Converts the NodeList from querySelectorAll into an array for easier handling and manipulation.
+     *
+     * Parameters:
+     * - document: An object that mimics the global document, having a querySelectorAll method.
+     * - selector: A string representing the value of the 'data-cy' attribute to search for.
+     *
+     * Returns an array of HTML elements matching the 'data-cy' attribute. Returns an empty array if no matches are found.
+     */
     queryAll(document, selector) {
       const attr = `[data-cy="${selector}"]`;
       const els = Array.from(document.querySelectorAll(attr));
@@ -1007,10 +944,7 @@ var BasePage2 = class {
     this.fullUrl = `${this.baseUrl}${this.urlPath}`;
     this.pocName = pocName;
     this.log = pwrl.getNewChildLogger(pocName);
-    this.locators = new GetLocatorBase(
-      this,
-      this.log.getNewChildLogger("GetLocator")
-    );
+    this.locators = new GetLocatorBase(this, this.log.getNewChildLogger("GetLocator"));
     this.initLocatorSchemas();
     this.sessionStorage = new SessionStorage(this.page, this.pocName);
     if (!selectorRegistered) {
@@ -1019,63 +953,84 @@ var BasePage2 = class {
     }
   }
   /**
-   * Asynchronously retrieves a nested locator based on the provided LocatorSchemaPath and optional indices per nested locator.
-   * Useful for interacting with elements in a structured or hierarchical manner, reducing the number of possible elements we can resolve to.
-   *
-   * The update and updates methods cannot be used with this method. Use the getLocatorSchema method instead.
-   *
-   * @param LocatorSchemaPathType locatorSchemaPath - The unique path identifier for the locator schema.
-   * @param indices - An optional object to specify the nth occurrence of each nested locator.
-   * @returns Promise<Locator> - A promise that resolves to the nested locator.
+   * getNestedLocator(indices?: { [key: number]: number | null } | null)
+   * - Asynchronously retrieves a nested locator based on the LocatorSchemaPath provided by getLocatorSchema("...")
+   * - Can be chained after the update and updates methods, getNestedLocator will end the chain.
+   * - The optional parameter of the method takes an object with 0-based indices "{0: 0, 3: 1}" for one or more locators
+   * to be nested given by sub-paths (indices correspond to last "word" of a sub-path).
+   * - Returns a promise that resolves to the nested locator.
    */
   getNestedLocator = async (locatorSchemaPath, indices) => {
-    return await this.getLocatorSchema(locatorSchemaPath).getNestedLocator(
-      indices
-    );
+    return await this.getLocatorSchema(locatorSchemaPath).getNestedLocator(indices);
   };
   /**
-   * Asynchronously retrieves the locator based on the current LocatorSchemaPath. This method does not perform nesting.
-   * Useful for directly interacting with an element based on its LocatorSchema.
-   *
-   * The update and updates methods cannot be used with this method. Use the getLocatorSchema method instead.
-   *
-   * @param LocatorSchemaPathType locatorSchemaPath - The unique path identifier for the locator schema.
-   * @returns Promise<Locator> - A promise that resolves to the nested locator.
+   * getLocator()
+   * - Asynchronously retrieves a locator based on the current LocatorSchema. This method does not perform nesting,
+   * and will return the locator for which the full LocatorSchemaPath resolves to, provided by getLocatorSchema("...")
+   * - Can be chained after the update and updates methods, getLocator will end the chain.
+   * - Returns a promise that resolves to the locator.
    */
   getLocator = async (locatorSchemaPath) => {
     return await this.getLocatorSchema(locatorSchemaPath).getLocator();
   };
   /**
-   * The "getLocatorSchema" method is used to retrieve a deep copy of a locator schema defined in the GetLocatorBase class.
-   * It enriches the returned schema with additional methods to handle updates and retrieval of deep copy locators.
+   * The "getLocatorSchema" method is used to retrieve an updatable deep copy of a LocatorSchema defined in the
+   * GetLocatorBase class. It enriches the returned schema with additional methods to handle updates and retrieval of
+   * deep copy locators.
    *
-   * @param LocatorSchemaPathType locatorSchemaPath - The unique path identifier for the locator schema.
-   * @returns LocatorSchemaWithMethods - A deep copy of the locator schema with additional methods.
+   * 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
    *
-   * Methods added to the returned LocatorSchemaWithMethods object:
+   * getLocatorSchema adds the following chainable methods to the returned LocatorSchemaWithMethods object:
    *
-   * - update(updates: Partial<UpdatableLocatorSchemaProperties>):
-   *      Allows updating properties of the locator schema.
-   *      This method is used for modifying the current schema without affecting the original schema.
-   *      @param updates - An object with properties to be updated in the locator schema, omits the locatorSchemaPath parameter.
-   *      @returns LocatorSchemaWithMethods - The updated locator schema object.
+   * update(updates: Partial< UpdatableLocatorSchemaProperties >)
+   * - Allows updating the properties of the LocatorSchema which the full LocatorSchemaPath resolves to.
+   * - This method is used for modifying the current schema without affecting the original schema.
+   * - Takes a "LocatorSchema" object which omits the locatorSchemaPath parameter as input, the parameters provided
+   * will overwrite the corresponding property in the current schema.
+   * - Returns the updated deep copy of the "LocatorSchema" with methods.
+   * - Can be chained with the update and updates methods, and the getLocator or getNestedLocator method.
    *
-   * - updates(indexedUpdates: { [index: number]: Partial<UpdatableLocatorSchemaProperties> | null }):
-   *      Similar to update, but allows for indexed updates of any locator to be nested within the path.
-   *      This method is used for modifying the current schema without affecting the original schema
-   *      @param indexedUpdates - An object where keys represent index levels, and values are the updates at each level.
-   *      @returns LocatorSchemaWithMethods - The locator schema object with indexed updates.
+   * updates(indexedUpdates: { [index: number]: Partial< UpdatableLocatorSchemaProperties > | null }):
+   * - Similar to update, but allows updating any locator in the nested chain (all sub-paths of the LocatorSchemaPath).
+   * - This method can modify the current deep copy of each LocatorSchema that each sub-path resolves to without
+   * affecting the original schemas
+   * - Takes an object where keys represent the index of the last "word" of a sub-path, where the value per key is a
+   * "LocatorSchema" object which omits the locatorSchemaPath parameter as input, the parameters provided will overwrite
+   * the corresponding property in the given schema.
+   * - Returns the updated deep copy of the LocatorSchema object with methods and its own updated deep copies for all
+   * LocatorSchema each sub-path resolved to.
+   * - Can be chained with the update and updates methods, and the getLocator or getNestedLocator method.
    *
-   * - getNestedLocator(indices?: { [key: number]: number | null }):
-   *      Asynchronously retrieves a nested locator based on the current schema and optional indices per nested locator.
-   *      Useful for interacting with elements in a structured or hierarchical manner.
-   *      @param indices - An optional object to specify the nth occurrence of each nested locator.
-   *      @returns Promise<Locator> - A promise that resolves to the nested locator.
+   * getNestedLocator(indices?: { [key: number]: number | null } | null)
+   * - Asynchronously retrieves a nested locator based on the LocatorSchemaPath provided by getLocatorSchema("...")
+   * - Can be chained after the update and updates methods, getNestedLocator will end the chain.
+   * - The optional parameter of the method takes an object with 0-based indices "{0: 0, 3: 1}" for one or more locators
+   * to be nested given by sub-paths (indices correspond to last "word" of a sub-path).
+   * - Returns a promise that resolves to the nested locator.
    *
-   * - getLocator():
-   *      Asynchronously retrieves the locator based on the current schema. This method does not consider nesting.
-   *      Useful for directly interacting with an element based on its schema.
-   *      @returns Promise<Locator> - A promise that resolves to the locator.
+   * getLocator()
+   * - Asynchronously retrieves a locator based on the current LocatorSchema. This method does not perform nesting,
+   * and will return the locator for which the full LocatorSchemaPath resolves to, provided by getLocatorSchema("...")
+   * - Can be chained after the update and updates methods, getLocator will end the chain.
+   * - Returns a promise that resolves to the locator.
+   *
+   * Note: Calling getLocator() and getNestedLocator() on the same LocatorSchemaPath will return a Locator for the same
+   * element, but the Locator returned by getNestedLocator() will be a locator resolving to said same element through
+   * a chain of locators. While the Locator returned by getLocator() will be a single locator which resolves directly
+   * to said element. Thus getLocator() is rarely used, while getNestedLocator() is used extensively.
+   *
+   * That said, for certain use cases, getLocator() can be useful, and you could use it to manually chain locators
+   * yourself if some edge case required it. Though, it would be likely be more prudent to expand your LocatorSchemaPath
+   * type and initLocatorSchemas() method to include the additional locators you need for the given POC, and then use
+   * getNestedLocator() instead.
    */
   getLocatorSchema(locatorSchemaPath) {
     return this.locators.getLocatorSchema(locatorSchemaPath);
@@ -1090,11 +1045,7 @@ var test3 = import_test5.test.extend({
     const contextName = "TestCase";
     const sharedLogEntry = [];
     const sharedLogLevel = testInfo.retry === 0 ? { current: "warn", initial: "warn" } : { current: "debug", initial: "debug" };
-    const log = new PlaywrightReportLogger(
-      sharedLogLevel,
-      sharedLogEntry,
-      contextName
-    );
+    const log = new PlaywrightReportLogger(sharedLogLevel, sharedLogEntry, contextName);
     await use(log);
     log.attachLogsToTest(testInfo);
   }
@@ -1115,10 +1066,10 @@ var BaseApi = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BaseApi,
+  BasePage,
   GetByMethod,
-  POMWright,
-  POMWrightApi,
-  POMWrightGetLocatorBase,
-  POMWrightLogger,
-  POMWrightTestFixture
+  GetLocatorBase,
+  PlaywrightReportLogger,
+  test
 });