pomwright 1.1.0 → 1.2.0

package/dist/index.js

@@ -21,7 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var POMWright_exports = {};
 __export(POMWright_exports, {
   BaseApi: () => BaseApi,
-  BasePage: () => BasePage2,
+  BasePage: () => BasePage,
   GetByMethod: () => GetByMethod,
   GetLocatorBase: () => GetLocatorBase,
   PlaywrightReportLogger: () => PlaywrightReportLogger,
@@ -30,12 +30,9 @@ __export(POMWright_exports, {
 module.exports = __toCommonJS(POMWright_exports);
 
 // src/basePage.ts
-var import_test4 = require("@playwright/test");
+var import_test3 = require("@playwright/test");
 
 // src/helpers/getLocatorBase.ts
-var import_test2 = require("@playwright/test");
-
-// src/helpers/getBy.locator.ts
 var import_test = require("@playwright/test");
 
 // src/helpers/locatorSchema.interface.ts
@@ -97,6 +94,12 @@ var locatorSchemaDummy = {
   testId: void 0,
   dataCy: void 0,
   id: void 0,
+  filter: {
+    has: void 0,
+    hasNot: void 0,
+    hasNotText: void 0,
+    hasText: void 0
+  },
   locatorMethod: void 0,
   locatorSchemaPath: void 0
 };
@@ -104,147 +107,6 @@ function getLocatorSchemaDummy() {
   return locatorSchemaDummy;
 }
 
-// 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;
-    this.contextName = contextName;
-  }
-  contextName;
-  logLevels = ["debug", "info", "warn", "error"];
-  /**
-   * 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.
-   */
-  getNewChildLogger(prefix) {
-    return new _PlaywrightReportLogger(this.sharedLogLevel, this.sharedLogEntry, `${this.contextName} -> ${prefix}`);
-  }
-  /**
-   * 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) {
-    const logLevelIndex = this.logLevels.indexOf(level);
-    if (logLevelIndex < this.getCurrentLogLevelIndex()) {
-      return;
-    }
-    this.sharedLogEntry.push({
-      timestamp: /* @__PURE__ */ new Date(),
-      logLevel: level,
-      prefix: this.contextName,
-      message: `${message}
-
-${args.join("\n\n")}`
-    });
-  }
-  /**
-   * Logs a debug-level message with the specified message and arguments.
-   */
-  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
-  debug(message, ...args) {
-    this.log("debug", message, ...args);
-  }
-  /**
-   * Logs a info-level message with the specified message and arguments.
-   */
-  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
-  info(message, ...args) {
-    this.log("info", message, ...args);
-  }
-  /**
-   * Logs a warn-level message with the specified message and arguments.
-   */
-  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
-  warn(message, ...args) {
-    this.log("warn", message, ...args);
-  }
-  /**
-   * Logs a error-level message with the specified message and arguments.
-   */
-  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
-  error(message, ...args) {
-    this.log("error", message, ...args);
-  }
-  /**
-   * Sets the current log level to the specified level during runTime.
-   */
-  setLogLevel(level) {
-    this.sharedLogLevel.current = level;
-  }
-  /**
-   * Retrieves the current log level during runtime.
-   */
-  getCurrentLogLevel() {
-    return this.sharedLogLevel.current;
-  }
-  /**
-   * Retrieves the index of the current log level in the logLevels array during runtime.
-   */
-  getCurrentLogLevelIndex() {
-    return this.logLevels.indexOf(this.sharedLogLevel.current);
-  }
-  /**
-   * Resets the current log level to the initial level during runtime.
-   */
-  resetLogLevel() {
-    this.sharedLogLevel.current = this.sharedLogLevel.initial;
-  }
-  /**
-   * Checks if the input log level is equal to the current log level of the PlaywrightReportLogger instance.
-   */
-  isCurrentLogLevel(level) {
-    return this.sharedLogLevel.current === level;
-  }
-  /**
-   * 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);
-    if (logLevelIndex < this.getCurrentLogLevelIndex()) {
-      return false;
-    }
-    return true;
-  }
-  /**
-   * 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());
-    for (const log of this.sharedLogEntry) {
-      const printTime = log.timestamp.toLocaleTimeString("nb-NO", {
-        hour: "2-digit",
-        minute: "2-digit",
-        second: "2-digit"
-      });
-      const printDate = log.timestamp.toLocaleDateString("nb-NO", {
-        day: "2-digit",
-        month: "2-digit",
-        year: "numeric"
-      });
-      const printLogLevel = `${log.logLevel.toUpperCase()}`;
-      const printPrefix = log.prefix ? `: [${log.prefix}]` : "";
-      let messageBody = "";
-      let messageContentType = "";
-      try {
-        const parsedMessage = JSON.parse(log.message);
-        messageContentType = "application/json";
-        messageBody = JSON.stringify(parsedMessage, null, 2);
-      } catch (error) {
-        messageContentType = "text/plain";
-        messageBody = log.message;
-      }
-      testInfo.attach(`${printTime} ${printDate} - ${printLogLevel} ${printPrefix}`, {
-        contentType: messageContentType,
-        body: Buffer.from(messageBody)
-      });
-    }
-  }
-};
-
 // src/helpers/getBy.locator.ts
 var GetBy = class {
   constructor(page, pwrl) {
@@ -410,52 +272,72 @@ var GetBy = class {
 var REQUIRED_PROPERTIES_FOR_LOCATOR_SCHEMA_WITH_METHODS = [
   "update",
   "updates",
+  "addFilter",
   "getNestedLocator",
   "getLocator",
   "locatorSchemaPath",
   "locatorMethod",
-  "schemasMap"
+  "schemasMap",
+  "filterMap"
 ];
+var safeStringifyOfNestedLocatorResults = (obj) => {
+  const seen = /* @__PURE__ */ new WeakSet();
+  return JSON.stringify(
+    obj,
+    (key, value) => {
+      if (value instanceof Map) {
+        return Array.from(value.entries());
+      }
+      if (value instanceof RegExp) {
+        return { type: "RegExp", source: value.source, flags: value.flags };
+      }
+      if (value && typeof value === "object" && value.constructor && value.constructor.name === "Locator") {
+        return { type: "Locator", note: "Custom placeholder - Locators are complex." };
+      }
+      if (typeof value === "object" && value !== null) {
+        if (seen.has(value)) return "[Circular]";
+        seen.add(value);
+      }
+      return value;
+    },
+    2
+  );
+};
 var GetLocatorBase = class {
-  /**
-   * Initializes the GetLocatorBase class with a page object class and a logger.
-   */
-  constructor(pageObjectClass, log) {
+  constructor(pageObjectClass, log, locatorSubstring) {
     this.pageObjectClass = pageObjectClass;
     this.log = log;
+    this.locatorSubstring = locatorSubstring;
     this.locatorSchemas = /* @__PURE__ */ new Map();
     this.getBy = new GetBy(this.pageObjectClass.page, this.log.getNewChildLogger("GetBy"));
   }
   getBy;
   locatorSchemas;
   /**
-   * Retrieves a locator schema with additional methods for manipulation and retrieval of locators.
+   * getLocatorSchema:
+   * Given a path P, we:
+   * 1. Collect deep copies of the schemas involved.
+   * 2. Create a WithMethodsClass instance with LocatorSubstring = P.
+   * 3. Return a locator schema copy enriched with chainable methods.
    */
   getLocatorSchema(locatorSchemaPath) {
     const pathIndexPairs = this.extractPathsFromSchema(locatorSchemaPath);
     const schemasMap = this.collectDeepCopies(locatorSchemaPath, pathIndexPairs);
     const locatorSchemaCopy = schemasMap.get(locatorSchemaPath);
     locatorSchemaCopy.schemasMap = schemasMap;
-    const self = this;
-    locatorSchemaCopy.update = function(updates) {
-      self.applyUpdate(schemasMap, locatorSchemaPath, updates);
-      return this;
-    };
-    locatorSchemaCopy.updates = function(indexedUpdates) {
-      self.applyUpdates(schemasMap, pathIndexPairs, indexedUpdates);
-      return this;
-    };
-    locatorSchemaCopy.getNestedLocator = async (indices) => {
-      return await this.buildNestedLocator(locatorSchemaPath, schemasMap, indices);
-    };
-    locatorSchemaCopy.getLocator = async () => {
-      return this.getBy.getLocator(locatorSchemaCopy);
-    };
-    return locatorSchemaCopy;
+    locatorSchemaCopy.filterMap = /* @__PURE__ */ new Map();
+    const wrapper = new WithMethodsClass(
+      this.pageObjectClass,
+      this.log,
+      locatorSchemaPath,
+      schemasMap
+    );
+    return wrapper.init(locatorSchemaPath, 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:
+   * Clones and stores all schemas related to the chosen path and its sub-paths.
+   * Ensures updates and filters don't affect original schema definitions.
    */
   collectDeepCopies(locatorSchemaPath, pathIndexPairs) {
     const schemasMap = /* @__PURE__ */ new Map();
@@ -480,8 +362,25 @@ var GetLocatorBase = class {
     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.
+   * applyUpdateToSubPath:
+   * Applies updates to a specific sub-path schema within schemasMap.
+   * Similar to applyUpdate, but we locate the sub-path schema directly by its path.
+   */
+  applyUpdateToSubPath(schemasMap, subPath, updates) {
+    const schema = schemasMap.get(subPath);
+    if (!schema) {
+      throw new Error(`No schema found for sub-path: '${subPath}'`);
+    }
+    const updatedSchema = this.deepMerge(schema, updates);
+    if (this.isLocatorSchemaWithMethods(schema)) {
+      Object.assign(schema, updatedSchema);
+    } else {
+      schemasMap.set(subPath, updatedSchema);
+    }
+  }
+  /**
+   * applyUpdate:
+   * Applies updates to a single schema within the schemasMap.
    */
   applyUpdate(schemasMap, locatorSchemaPath, updateData) {
     const schema = schemasMap.get(locatorSchemaPath);
@@ -495,12 +394,12 @@ var GetLocatorBase = class {
     }
   }
   /**
-   * 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:
+   * Applies multiple updates to multiple schemas in the chain, identified by their path indexes.
    */
   applyUpdates(schemasMap, pathIndexPairs, updatesData) {
     for (const [index, updateAtIndex] of Object.entries(updatesData)) {
-      const path = pathIndexPairs[parseInt(index)]?.path;
+      const path = pathIndexPairs[Number.parseInt(index)]?.path;
       if (path && updateAtIndex) {
         const schema = schemasMap.get(path);
         if (schema) {
@@ -515,16 +414,17 @@ var GetLocatorBase = class {
     }
   }
   /**
-   * 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:
+   * Creates a fresh LocatorSchema object by merging provided schemaDetails with a required locatorSchemaPath.
    */
   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:
+   * Registers a new LocatorSchema under the given locatorSchemaPath.
+   * Throws an error if a schema already exists at that path.
    */
   addSchema(locatorSchemaPath, schemaDetails) {
     const newLocatorSchema = this.createLocatorSchema(schemaDetails, locatorSchemaPath);
@@ -540,16 +440,16 @@ 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:
+   * Safely retrieves a schema function if available for the given path.
    */
   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:
+   * Splits a path into incremental sub-paths and associates them with optional indices.
+   * Used by updates and getNestedLocator methods.
    */
   extractPathsFromSchema = (paths, indices = {}) => {
     const schemaParts = paths.split(".");
@@ -563,8 +463,8 @@ Attempted to Add Schema: ${JSON.stringify(newLocatorSchema, null, 2)}`
     });
   };
   /**
-   * logError is a utility function for logging errors with detailed debug information
-   * It re-throws the error after logging to ensure the test will fail.
+   * logError:
+   * Logs detailed error information and re-throws the error to ensure tests fail as expected.
    */
   logError = (error, locatorSchemaPath, currentLocator, currentPath, pathIndexPairs, nestedLocatorResults) => {
     const errorDetails = {
@@ -576,7 +476,7 @@ Attempted to Add Schema: ${JSON.stringify(newLocatorSchema, null, 2)}`
         locatorString: currentLocator,
         isNotNull: true
       } : { isNotNull: false },
-      nestedLocatorResults
+      nestedLocatorResults: safeStringifyOfNestedLocatorResults(nestedLocatorResults)
     };
     this.log.error(
       "An error occurred during nested locator construction.\n",
@@ -585,7 +485,11 @@ Attempted to Add Schema: ${JSON.stringify(newLocatorSchema, null, 2)}`
     );
     throw error;
   };
-  /** Merges 'source' into 'target', combining their properties into a new isolated object. */
+  /**
+   * deepMerge:
+   * Recursively merges source properties into target, validating them against LocatorSchema to ensure no invalid keys.
+   * Ensures immutability by creating a new object rather than modifying in place.
+   */
   deepMerge(target, source, schema = getLocatorSchemaDummy()) {
     const merged = { ...target };
     for (const key of Object.keys(source)) {
@@ -610,7 +514,6 @@ Attempted to Add Schema: ${JSON.stringify(newLocatorSchema, null, 2)}`
         } else {
           merged[key] = this.deepMerge(
             {},
-            // Updated type here
             sourceValue,
             schema[key]
           );
@@ -631,52 +534,60 @@ Attempted to Add Schema: ${JSON.stringify(newLocatorSchema, null, 2)}`
     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:
+   * Constructs a nested locator by iterating through each sub-path of locatorSchemaPath and chaining locators.
+   * Applies filters, indexing (nth), and logs details for debugging during test retries.
    */
-  buildNestedLocator = async (locatorSchemaPath, schemasMap, indices = {}) => {
-    return await import_test2.test.step(`${this.pageObjectClass.pocName}: Build Nested Locator`, async () => {
+  buildNestedLocator = async (locatorSchemaPath, schemasMap, filterMap, indices = {}) => {
+    return await import_test.test.step(`${this.pageObjectClass.pocName}: Build Nested Locator`, async () => {
       const pathIndexPairs = this.extractPathsFromSchema(locatorSchemaPath, indices);
       let currentLocator = null;
       let currentIFrame = null;
       const nestedLocatorResults = {
         LocatorSchema: null,
-        // Initialize as an empty object
         NestingSteps: []
       };
       for (const { path, index } of pathIndexPairs) {
         const currentSchema = schemasMap.get(path);
-        if (!currentSchema)
-          continue;
+        if (!currentSchema) continue;
         try {
           const nextLocator = this.getBy.getLocator(currentSchema);
-          if (currentLocator) {
-            currentLocator = currentLocator.locator(nextLocator);
-            if (index != null) {
-              currentLocator = currentLocator.nth(index);
-            }
-          } else {
-            currentLocator = nextLocator;
-            if (index != null) {
-              currentLocator = currentLocator.nth(index);
+          currentLocator = currentLocator ? currentLocator.locator(nextLocator) : nextLocator;
+          if (currentSchema.locatorMethod !== "frameLocator" /* frameLocator */ && currentSchema.filter) {
+            currentLocator = currentLocator.filter({
+              has: currentSchema.filter.has,
+              hasNot: currentSchema.filter.hasNot,
+              hasNotText: currentSchema.filter.hasNotText,
+              hasText: currentSchema.filter.hasText
+            });
+          }
+          const filterEntries = filterMap.get(path);
+          if (filterEntries) {
+            for (const filterData of filterEntries) {
+              currentLocator = currentLocator.filter({
+                has: filterData.has,
+                hasNot: filterData.hasNot,
+                hasNotText: filterData.hasNotText,
+                hasText: filterData.hasText
+              });
             }
           }
+          if (index != null) {
+            currentLocator = currentLocator.nth(index);
+          }
           if (this.log.isLogLevelEnabled("debug")) {
             if (!nestedLocatorResults.LocatorSchema) {
-              const safeGetLocatorSchema = this.safeGetLocatorSchema(locatorSchemaPath);
-              if (safeGetLocatorSchema !== void 0) {
-                nestedLocatorResults.LocatorSchema = safeGetLocatorSchema();
+              const schemaFromMap = schemasMap.get(locatorSchemaPath);
+              if (schemaFromMap) {
+                nestedLocatorResults.LocatorSchema = schemaFromMap;
               }
             }
             if (currentSchema.locatorMethod === "frameLocator" /* frameLocator */) {
               if (!currentIFrame) {
                 currentIFrame = currentSchema.frameLocator;
               }
-              if (currentIFrame != null && currentSchema.frameLocator != null) {
-                if (currentIFrame.endsWith(currentSchema.frameLocator)) {
-                  currentIFrame += ` -> ${currentSchema.frameLocator}`;
-                }
+              if (currentIFrame && currentSchema.frameLocator && currentIFrame.endsWith(currentSchema.frameLocator)) {
+                currentIFrame += ` -> ${currentSchema.frameLocator}`;
               }
             }
             if (currentIFrame !== void 0) {
@@ -700,7 +611,7 @@ Attempted to Add Schema: ${JSON.stringify(newLocatorSchema, null, 2)}`
         );
       }
       if (this.log.isLogLevelEnabled("debug")) {
-        this.log.debug("Nested locator evaluation results:", JSON.stringify(nestedLocatorResults, null, 2));
+        this.log.debug("Nested locator evaluation results:", safeStringifyOfNestedLocatorResults(nestedLocatorResults));
       }
       if (currentLocator != null) {
         return currentLocator;
@@ -708,7 +619,9 @@ Attempted to Add Schema: ${JSON.stringify(newLocatorSchema, null, 2)}`
     });
   };
   /**
-   * Evaluates the current locator, capturing details about its resolution status and the elements it resolves to.
+   * evaluateCurrentLocator:
+   * Gathers debug information about the current locator's resolved elements.
+   * Helps with logging and debugging complex locator chains.
    */
   evaluateCurrentLocator = async (currentLocator, resultsArray, currentIFrame) => {
     if (currentIFrame) {
@@ -720,7 +633,7 @@ Attempted to Add Schema: ${JSON.stringify(newLocatorSchema, null, 2)}`
     } else {
       const elementsData = await this.evaluateAndGetAttributes(currentLocator);
       resultsArray.push({
-        currentLocatorString: currentLocator,
+        currentLocatorString: `${currentLocator}`,
         resolved: elementsData.length > 0,
         elementCount: elementsData.length,
         elementsResolvedTo: elementsData
@@ -728,8 +641,8 @@ Attempted to Add Schema: ${JSON.stringify(newLocatorSchema, null, 2)}`
     }
   };
   /**
-   * 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:
+   * Extracts tagName and attributes from all elements matched by the locator for debugging purposes.
    */
   evaluateAndGetAttributes = async (pwLocator) => {
     return await pwLocator.evaluateAll(
@@ -740,9 +653,129 @@ Attempted to Add Schema: ${JSON.stringify(newLocatorSchema, null, 2)}`
     );
   };
 };
+var WithMethodsClass = class extends GetLocatorBase {
+  constructor(pageObjectClass, log, locatorSubstring, schemasMap) {
+    super(pageObjectClass, log, locatorSubstring);
+    this.pageObjectClass = pageObjectClass;
+    this.log = log;
+    this.schemasMap = schemasMap;
+  }
+  locatorSchemaPath;
+  /**
+   * init:
+   * Assigns the locatorSchemaPath and binds methods (update, updates, addFilter, getNestedLocator, getLocator)
+   * directly on the locatorSchemaCopy. Returns the modified copy, now fully chainable and type-safe.
+   */
+  init(locatorSchemaPath, locatorSchemaCopy) {
+    this.locatorSchemaPath = locatorSchemaPath;
+    const self = this;
+    locatorSchemaCopy.update = function(a, b) {
+      const fullPath = this.locatorSchemaPath;
+      if (b === void 0) {
+        const updates = a;
+        self.applyUpdate(self.schemasMap, self.locatorSchemaPath, updates);
+      } else {
+        const subPath = a;
+        const updates = b;
+        if (!(subPath === fullPath || fullPath.startsWith(`${subPath}.`))) {
+          throw new Error(`Invalid sub-path: '${subPath}' is not a valid sub-path of '${fullPath}'.`);
+        }
+        self.applyUpdateToSubPath(self.schemasMap, subPath, updates);
+      }
+      return this;
+    };
+    locatorSchemaCopy.updates = function(indexedUpdates) {
+      const pathIndexPairs = self.extractPathsFromSchema(self.locatorSchemaPath);
+      self.applyUpdates(self.schemasMap, pathIndexPairs, indexedUpdates);
+      return this;
+    };
+    locatorSchemaCopy.addFilter = function(subPath, filterData) {
+      const fullPath = this.locatorSchemaPath;
+      if (!self.schemasMap.has(subPath)) {
+        const allowedPaths = self.extractPathsFromSchema(fullPath).map((p) => p.path).filter((path) => self.schemasMap.has(path));
+        throw new Error(
+          `Invalid sub-path '${subPath}' in addFilter. Allowed sub-paths are:
+${allowedPaths.join(",\n")}`
+        );
+      }
+      if (!this.filterMap) {
+        this.filterMap = /* @__PURE__ */ new Map();
+      }
+      const existingFilters = this.filterMap.get(subPath) || [];
+      existingFilters.push(filterData);
+      this.filterMap.set(subPath, existingFilters);
+      return this;
+    };
+    locatorSchemaCopy.getNestedLocator = async function(arg) {
+      if (arg !== void 0 && arg !== null && typeof arg !== "object") {
+        throw new Error("Invalid argument passed to getNestedLocator: Expected an object or null.");
+      }
+      if (!arg || Object.keys(arg).length === 0) {
+        return await self.buildNestedLocator(
+          self.locatorSchemaPath,
+          self.schemasMap,
+          this.filterMap,
+          {}
+        );
+      }
+      const keys = Object.keys(arg);
+      const isNumberKey = keys.every((key) => /^\d+$/.test(key));
+      const numericIndices = {};
+      if (isNumberKey) {
+        for (const [key, value] of Object.entries(arg)) {
+          const index = Number(key);
+          if (typeof value === "number" && value >= 0) {
+            numericIndices[index] = value;
+          } else if (value !== null) {
+            throw new Error(`Invalid index value at key '${key}': Expected a positive number or null.`);
+          }
+        }
+      } else {
+        const pathIndexPairs = self.extractPathsFromSchema(self.locatorSchemaPath);
+        const pathToIndexMap = new Map(pathIndexPairs.map((pair, idx) => [pair.path, idx]));
+        for (const [subPath, value] of Object.entries(arg)) {
+          if (!self.schemasMap.has(subPath)) {
+            const validPaths = Array.from(self.schemasMap.keys());
+            throw new Error(
+              `Invalid sub-path '${subPath}' in getNestedLocator. Allowed sub-paths are:
+${validPaths.join(",\n")}`
+            );
+          }
+          if (!pathToIndexMap.has(subPath)) {
+            const validPaths = pathIndexPairs.map((p) => p.path).filter((path) => self.schemasMap.has(path));
+            throw new Error(
+              `Invalid sub-path '${subPath}' in getNestedLocator. Allowed sub-paths are:
+${validPaths.join(",\n")}`
+            );
+          }
+          const numericIndex = pathToIndexMap.get(subPath);
+          if (numericIndex === void 0) {
+            throw new Error(`Sub-path '${subPath}' not found in pathToIndexMap.`);
+          }
+          if (value !== null && (typeof value !== "number" || value < 0)) {
+            throw new Error(`Invalid index for sub-path '${subPath}': Expected a positive number or null.`);
+          }
+          if (value !== null) {
+            numericIndices[numericIndex] = value;
+          }
+        }
+      }
+      return await self.buildNestedLocator(
+        self.locatorSchemaPath,
+        self.schemasMap,
+        this.filterMap,
+        numericIndices
+      );
+    };
+    locatorSchemaCopy.getLocator = async () => {
+      return self.getBy.getLocator(locatorSchemaCopy);
+    };
+    return locatorSchemaCopy;
+  }
+};
 
 // src/helpers/sessionStorage.actions.ts
-var import_test3 = require("@playwright/test");
+var import_test2 = 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) {
@@ -792,7 +825,7 @@ var SessionStorage = class {
    */
   // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   async set(states, reload) {
-    await import_test3.test.step(`${this.pocName}: setSessionStorage`, async () => {
+    await import_test2.test.step(`${this.pocName}: setSessionStorage`, async () => {
       await this.writeToSessionStorage(states);
       if (reload) {
         await this.page.reload();
@@ -814,7 +847,7 @@ var SessionStorage = class {
   async setOnNextNavigation(states) {
     this.queuedStates = { ...this.queuedStates, ...states };
     const populateStorage = async () => {
-      await import_test3.test.step(`${this.pocName}: setSessionStorageBeforeNavigation`, async () => {
+      await import_test2.test.step(`${this.pocName}: setSessionStorageBeforeNavigation`, async () => {
         await this.writeToSessionStorage(this.queuedStates);
       });
       this.queuedStates = {};
@@ -851,7 +884,7 @@ var SessionStorage = class {
   // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   async get(keys) {
     let result = {};
-    await import_test3.test.step(`${this.pocName}: getSessionStorage`, async () => {
+    await import_test2.test.step(`${this.pocName}: getSessionStorage`, async () => {
       const allData = await this.readFromSessionStorage();
       if (keys && keys.length > 0) {
         for (const key of keys) {
@@ -869,7 +902,7 @@ var SessionStorage = class {
    * Clears all states in sessionStorage.
    */
   async clear() {
-    await import_test3.test.step(`${this.pocName}: clear SessionStorage`, async () => {
+    await import_test2.test.step(`${this.pocName}: clear SessionStorage`, async () => {
       await this.page.evaluate(() => sessionStorage.clear());
     });
   }
@@ -914,7 +947,7 @@ function createCypressIdEngine() {
 
 // src/basePage.ts
 var selectorRegistered = false;
-var BasePage2 = class {
+var BasePage = class {
   /** Provides Playwright page methods */
   page;
   /** Playwright TestInfo contains information about currently running test, available to any test function */
@@ -922,12 +955,10 @@ var BasePage2 = class {
   /** Selectors can be used to install custom selector engines.*/
   selector;
   /** The base URL of the Page Object Class */
-  // baseUrl: string;
   baseUrl;
   /** The URL path of the Page Object Class */
-  // urlPath: string;
   urlPath;
-  // fullUrl: string;
+  /** The full URL of the Page Object Class */
   fullUrl;
   /** The name of the Page Object Class */
   pocName;
@@ -935,24 +966,39 @@ var BasePage2 = class {
   log;
   /** The SessionStorage class provides methods for setting and getting session storage data in Playwright.*/
   sessionStorage;
+  /**
+   * locators:
+   * An instance of GetLocatorBase that handles schema management and provides getLocatorSchema calls.
+   * Initially, LocatorSubstring is undefined. Once getLocatorSchema(path) is called,
+   * we get a chainable object typed with LocatorSubstring = P.
+   */
   locators;
-  constructor(page, testInfo, baseUrl, urlPath, pocName, pwrl) {
+  constructor(page, testInfo, baseUrl, urlPath, pocName, pwrl, locatorSubstring) {
     this.page = page;
     this.testInfo = testInfo;
-    this.selector = import_test4.selectors;
+    this.selector = import_test3.selectors;
     this.baseUrl = baseUrl;
     this.urlPath = urlPath;
     this.fullUrl = this.constructFullUrl(baseUrl, 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"),
+      locatorSubstring
+    );
     this.initLocatorSchemas();
     this.sessionStorage = new SessionStorage(this.page, this.pocName);
     if (!selectorRegistered) {
-      import_test4.selectors.register("data-cy", createCypressIdEngine);
+      import_test3.selectors.register("data-cy", createCypressIdEngine);
       selectorRegistered = true;
     }
   }
+  /**
+   * constructFullUrl:
+   * Combines baseUrl and urlPath, handling both strings and RegExps.
+   * Ensures a flexible approach to URL matching (string or regex-based).
+   */
   constructFullUrl(baseUrl, urlPath) {
     const escapeStringForRegExp = (str) => str.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&");
     if (typeof baseUrl === "string" && typeof urlPath === "string") {
@@ -970,64 +1016,67 @@ var BasePage2 = class {
     throw new Error("Invalid baseUrl or urlPath types. Expected string or RegExp.");
   }
   /**
-   * 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.
+   * Implementation of getNestedLocator.
    */
-  getNestedLocator = async (locatorSchemaPath, indices) => {
-    return await this.getLocatorSchema(locatorSchemaPath).getNestedLocator(indices);
-  };
+  async getNestedLocator(locatorSchemaPath, subPathIndices) {
+    const withValidation = new WithSubPathValidation(
+      this,
+      this.log.getNewChildLogger("SubPathValidation"),
+      locatorSchemaPath
+    );
+    return await withValidation.getNestedLocator(subPathIndices);
+  }
   /**
-   * 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.
+   * Short-hand wrapper method for calling .getLocatorSchema(LocatorSchemaPath).getLocator()
+   *
+   * This method does not perform nesting,and will return the locator for which the full LocatorSchemaPath resolves to,
+   * provided by getLocatorSchema("...")
+   *
+   * Note: This short-hand wrapper method is useful for quickly getting a locator without having to call
+   * getLocatorSchema("...") first. On the other hand, it can't be used to update or add filters to the LocatorSchema.
+   *
+   * @example
+   * // Usage:
+   * const submitButton = await poc.getLocator("main.form.button@submit");
+   * await expect(submitButton, "should only exist one submit button").toHaveCount(1);
    */
   getLocator = async (locatorSchemaPath) => {
     return await this.getLocatorSchema(locatorSchemaPath).getLocator();
   };
   /**
+   * getLocatorSchema:
+   * Delegates to this.locators.getLocatorSchema.
+   * Returns a chainable schema object for the given path.
+   * Once called with a specific path P, the update and addFilter methods are restricted to sub-paths of P.
+   *
    * 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.
    *
    * getLocatorSchema adds the following chainable methods to the returned LocatorSchemaWithMethods 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.
+   * update
+   * - Allows updating any schema in the chain by specifying the subPath directly.
+   * - Gives compile-time suggestions for valid sub-paths of the LocatorSchemaPath provided to .getLocatorSchema().
+   * - If you want to update multiple schemas, chain multiple .update() calls.
    *
-   * 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.
+   * addFilter(subPath: SubPaths<LocatorSchemaPathType, LocatorSubstring>, filterData: FilterEntry)
+   * - The equivalent of the Playwright locator.filter() method
+   * - This method is used for filtering the specified locator based on the provided filterData.
+   * - Can be chained multiple times to add multiple filters to the same or different LocatorSchema.
    *
-   * 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
+   * - Asynchronously builds a nested locator based on the LocatorSchemaPath provided by getLocatorSchema("...")
+   * - Can be chained once after the update and addFilter methods or directly on the .getLocatorSchema method.
+   * - getNestedLocator will end the method chain and return a nested Playwright Locator.
+   * - Optionally parameter takes a list of key(subPath)-value(index) pairs, the locator constructed from the LocatorSchema
+   * with the specified subPath will resolve to the .nth(n) occurrence of the element, within the chain.
    *
    * 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.
+   * - Asynchronously retrieves a locator based on the current LocatorSchemaPath.
+   * - This method does not perform nesting and will return the locator for which the full LocatorSchemaPath resolves to, provided by getLocatorSchema("...")
+   * - Can be chained once after the update and addFilter methods or directly on the .getLocatorSchema method.
+   * - getLocator will end the method chain and return a Playwright 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
@@ -1037,16 +1086,168 @@ var BasePage2 = class {
    * 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.
+   * getNestedLocator() instead, or by implementing a helper method on your Page Object Class.
    */
-  getLocatorSchema(locatorSchemaPath) {
-    return this.locators.getLocatorSchema(locatorSchemaPath);
+  getLocatorSchema(path) {
+    return this.locators.getLocatorSchema(path);
+  }
+};
+var WithSubPathValidation = class extends GetLocatorBase {
+  constructor(pageObjectClass, log, locatorSchemaPath) {
+    super(pageObjectClass, log, locatorSchemaPath);
+    this.locatorSchemaPath = locatorSchemaPath;
+  }
+  async getNestedLocator(arg) {
+    return await this.pageObjectClass.getLocatorSchema(this.locatorSchemaPath).getNestedLocator(arg);
+  }
+};
+
+// src/fixture/base.fixtures.ts
+var import_test4 = require("@playwright/test");
+
+// 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;
+    this.contextName = contextName;
+  }
+  contextName;
+  logLevels = ["debug", "info", "warn", "error"];
+  /**
+   * 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.
+   */
+  getNewChildLogger(prefix) {
+    return new _PlaywrightReportLogger(this.sharedLogLevel, this.sharedLogEntry, `${this.contextName} -> ${prefix}`);
+  }
+  /**
+   * 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) {
+    const logLevelIndex = this.logLevels.indexOf(level);
+    if (logLevelIndex < this.getCurrentLogLevelIndex()) {
+      return;
+    }
+    this.sharedLogEntry.push({
+      timestamp: /* @__PURE__ */ new Date(),
+      logLevel: level,
+      prefix: this.contextName,
+      message: `${message}
+
+${args.join("\n\n")}`
+    });
+  }
+  /**
+   * Logs a debug-level message with the specified message and arguments.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+  debug(message, ...args) {
+    this.log("debug", message, ...args);
+  }
+  /**
+   * Logs a info-level message with the specified message and arguments.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+  info(message, ...args) {
+    this.log("info", message, ...args);
+  }
+  /**
+   * Logs a warn-level message with the specified message and arguments.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+  warn(message, ...args) {
+    this.log("warn", message, ...args);
+  }
+  /**
+   * Logs a error-level message with the specified message and arguments.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+  error(message, ...args) {
+    this.log("error", message, ...args);
+  }
+  /**
+   * Sets the current log level to the specified level during runTime.
+   */
+  setLogLevel(level) {
+    this.sharedLogLevel.current = level;
+  }
+  /**
+   * Retrieves the current log level during runtime.
+   */
+  getCurrentLogLevel() {
+    return this.sharedLogLevel.current;
+  }
+  /**
+   * Retrieves the index of the current log level in the logLevels array during runtime.
+   */
+  getCurrentLogLevelIndex() {
+    return this.logLevels.indexOf(this.sharedLogLevel.current);
+  }
+  /**
+   * Resets the current log level to the initial level during runtime.
+   */
+  resetLogLevel() {
+    this.sharedLogLevel.current = this.sharedLogLevel.initial;
+  }
+  /**
+   * Checks if the input log level is equal to the current log level of the PlaywrightReportLogger instance.
+   */
+  isCurrentLogLevel(level) {
+    return this.sharedLogLevel.current === level;
+  }
+  /**
+   * 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);
+    if (logLevelIndex < this.getCurrentLogLevelIndex()) {
+      return false;
+    }
+    return true;
+  }
+  /**
+   * 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());
+    for (const log of this.sharedLogEntry) {
+      const printTime = log.timestamp.toLocaleTimeString("nb-NO", {
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit"
+      });
+      const printDate = log.timestamp.toLocaleDateString("nb-NO", {
+        day: "2-digit",
+        month: "2-digit",
+        year: "numeric"
+      });
+      const printLogLevel = `${log.logLevel.toUpperCase()}`;
+      const printPrefix = log.prefix ? `: [${log.prefix}]` : "";
+      let messageBody = "";
+      let messageContentType = "";
+      try {
+        const parsedMessage = JSON.parse(log.message);
+        messageContentType = "application/json";
+        messageBody = JSON.stringify(parsedMessage, null, 2);
+      } catch (error) {
+        messageContentType = "text/plain";
+        messageBody = log.message;
+      }
+      testInfo.attach(`${printTime} ${printDate} - ${printLogLevel} ${printPrefix}`, {
+        contentType: messageContentType,
+        body: Buffer.from(messageBody)
+      });
+    }
   }
 };
 
 // src/fixture/base.fixtures.ts
-var import_test5 = require("@playwright/test");
-var test3 = import_test5.test.extend({
+var test3 = import_test4.test.extend({
   // biome-ignore lint/correctness/noEmptyPattern: <Playwright does not support the use of _, thus we must provide an empty object {}>
   log: async ({}, use, testInfo) => {
     const contextName = "TestCase";