pomwright 1.1.1 → 1.3.0

package/dist/index.mjs

@@ -63,6 +63,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
 };
@@ -235,52 +241,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();
@@ -305,8 +331,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);
@@ -320,8 +363,8 @@ 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)) {
@@ -340,18 +383,24 @@ 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) {
+    if (locatorSchemaPath.length === 0 || locatorSchemaPath.startsWith(".") || locatorSchemaPath.endsWith(".") || locatorSchemaPath.includes("..")) {
+      throw new Error(
+        `[${this.pageObjectClass.pocName}] Invalid LocatorSchemaPath '${locatorSchemaPath}'. LocatorSchemaPath must not be empty, start or end with a '.', or contain consecutive '.'.`
+      );
+    }
     const newLocatorSchema = this.createLocatorSchema(schemaDetails, locatorSchemaPath);
     const existingSchemaFunc = this.safeGetLocatorSchema(locatorSchemaPath);
     if (existingSchemaFunc) {
@@ -365,16 +414,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(".");
@@ -388,8 +437,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 = {
@@ -401,7 +450,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",
@@ -410,7 +459,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)) {
@@ -435,7 +488,6 @@ Attempted to Add Schema: ${JSON.stringify(newLocatorSchema, null, 2)}`
         } else {
           merged[key] = this.deepMerge(
             {},
-            // Updated type here
             sourceValue,
             schema[key]
           );
@@ -456,18 +508,17 @@ 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 = {}) => {
+  buildNestedLocator = async (locatorSchemaPath, schemasMap, filterMap, indices = {}) => {
     return await 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) {
@@ -475,32 +526,42 @@ Attempted to Add Schema: ${JSON.stringify(newLocatorSchema, null, 2)}`
         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) {
@@ -524,7 +585,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;
@@ -532,7 +593,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) {
@@ -544,7 +607,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
@@ -552,8 +615,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(
@@ -564,6 +627,126 @@ 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
 import { test as test2 } from "@playwright/test";
@@ -598,7 +781,7 @@ var SessionStorage = class {
           const item = sessionStorage.getItem(key);
           try {
             storage[key] = item ? JSON.parse(item) : null;
-          } catch (e) {
+          } catch (_e) {
             storage[key] = item;
           }
         }
@@ -648,7 +831,7 @@ var SessionStorage = class {
       contextExists = await this.page.evaluate(() => {
         return typeof window !== "undefined" && window.sessionStorage !== void 0;
       });
-    } catch (e) {
+    } catch (_e) {
       contextExists = false;
     }
     if (contextExists) {
@@ -679,7 +862,7 @@ var SessionStorage = class {
       const allData = await this.readFromSessionStorage();
       if (keys && keys.length > 0) {
         for (const key of keys) {
-          if (Object.prototype.hasOwnProperty.call(allData, key)) {
+          if (Object.hasOwn(allData, key)) {
             result[key] = allData[key];
           }
         }
@@ -746,12 +929,10 @@ var BasePage = 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;
@@ -759,8 +940,14 @@ var BasePage = 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 = selectors;
@@ -769,7 +956,11 @@ var BasePage = class {
     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) {
@@ -777,8 +968,13 @@ var BasePage = class {
       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, "\\$&");
+    const escapeStringForRegExp = (str) => str.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
     if (typeof baseUrl === "string" && typeof urlPath === "string") {
       return `${baseUrl}${urlPath}`;
     }
@@ -794,64 +990,67 @@ var BasePage = 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
@@ -861,10 +1060,19 @@ var BasePage = 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);
   }
 };
 
@@ -1000,7 +1208,7 @@ ${args.join("\n\n")}`
         const parsedMessage = JSON.parse(log.message);
         messageContentType = "application/json";
         messageBody = JSON.stringify(parsedMessage, null, 2);
-      } catch (error) {
+      } catch (_error) {
         messageContentType = "text/plain";
         messageBody = log.message;
       }