pomwright 0.0.3

package/dist/index.d.mts

@@ -0,0 +1,567 @@
+import * as _playwright_test from '@playwright/test';
+import { Page, Locator, TestInfo, Selectors, APIRequestContext } from '@playwright/test';
+
+type AriaRoleType = Parameters<Page["getByRole"]>[0];
+/**
+ * ENUM representing methods from the "GetBy" helper class, used by the "GetLocatorBase" class when building nested locators
+ */
+declare enum GetByMethod {
+    role = "role",
+    text = "text",
+    label = "label",
+    placeholder = "placeholder",
+    altText = "altText",
+    title = "title",
+    locator = "locator",
+    frameLocator = "frameLocator",
+    testId = "testId",
+    dataCy = "dataCy",
+    id = "id"
+}
+/**
+ * An interface representing a locator object, which can be used with Playwright or other automation tools to create a reusable and maintainable "library" of Locator objects.
+ *
+ * To make tests resilient, prioritize user-facing attributes and explicit contracts such as role locators (ARIA).
+ *
+ * @interface
+ */
+interface LocatorSchema {
+    /** The ARIA role of the element, this is the prefered way to locate and interact with elements, as it is the closest way to how users and assistive technology perceive the page. {@link AriaRole} */
+    role?: AriaRoleType;
+    /** The options for the role property.*/
+    roleOptions?: {
+        /** Whether the element is checked, an attribute usually set by aria-checked or native 'input type=checkbox' controls. */
+        checked?: boolean;
+        /** Whether the element is disabled, an attribute usually set by aria-disabled or disabled. */
+        disabled?: boolean;
+        /** Whether name is matched exactly. Playwright: case-sensitive and whole-string, still trims whitespace. Ignored when locating by a regular expression.*/
+        exact?: boolean;
+        /** Whether the element is expanded, an attribute usually set by aria-expanded. */
+        expanded?: boolean;
+        /** Whether to include/match hidden elements. */
+        includeHidden?: boolean;
+        /** The level of the element in the accessibility hierarchy, a number attribute that is usually present for roles heading, listitem, row, treeitem, with default values for h1-h6 elements. */
+        level?: number;
+        /** Option to match the accessible name. Playwright: By default, matching is case-insensitive and searches for a substring, use exact to control this behavior. */
+        name?: string | RegExp;
+        /** Whether the element is pressed, an attribute usually set by aria-pressed. */
+        pressed?: boolean;
+        /** Whether the element is selected, an attribute usually set by aria-selected. */
+        selected?: boolean;
+    };
+    /** The text content of the element, allows locating elements that contain given text. */
+    text?: string | RegExp;
+    /** The options for the text property. */
+    textOptions?: {
+        /** Whether to match the text content exactly. Playwright: case-sensitive and whole-string, still trims whitespace. Ignored when locating by a regular expression.*/
+        exact?: boolean;
+    };
+    /** Text to locate the element 'for', allows locating input elements by the text of the associated label. */
+    label?: string | RegExp;
+    /** The options for the label property. */
+    labelOptions?: {
+        /** Whether to match the text content of the associated label exactly. Playwright: case-sensitive and whole-string, still trims whitespace. Ignored when locating by a regular expression.*/
+        exact?: boolean;
+    };
+    /** The text content of a placeholder element, allows locating input elements by the placeholder text. */
+    placeholder?: string | RegExp;
+    /** The options for the placeholder property. */
+    placeholderOptions?: {
+        /** Whether to match the placeholder text content exactly. Playwright: case-sensitive and whole-string, still trims whitespace. Ignored when locating by a regular expression.*/
+        exact?: boolean;
+    };
+    /** The 'alt' text of the element, allows locating elements by their alt text. */
+    altText?: string | RegExp;
+    /** The options for the altText property. */
+    altTextOptions?: {
+        /** Whether to match the 'alt' text content exactly. Playwright: case-sensitive and whole-string, still trims whitespace. Ignored when locating by a regular expression.*/
+        exact?: boolean;
+    };
+    /** The title of the element, allows locating elements by their title attribute. */
+    title?: string | RegExp;
+    /** The options for the altText property. */
+    titleOptions?: {
+        /** Whether to match the 'title' attribute exactly. Playwright: case-sensitive and whole-string, still trims whitespace. Ignored when locating by a regular expression.*/
+        exact?: boolean;
+    };
+    /** A Playwright Locator, typically used through Playwright's "page.locator()" method */
+    locator?: string | Locator;
+    /** The options for the locator property */
+    locatorOptions?: {
+        has?: Locator;
+        hasNot?: Locator;
+        hasNotText?: string | RegExp;
+        hasText?: string | RegExp;
+    };
+    /** A Playwright FrameLocator, represents a view to an iframe on the page, e.g.: "page.frameLocator('#my-frame')" */
+    frameLocator?: string;
+    /** The test ID of the element. Playwright default: "data-testid", can be changed by configuring playwright.config.ts. 'testId' string format: "id-value" */
+    testId?: string | RegExp;
+    /** FOR BACKWARDS COMPATIBILITY ONLY! A custom Selector Engine is implemented in 'base.page.ts' to support the ICE Web-Teams Cypress test ID. 'dataCy' string format: "data-cy=id-value"" */
+    dataCy?: string;
+    /** The ID of the element. 'id' string format: "value", or a regex expression of the value */
+    id?: 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. */
+    locatorSchemaPath: string;
+}
+
+type LogLevel = "debug" | "info" | "warn" | "error";
+type LogEntry = {
+    timestamp: Date;
+    logLevel: LogLevel;
+    prefix: string;
+    message: string;
+};
+/**
+ * PlaywrightReportLogger is a logger implementation designed for Playwright tests.
+ * It records log messages and attaches them to the Playwright HTML report.
+ *
+ * The logger enables all fixtures implementing it to share the same log level
+ * within the scope of a single test, independant of other tests run in parallell.
+ * In the same way each fixture will share a single logEntry for recording all log
+ * statements produced throughout the tests execution, when the test is done, all log
+ * entries are chronologically sorted and attached to the playwright HTML report.
+ *
+ * Log messages can be recorded with various log levels (debug, info, warn, error).
+ *
+ * The getNewChildLogger method allows you to create a new 'child' logger instance
+ * with a new contextual name (e.g. the class it's used), while sharing the logLevel
+ * and LogEntry with the 'parent'.
+ *
+ * @example
+ * 20:49:50 05.05.2023 - DEBUG : [TestCase]
+ * 20:49:50 05.05.2023 - DEBUG : [TestCase -> MobilEier]
+ * 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;
+    private sharedLogEntry;
+    private readonly contextName;
+    private readonly logLevels;
+    constructor(sharedLogLevel: {
+        current: LogLevel;
+        initial: LogLevel;
+    }, sharedLogEntry: LogEntry[], contextName: string);
+    /**
+     * Creates a new logger instance with a new contextual name which includes a reference to 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.
+     */
+    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").
+     */
+    setLogLevel(level: LogLevel): void;
+    /**
+     * Returns the current logLevel during runtime.
+     *
+     * @returns LogLevel ("debug" | "info" | "warn" | "error")
+     */
+    getCurrentLogLevel(): LogLevel;
+    /**
+     * Returns the index of the current logLevel during runtime.
+     */
+    getCurrentLogLevelIndex(): number;
+    /**
+     * Sets logLevel back to the initial logLevel 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.
+     */
+    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
+     */
+    isLogLevelEnabled(level: LogLevel): boolean;
+    /**
+     * Attaches the recorded logs to the Playwright HTML report.
+     *
+     * @param testInfo - The test information object from Playwright.
+     */
+    attachLogsToTest(testInfo: TestInfo): void;
+}
+
+type UpdatableLocatorSchemaProperties = Omit<LocatorSchema, "locatorSchemaPath">;
+interface WithUpdateMethod {
+    update(updates: Partial<UpdatableLocatorSchemaProperties>): LocatorSchemaWithMethods;
+}
+interface WithUpdatesMethod {
+    updates(indexedUpdates: {
+        [index: number]: Partial<UpdatableLocatorSchemaProperties> | null;
+    }): LocatorSchemaWithMethods;
+}
+interface WithGetNestedLocatorMethod {
+    getNestedLocator(indices?: {
+        [key: number]: number | null;
+    } | null): Promise<Locator>;
+}
+interface WithGetLocatorMethod {
+    getLocator(): Promise<Locator>;
+}
+type LocatorSchemaWithMethods = LocatorSchema & WithUpdateMethod & WithUpdatesMethod & WithGetNestedLocatorMethod & WithGetLocatorMethod & {
+    schemasMap: Map<string, LocatorSchema>;
+};
+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
+ *
+ */
+declare class GetLocatorBase<LocatorSchemaPathType extends string> {
+    protected pageObjectClass: BasePage<LocatorSchemaPathType>;
+    protected log: PlaywrightReportLogger;
+    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.
+     */
+    constructor(pageObjectClass: BasePage<LocatorSchemaPathType>, log: PlaywrightReportLogger);
+    /**
+     * test
+     * @param locatorSchemaPath
+     * @returns
+     */
+    getLocatorSchema(locatorSchemaPath: LocatorSchemaPathType): LocatorSchemaWithMethods;
+    private collectDeepCopies;
+    private applyUpdate;
+    private applyUpdates;
+    private createLocatorSchema;
+    addSchema(locatorSchemaPath: LocatorSchemaPathType, schemaDetails: ModifiedLocatorSchema): void;
+    private safeGetLocatorSchema;
+    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;
+    private deepMerge;
+    protected buildNestedLocator: (locatorSchemaPath: LocatorSchemaPathType, indices: {
+        [key: number]: number | null;
+    } | undefined, schemasMap: Map<string, LocatorSchema>) => Promise<Locator>;
+    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.
+     */
+    private evaluateAndGetAttributes;
+}
+
+/**
+ * The SessionStorage class provides methods for setting and getting session storage data in Playwright.
+ *
+ * @class
+ * @property {Page} page - The Playwright page object.
+ */
+declare class SessionStorage {
+    private page;
+    private pocName;
+    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.
+     */
+    private writeToSessionStorage;
+    /**
+     * Reads all states from the sessionStorage. Private utility function.
+     *
+     * @returns An object containing all states from the sessionStorage.
+     */
+    private readFromSessionStorage;
+    /**
+     * Sets the specified states in the sessionStorage.
+     *
+     * @param states An object representing the states (key/value pairs) to set in sessionStorage.
+     * @param reload If true, reloads the page after setting the sessionStorage data.
+     *
+     * Usage:
+     * await set({ user: 'John Doe', token: 'abc123' }, true);
+     */
+    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:
+     *
+     * 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' });
+     */
+    setOnNextNavigation(states: {
+        [key: string]: any;
+    }): Promise<void>;
+    /**
+     * Fetches all or selected states from sessionStorage.
+     *
+     * @param keys Optional array of keys to fetch from sessionStorage.
+     * @returns An object containing the fetched states.
+     *
+     * Usage:
+     * 1. To fetch all states: await get();
+     * 2. To fetch selected states: await get(['key1', 'key2']);
+     */
+    get(keys?: string[]): Promise<{
+        [key: string]: any;
+    }>;
+    /**
+     * Clears all states in sessionStorage.
+     *
+     * Usage:
+     * await clear();
+     */
+    clear(): Promise<void>;
+}
+
+/** The BasePage class, extended by all Page Object Classes */
+declare abstract class BasePage<LocatorSchemaPathType extends string> {
+    /** Provides Playwright page methods */
+    page: Page;
+    /** Playwright TestInfo contains information about currently running test, available to any test function */
+    testInfo: TestInfo;
+    /** Selectors can be used to install custom selector engines.*/
+    selector: Selectors;
+    /** The base URL of the Page Object Class */
+    baseUrl: string;
+    /** The URL path of the Page Object Class */
+    urlPath: string;
+    fullUrl: string;
+    /** The name of the Page Object Class */
+    pocName: string;
+    /** The Page Object Class' PlaywrightReportLogger instance, prefixed with its name. Log levels: debug, info, warn, and error.  */
+    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: 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: (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: (locatorSchemaPath: LocatorSchemaPathType) => Promise<Locator>;
+    protected abstract pageActionsToPerformAfterNavigation(): (() => Promise<void>)[];
+    /**
+     * Abstract method to initialize locator schemas.
+     *
+     * Each Page Object Class (POC) extending BasePage should define its own
+     * LocatorSchemaPathType, 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".
+     *
+     * Implement this method in derived classes to populate the locator map.
+     * You can define locator schemas directly within this method or import them
+     * from a separate file (recommended for larger sets of schemas).
+     *
+     * @example
+     * // Example of defining LocatorSchemaPathType in a POC:
+     *
+     * export type LocatorSchemaPath =
+     *   | "main.heading"
+     *   | "main.button.addItem";
+     *
+     * // Example implementation using direct definitions:
+     *
+     * initLocatorSchemas() {
+     *   this.addSchema("main.heading", {
+     *     role: "heading",
+     *     roleOptions: {
+     *       name: "Main Heading"
+     *     },
+     *     locatorMethod: GetBy.role
+     *   });
+     *
+     *   this.addSchema("main.button.addItem", {
+     *     role: "button",
+     *     roleOptions: {
+     *       name: "Add item"
+     *     },
+     *     testId: "add-item-button",
+     *     locatorMethod: GetBy.role
+     *   });
+     *
+     *   // Add more schemas as needed
+     * }
+     *
+     * // Example implementation using a separate file:
+     * // Create a file named 'pocName.locatorSchema.ts' and define a function
+     * // that populates the locator schemas, for example:
+     *
+     * // In pocName.locatorSchema.ts
+     * export type LocatorSchemaPath =
+     *   | "main.heading"
+     *   | "main.button.addItem";
+     *
+     * export function initLocatorSchemas(locators: GetLocatorBase<LocatorSchemaPath>) {
+     *   locators.addSchema("main.heading", {
+     *     role: "heading",
+     *     roleOptions: {
+     *       name: "Main Heading"
+     *     },
+     *     locatorMethod: GetBy.role
+     *   });
+     *
+     *   locators.addSchema("main.button.addItem", {
+     *     role: "button",
+     *     roleOptions: {
+     *       name: "Add item"
+     *     },
+     *     testId: "add-item-button",
+     *     locatorMethod: GetBy.role
+     *   });
+     *
+     *   // Add more schemas as needed
+     * }
+     *
+     * // In the derived POC class
+     * import { initLocatorSchemas, LocatorSchemaPath } from "./pocName.locatorSchema";
+     *
+     * initLocatorSchemas() {
+     *     initPocNameLocatorSchemas(this.locators);
+     * }
+     */
+    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.
+     */
+    getLocatorSchema(locatorSchemaPath: LocatorSchemaPathType): LocatorSchemaWithMethods;
+}
+
+type baseFixtures = {
+    log: PlaywrightReportLogger;
+};
+declare const test: _playwright_test.TestType<_playwright_test.PlaywrightTestArgs & _playwright_test.PlaywrightTestOptions & baseFixtures, _playwright_test.PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions>;
+
+declare class BaseApi {
+    protected baseUrl: string;
+    apiName: string;
+    protected log: PlaywrightReportLogger;
+    protected request: APIRequestContext;
+    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 };