pomwright 0.0.8 → 1.0.0

package/dist/index.d.mts

@@ -136,11 +136,6 @@ type LogEntry = {
  * 20:49:51 05.05.2023 - ERROR : [TestCase -> MobilEier -> Axe]
  * 20:49:52 05.05.2023 - INFO : [TestCase -> MobilEier]
  * 20:49:52 05.05.2023 - DEBUG : [TestCase -> MobilEier -> GetBy]
- *
- * @property {LogLevel} sharedLogLevel - The current shared log level and its initial level.
- * @property {LogEntry[]} sharedLogEntry - Array of log entries.
- * @property {string} contextName - The contextual name of the logger instance, e.g. the name of the class it was initialized in.
- * @property {logLevel[]} logLevels - Valid log levels
  */
 declare class PlaywrightReportLogger {
     private sharedLogLevel;
@@ -152,88 +147,58 @@ declare class PlaywrightReportLogger {
         initial: LogLevel;
     }, sharedLogEntry: LogEntry[], contextName: string);
     /**
-     * Creates a new logger instance with a new contextual name which includes a reference to the parent logger.
+     * Creates a child logger with a new contextual name, sharing the same log level and log entries with the parent logger.
      *
      * The root loggers log "level" is referenced by all child loggers and their child loggers and so on...
      * Changing the log "level" of one, will change it for all.
-     *
-     * @param prefix - The prefix to add to the new logger instance.
-     * @returns - A new logger instance with the updated prefix.
      */
     getNewChildLogger(prefix: string): PlaywrightReportLogger;
     /**
-     * Logs a message with the specified log level, prefix, and arguments.
-     * The message will only be recorded if the current log level allows it.
-     *
-     * @param level - The log level for the message.
-     * @param message - The log message.
-     * @param args - Additional arguments to log.
+     * Logs a message with the specified log level, prefix, and additional arguments if the current log level permits.
      */
     private log;
     /**
      * Logs a debug-level message with the specified message and arguments.
-     *
-     * @param message - The log message.
-     * @param args - Additional arguments to log.
      */
     debug(message: string, ...args: any[]): void;
     /**
      * Logs a info-level message with the specified message and arguments.
-     *
-     * @param message - The log message.
-     * @param args - Additional arguments to log.
      */
     info(message: string, ...args: any[]): void;
     /**
      * Logs a warn-level message with the specified message and arguments.
-     *
-     * @param message - The log message.
-     * @param args - Additional arguments to log.
      */
     warn(message: string, ...args: any[]): void;
     /**
      * Logs a error-level message with the specified message and arguments.
-     *
-     * @param message - The log message.
-     * @param args - Additional arguments to log.
      */
     error(message: string, ...args: any[]): void;
     /**
-     * Set logLevel during runtime.
-     *
-     * @param level - The logLevel ("debug" | "info" | "warn" | "error").
+     * Sets the current log level to the specified level during runTime.
      */
     setLogLevel(level: LogLevel): void;
     /**
-     * Returns the current logLevel during runtime.
-     *
-     * @returns LogLevel ("debug" | "info" | "warn" | "error")
+     * Retrieves the current log level during runtime.
      */
     getCurrentLogLevel(): LogLevel;
     /**
-     * Returns the index of the current logLevel during runtime.
+     * Retrieves the index of the current log level in the logLevels array during runtime.
      */
     getCurrentLogLevelIndex(): number;
     /**
-     * Sets logLevel back to the initial logLevel during runtime.
+     * Resets the current log level to the initial level during runtime.
      */
     resetLogLevel(): void;
     /**
-     * isCurrentLogLevel is a method that checks if the input log level is equal to the current log level of the PlaywrightReportLogger instance.
-     * @param level The log level to check if it is equal to the current log level.
-     * @returns A boolean indicating whether the input log level is equal to the current log level.
+     * Checks if the input log level is equal to the current log level of the PlaywrightReportLogger instance.
      */
     isCurrentLogLevel(level: LogLevel): boolean;
     /**
-     * isLogLevelEnabled returns 'true' if the "level" parameter provided has an equal or greater index than the current logLevel.
-     * @param level
-     * @returns
+     * Returns 'true' if the "level" parameter provided has an equal or greater index than the current logLevel.
      */
     isLogLevelEnabled(level: LogLevel): boolean;
     /**
-     * Attaches the recorded logs to the Playwright HTML report.
-     *
-     * @param testInfo - The test information object from Playwright.
+     * Attaches the recorded log entries to the Playwright HTML report in a sorted and formatted manner.
      */
     attachLogsToTest(testInfo: TestInfo): void;
 }
