pomwright 1.1.1 → 1.3.0

package/dist/index.d.mts

@@ -101,6 +101,13 @@ interface LocatorSchema {
     dataCy?: string;
     /** The ID of the element. 'id' string format: "value", or a regex expression of the value */
     id?: string | RegExp;
+    /** The equivalent of the Playwright locator.filter() method */
+    filter?: {
+        has?: Locator;
+        hasNot?: Locator;
+        hasNotText?: string | RegExp;
+        hasText?: string | RegExp;
+    };
     /** Defines the preferred Playwright locator method to be used on this LocatorSchema Object */
     locatorMethod: GetByMethod;
     /** The human-readable name of the defined locator object, used for debug logging and test report enrichment. */
@@ -203,104 +210,422 @@ declare class PlaywrightReportLogger {
     attachLogsToTest(testInfo: TestInfo): void;
 }
 
-type UpdatableLocatorSchemaProperties = Omit<LocatorSchema, "locatorSchemaPath">;
-interface WithUpdateMethod {
-    update(updates: Partial<UpdatableLocatorSchemaProperties>): LocatorSchemaWithMethods;
+/**
+ * The GetBy class encapsulates methods for generating and obtaining Playwright Locators using LocatorSchema.
+ * It maps locator methods to corresponding Playwright page functions and provides a convenient interface to interact
+ * with these locators. It holds a reference to a Playwright Page object and a PlaywrightReportLogger for logging.
+ * The constructor initializes the logger and sets up method mappings for locator creation.
+ */
+declare class GetBy {
+    private page;
+    private log;
+    private methodMap;
+    private subMethodMap;
+    constructor(page: Page, pwrl: PlaywrightReportLogger);
+    /**
+     * 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: LocatorSchema) => Locator;
+    /**
+     * 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.
+     */
+    private getBy;
+    /**
+     * 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.
+     */
+    private createByMethod;
+    private role;
+    private text;
+    private label;
+    private placeholder;
+    private altText;
+    private title;
+    private locator;
+    /**
+     * Returns a FrameLocator using the 'frameLocator' selector from a LocatorSchema.
+     * Throws an error if the frameLocator is not defined.
+     */
+    private frameLocator;
+    /**
+     * Returns a Locator using the 'testId' selector from a LocatorSchema.
+     * Throws an error if the testId is not defined.
+     */
+    private testId;
+    /**
+     * Returns a Locator using the 'dataCy' selector from a LocatorSchema.
+     * Throws an error if the dataCy is undefined.
+     */
+    private dataCy;
+    /**
+     * 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.
+     */
+    private id;
 }
-interface WithUpdatesMethod {
+
+/**
+ * A FilterEntry describes filtering criteria passed to .filter() calls on Playwright locators.
+ * has, hasNot: Locator | undefined - Used to filter elements that contain or exclude a certain element.
+ * hasText, hasNotText: string | RegExp | undefined - Used to filter elements based on text content.
+ */
+type FilterEntry = {
+    has?: Locator;
+    hasNot?: Locator;
+    hasNotText?: string | RegExp;
+    hasText?: string | RegExp;
+};
+/**
+ * ExtractSubPaths splits a path on '.' and returns a union of progressively longer sub-paths.
+ * For example: ExtractSubPaths<"body.section@playground.button@reset"> produces:
+ * "body" | "body.section@playground" | "body.section@playground.button@reset"
+ */
+type ExtractSubPaths<Path extends string> = Path extends `${infer Head}.${infer Tail}` ? Head | `${Head}.${ExtractSubPaths<Tail>}` : Path;
+/**
+ * SubPaths computes valid sub-paths for a given chosen substring (LocatorSubstring).
+ * If LocatorSubstring is a string:
+ * We return only sub-paths that belong to the chosen substring. For example, if
+ * LocatorSubstring = "body.section@playground.button@reset"
+ * SubPaths returns only "body", "body.section@playground", and "body.section@playground.button@reset"
+ * from the entire union of LocatorSchemaPathType, if they exist.
+ */
+type SubPaths<LocatorSchemaPathType extends string, LocatorSubstring extends LocatorSchemaPathType | undefined> = LocatorSubstring extends string ? Extract<LocatorSchemaPathType, LocatorSubstring | ExtractSubPaths<LocatorSubstring>> : never;
+/**
+ * UpdatableLocatorSchemaProperties represent the properties of LocatorSchema that can be changed by update/updates,
+ * excluding the locatorSchemaPath itself, which remains immutable.
+ */
+type LocatorSchemaWithoutPath = Omit<LocatorSchema, "locatorSchemaPath">;
+/** PathIndexPairs links each sub-part of a path to an optional index used in getNestedLocator calls. */
+type PathIndexPairs = {
+    path: string;
+    index?: number;
+}[];
+/**
+ * Ensures LocatorSchemaPath strings are non-empty, do not start/end with dots, and avoid consecutive dots.
+ */
+type LocatorSchemaPathValid<Path extends string> = Path extends "" ? never : Path extends `.${string}` | `${string}.` ? never : Path extends `${string}..${string}` ? never : Path;
+/**
+ * LocatorSchemaWithMethods is the type returned by getLocatorSchema. It merges LocatorSchema with chainable methods:
+ * - update: Modify any properties of any LocatorSchema in the chain that make up the LocatorSchemaPath. Can be chained multiple times, applies updates in the order chained.
+ * - addFilter: Add additonal filters to any LocatorSchema in the chain that make up the LocatorSchemaPath. Can be chained multiple times, applies updates in the order chained.
+ * - getNestedLocator: Obtain a fully resolved nested locator. Can be chained once after update and addFilter methods if used, ends the chain and returns the nested locator.
+ * - getLocator: Obtain the direct locator of the LocatorSchema the full LocatorSchemaPath resolves to. Can be chained once after update and addFilter methods if used, ends the chain and returns the nested locator.
+ *
+ * schemasMap and filterMap store the deep-copied schemas and associated filters, ensuring immutability and isolation from originals.
+ */
+type LocatorSchemaWithMethods<LocatorSchemaPathType extends string, LocatorSubstring extends LocatorSchemaPathType | undefined> = LocatorSchema & {
+    /**
+     * Contains deepCopies of all the LocatorSchema which make up the full LocatorSchemaPath
+     *
+     * Not inteded to be directly iteracted with, though you can if needed (debug).
+     * Use the chainable methods available on the .getLocatorSchema(LocatorSchemaPath) method instead.
+     */
+    schemasMap: Map<string, LocatorSchema>;
+    /**
+     * Contains deepCopies of all the LocatorSchema which make up the full LocatorSchemaPath
+     *
+     * Not inteded to be directly iteracted with, though you can if needed (debug).
+     * Use the chainable methods available on the .getLocatorSchema(LocatorSchemaPath) method instead.
+     */
+    filterMap: Map<string, FilterEntry[]>;
+    /**
+     * Allows updating any schema in the chain by specifying the subPath and a partial LocatorSchemaWithoutPath.
+     * - 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.
+     *
+     * @example
+     * // Direct usage:
+     * const submitButton = await poc.getLocatorSchema("main.form.button@submit").update("main.form.button@submit")
+     */
+    update(subPath: SubPaths<LocatorSchemaPathType, LocatorSubstring>, updates: Partial<LocatorSchemaWithoutPath>): LocatorSchemaWithMethods<LocatorSchemaPathType, LocatorSubstring>;
+    /**
+     * @deprecated To be removed in version 2.0.0. Use the new `.update(subPath, updates)` method instead, see example.
+     *
+     * This deprecated update method takes one argument and only updates the LocatorSchema which the full LocatorSchemaPath resolves to.
+     *
+     * @example
+     * // New update method usage:
+     * const userInfoSection = await poc
+     * 	.getLocatorSchema("main.form.section")
+     * 	.update("main.form.section", { locatorOptions: { hasText: "User Info:" } })
+     * 	.getNestedLocator();
+     */
+    update(updates: Partial<LocatorSchemaWithoutPath>): LocatorSchemaWithMethods<LocatorSchemaPathType, LocatorSubstring>;
+    /**
+     * @deprecated To be removed in version 2.0.0. Use the new `.update(subPath, updates)` method instead, chain the
+     * method for each update if multiple, see example.
+     *
+     * This deprecated updates method uses indices to identify which schema to update.
+     *
+     * @example
+     * // New update method usage:
+     * const userInfoSection = await poc
+     * 	.getLocatorSchema("main.form.section")
+     * 	.update("main.form", {
+     * 		role: "form",
+     * 		roleOptions: { name: "Personalia" },
+     * 		locatorMethod: GetByMethod.role,
+     * 	})
+     * 	.update("main.form.section", { locatorOptions: { hasText: /User Info:/i } })
+     * 	.getNestedLocator();
+     */
     updates(indexedUpdates: {
-        [index: number]: Partial<UpdatableLocatorSchemaProperties> | null;
-    }): LocatorSchemaWithMethods;
-}
-interface WithGetNestedLocatorMethod {
+        [index: number]: Partial<LocatorSchemaWithoutPath> | null;
+    }): LocatorSchemaWithMethods<LocatorSchemaPathType, LocatorSubstring>;
+    /**
+     * The equivalent of the Playwright locator.filter({...}) method and chainable on .getLocatorSchema(LocatorSchemaPath).
+     * Can be chained multiple times to add multiple filters to the same or different LocatorSchema.
+     *
+     * **See examples further down for usage.**
+     *
+     * A filter will search for a particular string/RegExp/Locator somewhere inside the element, possibly in a descendant element,
+     * case-insensitively (string).
+     *
+     * The filterData object can contain the following properties:
+     * - has: Locator - Filters elements that contain a certain element.
+     * - hasNot: Locator - Filters elements that do not contain a certain element.
+     * - hasText: string | RegExp - Filters elements based on text content.
+     * - hasNotText: string | RegExp - Filters elements that do not contain a certain text content.
+     *
+     * If you define multiple filterData properties in a single addFilter call instead of multiple addFilter calls, they
+     * will be chained after each other(playwright decides the order). If you want to add multiple filters of the same
+     * type, you must chain multiple addFilter calls.
+     *
+     * @example
+     * // Adding a filter to the last LocatorSchema in the chain:
+     * const userInfoSection = await poc
+     * 	.getLocatorSchema("main.form.section")
+     * 	.addFilter("main.form.section", { hasText: "User Info:" })
+     * 	.getNestedLocator();
+     *
+     * // Adding multiple filter to the last LocatorSchema in the chain:
+     * const userInfoSection = await poc
+     * 	.getLocatorSchema("main.form.section")
+     * 	.addFilter("main.form.section", { hasText: "User Info:" })
+     * 	.addFilter("main.form.section", { hasText: `First Name: ${user.firstName}` })
+     * 	.getNestedLocator();
+     *
+     * // Adding filters to multiple LocatorSchema in the chain:
+     * const submitButton = await poc.getLocator("main.form.button@submit");
+     *
+     * const userInfoSection = await poc
+     * 	.getLocatorSchema("main.form.section")
+     * 	.addFilter("main.form", { has: submitButton })
+     * 	.addFilter("main.form.section", { hasText: "User Info:" })
+     * 	.getNestedLocator();
+     */
+    addFilter(subPath: SubPaths<LocatorSchemaPathType, LocatorSubstring>, filterData: FilterEntry): LocatorSchemaWithMethods<LocatorSchemaPathType, LocatorSubstring>;
+    /**
+     * Asynchronously builds a nested locator based on the LocatorSchemaPath provided by getLocatorSchema("...")
+     *
+     * Builds a nested locator from all LocatorSchema that make up the full LocatorSchemaPath given by
+     * .getLocatorSchema(LocatorSchemaPath). Optionally, you can provide a list of subPaths and indices to have one or more
+     * LocatorSchema that make up the full LocatorSchemaPath each resolved to a specific .nth(n) occurrence of the element(s).
+     *
+     * - 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.
+     *
+     * Test retry: POMWright will set the log level to debug during retries of tests. This will trigger getNestedLocator
+     * to resolve the locator in DOM per nesting step and attach the log results to the HTML report for debugging purposes.
+     * This enables us to easily see which locator in the chain failed to resolve, making it easier to identify an issue
+     * or which LocatorSchema needs to be updated.
+     *
+     * Debug: Using POMWright's "log" fixture, you can set the log level to "debug" to see the nested locator evaluation
+     * results when a test isn't running retry.
+     *
+     * @example
+     * // Usage:
+     * const submitButton = await poc.getLocatorSchema("main.form.button@submit").getNestedLocator();
+     * await submitButton.click();
+     *
+     * // With indexing:
+     * for (const [index, subscription] of subscriptions.entries()) {
+     *   const inputUsername = await poc
+     *     .getLocatorSchema("main.form.item.input@username")
+     *     .getNestedLocator({ "main.form.item": index });
+     *   await inputUsername.fill(subscription.username);
+     *   await inputUsername.blur();
+     *
+     *   const enableServiceCheckbox = await poc
+     *     .getLocatorSchema("main.form.item.checkbox@enableService")
+     *     .getNestedLocator({ "main.form.item": index });
+     *   await enableServiceCheckbox.check();
+     * }
+     *
+     * // indexing multiple subPaths:
+     * const something = await poc
+     *   .getLocatorSchema("main.form.item.something")
+     *   .getNestedLocator({
+     *     "main.form": 0, // locator.first() / locator.nth(0)
+     *     "main.form.item": 1, // locator.nth(1)
+     *   });
+     * await something.click();
+     */
+    getNestedLocator(subPathIndices?: {
+        [K in SubPaths<LocatorSchemaPathType, LocatorSubstring>]?: number | null;
+    }): Promise<Locator>;
+    /**
+     * @deprecated To be removed in version 2.0.0. Use getNestedLocator({ LocatorSchemaPath: index }) instead of
+     * number-based indexing, see example.
+     *
+     * @example
+     * // New usage:
+     * for (const [index, subscription] of subscriptions.entries()) {
+     *   const inputUsername = await poc
+     *     .getLocatorSchema("main.form.item.input@username")
+     *     .getNestedLocator({ "main.form.item": index });
+     *   await inputUsername.fill(subscription.username);
+     *   await inputUsername.blur();
+     *
+     *   const enableServiceCheckbox = await poc
+     *     .getLocatorSchema("main.form.item.checkbox@enableService")
+     *     .getNestedLocator({ "main.form.item": index });
+     *   await enableServiceCheckbox.check();
+     * }
+     *
+     * // indexing multiple subPaths:
+     * const something = await poc
+     *   .getLocatorSchema("main.form.item.something")
+     *   .getNestedLocator({
+     *     "main.form": 0, // locator.first() / locator.nth(0)
+     *     "main.form.item": 1, // locator.nth(1)
+     *   });
+     * await something.click();
+     */
     getNestedLocator(indices?: {
         [key: number]: number | null;
-    } | null): Promise<Locator>;
-}
-interface WithGetLocatorMethod {
+    }): Promise<Locator>;
+    /**
+     * 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.
+     *
+     * @example
+     * // Usage:
+     * const submitButton = await poc.getLocatorSchema("main.form.button@submit").getLocator();
+     * await expect(submitButton, "should only exist one submit button").toHaveCount(1);
+     */
     getLocator(): Promise<Locator>;
-}
-type LocatorSchemaWithMethods = LocatorSchema & WithUpdateMethod & WithUpdatesMethod & WithGetNestedLocatorMethod & WithGetLocatorMethod & {
-    schemasMap: Map<string, LocatorSchema>;
 };
-interface ModifiedLocatorSchema extends UpdatableLocatorSchemaProperties {
-}
 /**
- * Provides core functionality for dynamically generating nested locators.
- * Nested locators help pinpoint elements with higher precision in Playwright tests.
- * The class includes methods for adding, updating, and retrieving locator schemas,
- * and for building nested locators based on these schemas.
+ * GetLocatorBase:
+ * The foundational class for managing and constructing nested locators based on LocatorSchemas.
+ *
+ * Key points:
+ * - Generics: <LocatorSchemaPathType, LocatorSubstring>
+ *   LocatorSchemaPathType is a union of all possible locator paths.
+ *   LocatorSubstring is either undefined or narrowed to a chosen path.
+ *
+ * - getLocatorSchema(path):
+ *   Returns a deep-copied schema and a chainable object (LocatorSchemaWithMethods) that
+ *   allows calling update, updates, addFilter, and finally getNestedLocator or getLocator.
+ *
+ * - By using WithMethodsClass, we lock LocatorSubstring = P, the chosen path,
+ *   ensuring addFilter suggests only valid sub-paths of P.
+ *
+ * - applyUpdate / applyUpdates and deepMerge:
+ *   Handle schema modifications without affecting the original definitions.
+ *
+ * - buildNestedLocator:
+ *   Assembles nested Playwright locators step-by-step according to the path.
  */