@@ -261,17 +226,10 @@ type LocatorSchemaWithMethods = LocatorSchema & WithUpdateMethod & WithUpdatesMe
 interface ModifiedLocatorSchema extends UpdatableLocatorSchemaProperties {
 }
 /**
- * GetLocatorBase
- *
- * The GetLocatorBase class is designed to provide the core functionality for dynamically generating
- * nested locators based on a defined structure. By nesting locators we narrow what we can resolve
- * to, providing a higher degree of certainty that the element(s) resolved to are correct and in
- * the expected location. These nested locators are used in Playwright tests to interact with elements
- * in a more contextual manner.
- *
- * @class
- * @public
- *
+ * 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.
  */
 declare class GetLocatorBase<LocatorSchemaPathType extends string> {
     protected pageObjectClass: BasePage<LocatorSchemaPathType>;
@@ -279,47 +237,76 @@ declare class GetLocatorBase<LocatorSchemaPathType extends string> {
     private getBy;
     private locatorSchemas;
     /**
-     * Constructor for the GetLocatorBaseClass.
-     *
-     * @param {BasePage} pageObjectClass - The page object class to which the locator pertains.
-     * @param {PlaywrightReportLogger} log - The PlaywrightReportLogger child of the page object class.
+     * Initializes the GetLocatorBase class with a page object class and a logger.
      */
     constructor(pageObjectClass: BasePage<LocatorSchemaPathType>, log: PlaywrightReportLogger);
     /**
-     * test
-     * @param locatorSchemaPath
-     * @returns
+     * 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.
+     */
     private collectDeepCopies;
+    /**
+     * 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.
+     */
     private applyUpdate;
+    /**
+     * 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.
+     */
     private applyUpdates;
+    /**
+     * 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.
+     */
     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(locatorSchemaPath: LocatorSchemaPathType, schemaDetails: ModifiedLocatorSchema): 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.
+     */
     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.
+     */
     private extractPathsFromSchema;
     /**
      * 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.
      */
     private logError;
+    /** Merges 'source' into 'target', combining their properties into a new isolated object. */
     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.
+     */
     protected buildNestedLocator: (locatorSchemaPath: LocatorSchemaPathType, schemasMap: Map<string, LocatorSchema>, indices?: Record<number, number>) => Promise<Locator>;
+    /**
+     * Evaluates the current locator, capturing details about its resolution status and the elements it resolves to.
+     */
     private evaluateCurrentLocator;
     /**
-     * Evaluates the Playwright locator, checking if it resolves to any elements, and retrieves element attributes.
-     *
-     * @param pwLocator - The Playwright locator to evaluate.
-     * @returns - A promise that resolves to an object containing the Playwright locator and an array of element attributes for each element located, or null if no elements are found.
+     * Retrieves and compiles attributes of elements resolved by a Playwright locator per nesting step.
+     * This method provides insights into the elements targeted by the locator, aiding in debugging and verification.
      */
     private evaluateAndGetAttributes;
 }
 
 /**
- * The SessionStorage class provides methods for setting and getting session storage data in Playwright.
- *
- * @class
- * @property {Page} page - The Playwright page object.
+ * Defines the SessionStorage class to manage session storage in Playwright.
+ * It provides methods to set, get, and clear session storage data, and to handle data before page navigation.
  */
 declare class SessionStorage {
     private page;
@@ -327,64 +314,50 @@ declare class SessionStorage {
     private queuedStates;
     private isInitiated;
     constructor(page: Page, pocName: string);
-    /**
-     * Writes states to the sessionStorage. Private utility function.
-     *
-     * @param states An object representing the states (key/value pairs) to set.
-     */
+    /** Writes states to session storage. Accepts an object with key-value pairs representing the states. */
     private writeToSessionStorage;
-    /**
-     * Reads all states from the sessionStorage. Private utility function.
-     *
-     * @returns An object containing all states from the sessionStorage.
-     */
+    /** Reads all states from session storage and returns them as an object. */
     private readFromSessionStorage;
     /**
-     * Sets the specified states in the sessionStorage.
+     * Sets the specified states in session storage.
+     * Optionally reloads the page after setting the data to ensure the new session storage state is active.
      *
-     * @param states An object representing the states (key/value pairs) to set in sessionStorage.
-     * @param reload If true, reloads the page after setting the sessionStorage data.
-     *
-     * Usage:
-     * await set({ user: 'John Doe', token: 'abc123' }, true);
+     * Parameters:
+     * states: Object representing the states to set in session storage.
+     * reload: Boolean indicating whether to reload the page after setting the session storage data.
      */
     set(states: {
         [key: string]: any;
     }, reload: boolean): Promise<void>;
     /**
      * Queues states to be set in the sessionStorage before the next navigation occurs.
-     * This handles multiple scenarios:
+     * Handles different scenarios based on whether the context exists or multiple calls are made.
      *
      * 1. No Context, Single Call: Queues and sets states upon the next navigation.
      * 2. No Context, Multiple Calls: Merges states from multiple calls and sets them upon the next navigation.
      * 3. With Context: Directly sets states in sessionStorage if the context already exists.
      *
-     * @param states An object representing the states (key/value pairs) to set.
-     *
-     * Usage:
-     * await setOnNextNavigation({ key: 'value' });
+     * Parameters:
+     * states: Object representing the states to queue for setting in session storage.
      */
     setOnNextNavigation(states: {
         [key: string]: any;
     }): Promise<void>;
     /**
-     * Fetches all or selected states from sessionStorage.
+     * Fetches states from session storage.
+     * If specific keys are provided, fetches only those states; otherwise, fetches all states.
      *
-     * @param keys Optional array of keys to fetch from sessionStorage.
-     * @returns An object containing the fetched states.
+     * Parameters:
+     * keys: Optional array of keys to specify which states to fetch from session storage.
      *
-     * Usage:
-     * 1. To fetch all states: await get();
-     * 2. To fetch selected states: await get(['key1', 'key2']);
+     * Returns:
+     * Object containing the fetched states.
      */
     get(keys?: string[]): Promise<{
         [key: string]: any;
     }>;
     /**
      * Clears all states in sessionStorage.
-     *
-     * Usage:
-     * await clear();
      */
     clear(): Promise<void>;
 }
@@ -411,29 +384,24 @@ declare abstract class BasePage<LocatorSchemaPathType extends string> {
     protected locators: GetLocatorBase<LocatorSchemaPathType>;
     constructor(page: Page, testInfo: TestInfo, baseUrl: string, urlPath: string, pocName: string, pwrl: PlaywrightReportLogger);
     /**
-     * Asynchronously retrieves a nested locator based on the provided LocatorSchemaPath and optional indices per nested locator.
-     * Useful for interacting with elements in a structured or hierarchical manner, reducing the number of possible elements we can resolve to.
-     *
-     * The update and updates methods cannot be used with this method. Use the getLocatorSchema method instead.
-     *
-     * @param LocatorSchemaPathType locatorSchemaPath - The unique path identifier for the locator schema.
-     * @param indices - An optional object to specify the nth occurrence of each nested locator.
-     * @returns Promise<Locator> - A promise that resolves to the nested locator.
+     * getNestedLocator(indices?: { [key: number]: number | null } | null)
+     * - Asynchronously retrieves a nested locator based on the LocatorSchemaPath provided by getLocatorSchema("...")
+     * - Can be chained after the update and updates methods, getNestedLocator will end the chain.
+     * - The optional parameter of the method takes an object with 0-based indices "{0: 0, 3: 1}" for one or more locators
+     * to be nested given by sub-paths (indices correspond to last "word" of a sub-path).
+     * - Returns a promise that resolves to the nested locator.
      */
     getNestedLocator: (locatorSchemaPath: LocatorSchemaPathType, indices?: {
         [key: number]: number | null;
     } | null | undefined) => Promise<Locator>;
     /**
-     * Asynchronously retrieves the locator based on the current LocatorSchemaPath. This method does not perform nesting.
-     * Useful for directly interacting with an element based on its LocatorSchema.
-     *
-     * The update and updates methods cannot be used with this method. Use the getLocatorSchema method instead.
-     *
-     * @param LocatorSchemaPathType locatorSchemaPath - The unique path identifier for the locator schema.
-     * @returns Promise<Locator> - A promise that resolves to the nested locator.
+     * getLocator()
+     * - Asynchronously retrieves a locator based on the current LocatorSchema. This method does not perform nesting,
+     * and will return the locator for which the full LocatorSchemaPath resolves to, provided by getLocatorSchema("...")
+     * - Can be chained after the update and updates methods, getLocator will end the chain.
+     * - Returns a promise that resolves to the locator.
      */
     getLocator: (locatorSchemaPath: LocatorSchemaPathType) => Promise<Locator>;
-    protected abstract pageActionsToPerformAfterNavigation(): (() => Promise<void>)[];
     /**
      * Abstract method to initialize locator schemas.
      *
@@ -515,36 +483,63 @@ declare abstract class BasePage<LocatorSchemaPathType extends string> {
      */
     protected abstract initLocatorSchemas(): void;
     /**
-     * The "getLocatorSchema" method is used to retrieve a deep copy of a locator schema defined in the GetLocatorBase class.
-     * It enriches the returned schema with additional methods to handle updates and retrieval of deep copy locators.
-     *
-     * @param LocatorSchemaPathType locatorSchemaPath - The unique path identifier for the locator schema.
-     * @returns LocatorSchemaWithMethods - A deep copy of the locator schema with additional methods.
-     *
-     * Methods added to the returned LocatorSchemaWithMethods object:
-     *
-     * - update(updates: Partial<UpdatableLocatorSchemaProperties>):
-     *      Allows updating properties of the locator schema.
-     *      This method is used for modifying the current schema without affecting the original schema.
-     *      @param updates - An object with properties to be updated in the locator schema, omits the locatorSchemaPath parameter.
-     *      @returns LocatorSchemaWithMethods - The updated locator schema object.
-     *
-     * - updates(indexedUpdates: { [index: number]: Partial<UpdatableLocatorSchemaProperties> | null }):
-     *      Similar to update, but allows for indexed updates of any locator to be nested within the path.
-     *      This method is used for modifying the current schema without affecting the original schema
-     *      @param indexedUpdates - An object where keys represent index levels, and values are the updates at each level.
-     *      @returns LocatorSchemaWithMethods - The locator schema object with indexed updates.
-     *
-     * - getNestedLocator(indices?: { [key: number]: number | null }):
-     *      Asynchronously retrieves a nested locator based on the current schema and optional indices per nested locator.
-     *      Useful for interacting with elements in a structured or hierarchical manner.
-     *      @param indices - An optional object to specify the nth occurrence of each nested locator.
-     *      @returns Promise<Locator> - A promise that resolves to the nested locator.
-     *
-     * - getLocator():
-     *      Asynchronously retrieves the locator based on the current schema. This method does not consider nesting.
-     *      Useful for directly interacting with an element based on its schema.
-     *      @returns Promise<Locator> - A promise that resolves to the locator.
+     * 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.
+     *
+     * Providing a precise and powerful solution for interacting with elements through locators in a structured
+     * or hierarchical manner:
+     * - Effortless validation of any element's expected location in the DOM.
+     * - Improved readability and maintainability of tests.
+     * - Improved readability and maintainability of Page Object Classes (POCs), through the use of a single source of
+     * truth and flat locator (LocatorSchema) structure.
+     * - Improved rebustness of tests in the face of DOM changes.
+     * - Simpler debugging and maintenance as a result of limitin/scoping the number of possible resolvable elements
+     * - Highly veratile usage
+     *
+     * getLocatorSchema adds the following chainable methods to the returned LocatorSchemaWithMethods object:
+     *
+     * update(updates: Partial< UpdatableLocatorSchemaProperties >)
+     * - 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;
 }
@@ -562,4 +557,4 @@ declare class BaseApi {
     constructor(baseUrl: string, apiName: string, context: APIRequestContext, pwrl: PlaywrightReportLogger);
 }
 
-export { type AriaRoleType, GetByMethod, type LocatorSchema, BasePage as POMWright, BaseApi as POMWrightApi, GetLocatorBase as POMWrightGetLocatorBase, PlaywrightReportLogger as POMWrightLogger, test as POMWrightTestFixture };
+export { type AriaRoleType, BaseApi, BasePage, GetByMethod, GetLocatorBase, type LocatorSchema, PlaywrightReportLogger, test };