-declare class GetLocatorBase<LocatorSchemaPathType extends string> {
-    protected pageObjectClass: BasePage<LocatorSchemaPathType, BasePageOptions>;
+declare class GetLocatorBase<LocatorSchemaPathType extends string, LocatorSubstring extends LocatorSchemaPathType | undefined = undefined> {
+    protected pageObjectClass: BasePage<LocatorSchemaPathType, BasePageOptions, LocatorSubstring>;
     protected log: PlaywrightReportLogger;
-    private getBy;
+    protected locatorSubstring?: LocatorSubstring | undefined;
+    getBy: GetBy;
     private locatorSchemas;
+    constructor(pageObjectClass: BasePage<LocatorSchemaPathType, BasePageOptions, LocatorSubstring>, log: PlaywrightReportLogger, locatorSubstring?: LocatorSubstring | undefined);
     /**
-     * Initializes the GetLocatorBase class with a page object class and a logger.
+     * 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.
      */
-    constructor(pageObjectClass: BasePage<LocatorSchemaPathType, BasePageOptions>, log: PlaywrightReportLogger);
+    getLocatorSchema<P extends LocatorSchemaPathType>(locatorSchemaPath: P): LocatorSchemaWithMethods<LocatorSchemaPathType, P>;
     /**
-     * Retrieves a locator schema with additional methods for manipulation and retrieval of locators.
-     */
-    getLocatorSchema(locatorSchemaPath: LocatorSchemaPathType): LocatorSchemaWithMethods;
-    /**
-     * 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.
      */
     private collectDeepCopies;
     private isLocatorSchemaWithMethods;
     /**
-     * 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: Map<string, LocatorSchema>, subPath: LocatorSchemaPathType, updates: Partial<LocatorSchemaWithoutPath>): void;
+    /**
+     * applyUpdate:
+     * Applies updates to a single schema within the schemasMap.
      */
-    private applyUpdate;
+    applyUpdate(schemasMap: Map<string, LocatorSchema>, locatorSchemaPath: LocatorSchemaPathType, updateData: Partial<LocatorSchema>): void;
     /**
-     * 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.
      */
-    private applyUpdates;
+    applyUpdates(schemasMap: Map<string, LocatorSchema>, pathIndexPairs: PathIndexPairs, updatesData: {
+        [index: number]: Partial<LocatorSchema>;
+    }): void;
     /**
-     * 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.
      */
     private createLocatorSchema;
     /**
-     * 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: LocatorSchemaPathType, schemaDetails: ModifiedLocatorSchema): void;
+    addSchema(locatorSchemaPath: LocatorSchemaPathType & LocatorSchemaPathValid<LocatorSchemaPathType>, schemaDetails: LocatorSchemaWithoutPath): void;
     /**
-     * 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.
      */
     private safeGetLocatorSchema;
     /**
-     * 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.
      */
-    private extractPathsFromSchema;
+    extractPathsFromSchema: (paths: string, indices?: Record<number, number>) => PathIndexPairs;
     /**
-     * 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.
      */
     private logError;
-    /** 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.
+     */
     private deepMerge;
     /**
-     * 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.
      */
-    protected buildNestedLocator: (locatorSchemaPath: LocatorSchemaPathType, schemasMap: Map<string, LocatorSchema>, indices?: Record<number, number>) => Promise<Locator>;
+    buildNestedLocator: (locatorSchemaPath: LocatorSchemaPathType, schemasMap: Map<string, LocatorSchema>, filterMap: Map<string, FilterEntry[]>, indices?: Record<number, number>) => Promise<Locator>;
     /**
-     * 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.
      */
     private evaluateCurrentLocator;
     /**
-     * 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.
      */
     private evaluateAndGetAttributes;
 }
@@ -363,6 +688,10 @@ declare class SessionStorage {
     clear(): Promise<void>;
 }
 
+/**
+ * BasePageOptions can define optional patterns for baseUrl and urlPath.
+ * Defaults assume they are strings if not specified.
+ */
 type BasePageOptions = {
     urlOptions?: {
         baseUrlType?: string | RegExp;
@@ -380,13 +709,29 @@ type ExtractFullUrlType<T extends BasePageOptions> = T["urlOptions"] extends {
 } | {
     urlPathType: RegExp;
 } ? RegExp : string;
-/** The BasePage class, extended by all Page Object Classes */
+/**
+ * BasePage:
+ * The foundational class for all Page Object Classes.
+ *
+ * Generics:
+ * - LocatorSchemaPathType: A union of valid locator paths.
+ * - Options: Configuration type for URLs.
+ * - LocatorSubstring: The chosen substring locator.
+ *
+ * We instantiate GetLocatorBase with these generics. When calling getLocatorSchema,
+ * the chosen path P sets LocatorSubstring = P, ensuring methods like addFilter only suggests valid sub-paths.
+ *
+ * BasePage provides:
+ * - Common properties: page, testInfo, selectors, URLs, logging, sessionStorage.
+ * - getNestedLocator & getLocator methods that delegate to getLocatorSchema.
+ * - Abstract initLocatorSchemas method to be implemented by concrete POCs.
+ */
 declare abstract class BasePage<LocatorSchemaPathType extends string, Options extends BasePageOptions = {
     urlOptions: {
         baseUrlType: string;
         urlPathType: string;
     };
-}> {
+}, LocatorSubstring extends LocatorSchemaPathType | undefined = undefined> {
     /** Provides Playwright page methods */
     page: Page;
     /** Playwright TestInfo contains information about currently running test, available to any test function */
@@ -397,6 +742,7 @@ declare abstract class BasePage<LocatorSchemaPathType extends string, Options ex
     baseUrl: ExtractBaseUrlType<Options>;
     /** The URL path of the Page Object Class */
     urlPath: ExtractUrlPathType<Options>;
+    /** The full URL of the Page Object Class */
     fullUrl: ExtractFullUrlType<Options>;
     /** The name of the Page Object Class */
     pocName: string;
@@ -404,33 +750,137 @@ declare abstract class BasePage<LocatorSchemaPathType extends string, Options ex
     protected log: PlaywrightReportLogger;
     /** The SessionStorage class provides methods for setting and getting session storage data in Playwright.*/
     sessionStorage: SessionStorage;
-    protected locators: GetLocatorBase<LocatorSchemaPathType>;
-    constructor(page: Page, testInfo: TestInfo, baseUrl: ExtractBaseUrlType<Options>, urlPath: ExtractUrlPathType<Options>, pocName: string, pwrl: PlaywrightReportLogger);
+    /**
+     * 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.
+     */
+    protected locators: GetLocatorBase<LocatorSchemaPathType, LocatorSubstring>;
+    constructor(page: Page, testInfo: TestInfo, baseUrl: ExtractBaseUrlType<Options>, urlPath: ExtractUrlPathType<Options>, pocName: string, pwrl: PlaywrightReportLogger, locatorSubstring?: LocatorSubstring);
+    /**
+     * constructFullUrl:
+     * Combines baseUrl and urlPath, handling both strings and RegExps.
+     * Ensures a flexible approach to URL matching (string or regex-based).
+     */
     private constructFullUrl;
     /**
-     * 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.
+     * Short-hand wrapper method for calling .getLocatorSchema(LocatorSchemaPath).getNestedLocator(subPathIndices?)
+     *
+     * Asynchronously builds a nested locator from all LocatorSchema that make up the full LocatorSchemaPath. Optionally,
+     * you can provide a list of subPaths and indices to have one or more LocatorSchema that make up the full
+     * LocatorSchemaPath each resolved to a specific .nth(n) occurrence of the element(s).
+     *
+     * Note: This short-hand wrapper method is useful for quickly building nested locators without having to call
+     * getLocatorSchema("...") first. On the other hand, it can't be used to update or add filters to the LocatorSchema.
+     *
+     * Test retry: POMWright will set the log level to debug during retries of tests. This will trigger getNestedLocator
+     * to resolve the locator in DOM per nesting step and attach the log results to the HTML report for debugging purposes.
+     * This enables us to easily see which locator in the chain failed to resolve, making it easier to identify an issue
+     * or which LocatorSchema needs to be updated.
+     *
+     * Debug: Using POMWright's "log" fixture, you can set the log level to "debug" to see the nested locator evaluation
+     * results when a test isn't running retry.
+     *
+     * @example
+     * // Usage:
+     * const submitButton = await poc.getNestedLocator("main.form.button@submit");
+     * await submitButton.click();
+     *
+     * // With indexing:
+     * const something = await poc.getNestedLocator("main.form.item.something", {
+     *     "main.form": 0, // locator.first() / locator.nth(0)
+     *     "main.form.item": 1, // locator.nth(1)
+     *   });
+     * await something.click();
      */
-    getNestedLocator: (locatorSchemaPath: LocatorSchemaPathType, indices?: {
+    getNestedLocator<P extends LocatorSchemaPathType>(locatorSchemaPath: P, subPathIndices?: {
+        [K in SubPaths<LocatorSchemaPathType, P>]?: number | null;
+    }): Promise<Locator>;
+    /**
+     * @deprecated Use { SubPaths: index } instead of {4:2}, i.e. subPath-based keys instead of indices, see example.
+     *
+     * Deprecated short-hand wrapper method for calling .getLocatorSchema(LocatorSchemaPath).getNestedLocator(subPathIndices?)
+     *
+     * @example
+     * // New Usage:
+     * const something = await poc.getNestedLocator("main.form.item.something", {
+     *     "main.form": 0, // locator.first() / locator.nth(0)
+     *     "main.form.item": 1, // locator.nth(1)
+     *   });
+     * await something.click();
+     */
+    getNestedLocator(locatorSchemaPath: LocatorSchemaPathType, indices?: {
         [key: number]: number | null;
-    } | null) => Promise<Locator>;
+    } | null): Promise<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.
+     * 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: (locatorSchemaPath: LocatorSchemaPathType) => Promise<Locator>;
     /**
-     * Abstract method to initialize locator schemas.
+     * 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
+     * - 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.
+     *
+     * 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
+     * - 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 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
+     * 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, or by implementing a helper method on your Page Object Class.
+     */
+    getLocatorSchema<P extends LocatorSchemaPathType>(path: P): LocatorSchemaWithMethods<LocatorSchemaPathType, P>;
+    /**
+     * initLocatorSchemas:
+     * Abstract method to be implemented by each POC.
+     * POCs define their own type LocatorSchemaPath and add their schemas using locators.addSchema(...).
      *
      * Each Page Object Class (POC) extending BasePage should define its own
-     * LocatorSchemaPathType, which is a string type using dot (".") notation.
+     * LocatorSchemaPath type, which is a string type using dot (".") notation.
      * The format should start and end with a word, and words should be separated by dots.
      * For example: "section.subsection.element".
      *
@@ -506,56 +956,6 @@ declare abstract class BasePage<LocatorSchemaPathType extends string, Options ex
      * }
      */
     protected abstract initLocatorSchemas(): void;
-    /**
-     * 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.
-     *
-     * 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 } | 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 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: LocatorSchemaPathType): LocatorSchemaWithMethods;
 }
 
 type baseFixtures = {
@@ -571,4 +971,4 @@ declare class BaseApi {
     constructor(baseUrl: string, apiName: string, context: APIRequestContext, pwrl: PlaywrightReportLogger);
 }
 
-export { type AriaRoleType, BaseApi, BasePage, type BasePageOptions, type ExtractBaseUrlType, type ExtractFullUrlType, type ExtractUrlPathType, GetByMethod, GetLocatorBase, type LocatorSchema, PlaywrightReportLogger, test };
+export { type AriaRoleType, BaseApi, BasePage, type BasePageOptions, type ExtractBaseUrlType, type ExtractFullUrlType, type ExtractUrlPathType, GetByMethod, GetLocatorBase, type LocatorSchema, type LocatorSchemaWithoutPath, PlaywrightReportLogger, test };