@anddone/coretestautomation 1.0.1

package/src/utils/commonUtils.ts

@@ -0,0 +1,1544 @@
+import type { Locator } from '@playwright/test';
+
+export type ActionOptions = {
+  timeout?: number;
+  description?: string;
+  lastButtonLocator?: string;
+  activePageLocator?: string;
+  nextButtonLocator?: string;
+  prevButtonLocator?: string;
+  firstButtonLocator?: string;
+  pageButtonLocator?: string;
+};
+
+export class CommonUtils {
+  private static isHighlight = false;
+
+  private static resolveOptions(options?: ActionOptions) {
+    return {
+      timeout: options?.timeout ?? 15000,
+      description: options?.description ?? 'Element',
+    };
+  }
+  /**
+  * Highlights a UI element on the page for debugging and visual validation.
+  */
+  public static async highlight(locator: Locator) {
+    if (!this.isHighlight) return;
+    try {
+      await locator.highlight();
+    } catch {
+      console.warn('⚠ highlight skipped: page/locator not ready');
+    }
+  }
+
+  /**
+  * Waits for a Playwright locator to become visible on the page.
+  *
+  * @param locator - Playwright Locator to wait for
+  * @param options - Optional configuration object
+  * @param options.timeout - Maximum wait time in milliseconds (default: 15000)
+  * @param options.description - Logical name of the element for logging purposes
+  *
+  * @example
+  * await CommonUtils.waitForVisible(loginButton);
+  *
+  * @example
+  * await CommonUtils.waitForVisible(loginButton, {timeout: 5000,description: 'Login Button'});
+  */
+  static async waitForVisible(locator: Locator, options: ActionOptions = {}
+  ): Promise<void> {
+    const { timeout, description } = this.resolveOptions(options);
+    try {
+      await locator.waitFor({ state: 'visible', timeout });
+    } catch {
+      console.error(`❌ ${description} not visible after ${timeout}ms`);
+    }
+  }
+
+  /**
+ * Waits for a Playwright locator to become hidden or removed from the DOM.
+ *
+ * @param locator - Playwright Locator to wait for
+ * @param options - Optional configuration object
+ * @param options.timeout - Maximum wait time in milliseconds (default: 15000)
+ * @param options.description - Logical name of the element for logging purposes
+ *
+ * @example
+ * await CommonUtils.waitForInvisible(loginButton);
+ *
+ * @example
+ * await CommonUtils.waitForInvisible(loginButton, {timeout: 5000,description: 'Login Button'});
+ */
+  static async waitForInvisible(locator: Locator, options: ActionOptions = {}
+  ): Promise<void> {
+    const { timeout, description } = this.resolveOptions(options);
+    try {
+      await locator.waitFor({ state: 'hidden', timeout });
+    } catch {
+      console.error(`❌ ${description} Element still visible after ${timeout}ms`);
+    }
+  }
+
+  /**
+ * Pauses execution for a specified number of seconds.
+ *
+ * @param seconds - Number of seconds to wait
+ *
+ * @example
+ * await CommonUtils.waitSeconds(3);
+ *
+ * @returns Promise<void>
+ */
+  static async waitSeconds(seconds: number): Promise<void> {
+    try {
+      await new Promise(resolve => setTimeout(resolve, seconds * 1000));
+    } catch (error) {
+      console.warn(`⚠ Error during wait:`, (error as Error).message);
+    }
+  }
+
+  /**
+   * Clicks on a web element after waiting for it to become visible.
+   * 
+   * If the element is not found or the click fails, the error is logged
+   * 
+   * @param locator - Playwright Locator to be clicked
+   * @param options - Optional configuration object
+   * @param options.timeout - Maximum wait time for visibility and click (default: 15000 ms)
+   * @param options.description - Logical name of the element for logging purposes
+   *
+   * @example
+   * await CommonUtils.click(loginButton);
+   *
+   * @example
+   * await CommonUtils.click(loginButton, {timeout: 5000,description: 'Login Button'});
+   */
+  static async click(locator: Locator, options: ActionOptions = {}
+  ): Promise<void> {
+    const { timeout, description } = this.resolveOptions(options);
+    try {
+      await this.waitForVisible(locator, options);
+      await this.highlight(locator);
+      await locator.click({ timeout });
+    } catch (error) {
+      console.warn(`⚠ Click skipped on ${description}: ${(error as Error).message}`);
+    }
+  }
+
+  /**
+ * Fills text into an input field after ensuring it is visible.
+ *
+ * @param locator - Playwright Locator of the input element
+ * @param text - Text value to be entered into the field
+ * @param options - Optional configuration object
+ * @param options.timeout - Maximum wait time for visibility (default: 15000 ms)
+ * @param options.description - Logical name of the element for logging purposes
+ *
+ * @example
+ * await CommonUtils.fill(usernameInput, 'admin');
+ *
+ * @example
+ * await CommonUtils.fill(usernameInput, 'admin', {timeout: 5000,description: 'Username Input'
+ * });
+ */
+  static async fill(locator: Locator, text: string, options: ActionOptions = {}
+  ): Promise<void> {
+    const { timeout, description } = this.resolveOptions(options);
+    try {
+      await this.waitForVisible(locator, options);
+      await this.highlight(locator);
+      await locator.fill(text, { timeout });
+    } catch (error) {
+      console.warn(
+        `⚠ Fill skipped on ${description}. Reason: ${(error as Error).message}`
+      );
+    }
+  }
+
+  /**
+   * Types text into an input or editable element using keyboard events.
+   *
+   * @param locator - Playwright Locator of the input or editable element
+   * @param text - Text to be typed into the element
+   * @param options - Optional configuration object
+   * @param options.timeout - Maximum wait time for visibility (default: 15000 ms)
+   * @param options.description - Logical name of the element for logging purposes
+   *
+   * @example
+   * await CommonUtils.typeText(usernameInput, 'admin');
+   *
+   * @example
+   * await CommonUtils.typeText(passwordInput, 'password123', {
+   *   timeout: 5000,
+   *   description: 'Password Input'
+   * });
+   */
+  static async typeText(locator: Locator, text: string, options: ActionOptions = {}
+  ): Promise<void> {
+    const { timeout, description } = this.resolveOptions(options);
+    try {
+      await this.waitForVisible(locator, options);
+      await this.highlight(locator);
+      await locator.type(text, { delay: 50, timeout });
+    } catch (error) {
+      console.warn(
+        `⚠ Type skipped on ${description}. Reason: ${(error as Error).message}`
+      );
+    }
+  }
+
+  /**
+ * Checks whether a locator is visible within the given timeout.
+ *
+ * @param locator - Locator of the element to check
+ * @param options - Optional configuration (timeout in ms, description)
+ * @returns True if the element becomes visible, otherwise false
+ *
+ * @example
+ * const visible = await CommonUtils.isVisible(page.locator('#loginButton'));
+ * const visibleWithDesc = await CommonUtils.isVisible(page.locator('#loginButton'), {timeout:5000, description:'Login Button'});
+ */
+  static async isVisible(locator: Locator, options: ActionOptions = {}): Promise<boolean> {
+    const { timeout, description } = this.resolveOptions(options);
+    try {
+      await this.waitForVisible(locator, options);
+      await this.highlight(locator);
+      return await locator.isVisible();
+    } catch {
+      console.warn(`⚠ ${description} is not visible`);
+      return false;
+    }
+  }
+
+  /**
+   * Checks whether a locator is enabled (interactable).
+   *
+   * @param locator - Locator of the element to check
+   * @param options - Optional configuration (timeout in ms, description)
+   * @returns True if the element is enabled, otherwise false
+   *
+   * @example
+   * const enabled = await CommonUtils.isEnabled(page.locator('#submitButton'));
+   */
+  static async isEnabled(locator: Locator, options: ActionOptions = {}): Promise<boolean> {
+    const { timeout, description } = this.resolveOptions(options);
+    try {
+      await this.waitForVisible(locator, options);
+      await this.highlight(locator);
+      return await locator.isEnabled();
+    } catch {
+      console.warn(`⚠ ${description} is not enabled`);
+      return false;
+    }
+  }
+
+  /**
+   * Checks whether a locator is disabled.
+   *
+   * @param locator - Locator of the element to check
+   * @param options - Optional configuration (timeout in ms, description)
+   * @returns True if the element is disabled or not interactable, otherwise false
+   *
+   * @example
+   * const disabled = await CommonUtils.isDisabled(page.locator('#cancelButton'));
+   */
+  static async isDisabled(locator: Locator, options: ActionOptions = {}): Promise<boolean> {
+    const { timeout, description } = this.resolveOptions(options);
+    try {
+      await this.waitForVisible(locator, options);
+      await this.highlight(locator);
+      return await locator.isDisabled();
+    } catch {
+      console.warn(`⚠ ${description} is not disabled`);
+      return true;
+    }
+  }
+
+  /**
+   * Checks whether a locator is editable.
+   *
+   * @param locator - Locator of the element to check
+   * @param options - Optional configuration (timeout in ms, description)
+   * @returns True if the element is editable, otherwise false
+   *
+   * @example
+   * const editable = await CommonUtils.isEditable(page.locator('#nameInput'));
+   */
+  static async isEditable(locator: Locator, options: ActionOptions = {}): Promise<boolean> {
+    const { timeout, description } = this.resolveOptions(options);
+    try {
+      await this.waitForVisible(locator, options);
+      await this.highlight(locator);
+      return await locator.isEditable();
+    } catch {
+      console.warn(`⚠ ${description} is not editable`);
+      return false;
+    }
+  }
+
+  /**
+   * Checks whether a checkbox or radio button is checked.
+   *
+   * @param locator - Locator of the checkbox or radio element
+   * @param options - Optional configuration (timeout in ms, description)
+   * @returns True if the element is checked, otherwise false
+   *
+   * @example
+   * const checked = await CommonUtils.isChecked(page.locator('#acceptTerms'));
+   */
+  static async isChecked(locator: Locator, options: ActionOptions = {}): Promise<boolean> {
+    const { timeout, description } = this.resolveOptions(options);
+    try {
+      await this.waitForVisible(locator, options);
+      await this.highlight(locator);
+      return await locator.isChecked();
+    } catch {
+      console.warn(`⚠ ${description} is not checked`);
+      return false;
+    }
+  }
+
+  /**
+   * Checks whether a locator is hidden within the given timeout.
+   *
+   * @param locator - Locator of the element to check
+   * @param options - Optional configuration (timeout in ms, description)
+   * @returns True if the element is hidden or not visible, otherwise false
+   *
+   * @example
+   * const hidden = await CommonUtils.isHidden(page.locator('#loadingSpinner'));
+   */
+  static async isHidden(locator: Locator, options: ActionOptions = {}): Promise<boolean> {
+    const { description } = this.resolveOptions(options);
+    try {
+      await this.waitForInvisible(locator, options);
+      return true;
+    } catch {
+      console.warn(`⚠ ${description} is not hidden`);
+      return false;
+    }
+  }
+
+  /**
+   * Clears the value of an input or editable element.
+   *
+   * @param locator - Locator of the element to clear
+   * @param options - Optional configuration (timeout in ms, description)
+   *
+   * @example
+   * await CommonUtils.clear(page.locator('#searchInput'));
+   * await CommonUtils.clear(page.locator('#searchInput'), {timeout: 5000, description: 'Search Input'});
+   */
+  static async clear(locator: Locator, options: ActionOptions = {}): Promise<void> {
+    const { description } = this.resolveOptions(options);
+    try {
+      await this.waitForVisible(locator, options);
+      await this.highlight(locator);
+      await locator.clear();
+    } catch (error) {
+      console.warn(`⚠ Unable to clear ${description}: ${(error as Error).message}`);
+    }
+  }
+
+  /**
+ * Retrieves the value of a specified attribute from an element.
+ *
+ * @param locator - Locator of the element
+ * @param attributeName - Name of the attribute to retrieve
+ * @param options - Optional configuration (timeout in ms, description)
+ * @returns Attribute value or null if not found
+ */
+  static async getAttributeValue(locator: Locator, attributeName: string,
+    options: ActionOptions = {}): Promise<string | null> {
+    const { timeout, description } = this.resolveOptions(options);
+    try {
+      await locator.waitFor({ state: 'attached', timeout });
+      await this.highlight(locator);
+      return await locator.getAttribute(attributeName);
+    } catch (error) {
+      console.warn(
+        `⚠ Unable to get attribute "${attributeName}" from ${description}`,
+        (error as Error).message
+      );
+      return null;
+    }
+  }
+
+  /**
+ * Checks whether an element's attribute value contains the expected text.
+ *
+ * @param locator - Locator of the element
+ * @param attributeName - Attribute to inspect
+ * @param expectedValue - Text expected to be contained in the attribute
+ * @param options - Optional configuration (timeout in ms, description)
+ * @returns True if attribute contains the expected value
+ */
+  static async isAttributeValueContains(locator: Locator, attributeName: string,
+    expectedValue: string, options: ActionOptions = {}
+  ): Promise<boolean> {
+    const { timeout, description } = this.resolveOptions(options);
+    try {
+      await locator.waitFor({ state: 'attached', timeout });
+      await this.highlight(locator);
+
+      const attributeValue = await this.getAttributeValue(locator, attributeName,
+        options);
+
+      return attributeValue?.includes(expectedValue) ?? false;
+    } catch {
+      console.warn(
+        `⚠ Attribute "${attributeName}" of ${description} does not contain "${expectedValue}"`
+      );
+      return false;
+    }
+  }
+
+  /**
+   * Retrieves visible text from a Playwright locator.
+   *
+   * @param locator - Playwright Locator from which text is retrieved
+   * @param options - Optional configuration object
+   * @param options.timeout - Maximum wait time for visibility (default: 15000 ms)
+   * @param options.description - Logical name of the element for logging
+   *
+   * @returns The extracted text, or an empty string if unavailable
+   *
+   * @example
+   * const header = await CommonUtils.getText(pageHeader);
+   *
+   * @example
+   * const errorMsg = await CommonUtils.getText(errorLabel, {
+   *   timeout: 5000,
+   *   description: 'Error Message'
+   * });
+   */
+  static async getText(locator: Locator, options: ActionOptions = {}
+  ): Promise<string> {
+    const { description } = this.resolveOptions(options);
+    try {
+      await this.waitForVisible(locator, options);
+      await this.highlight(locator);
+      const text = await locator.innerText();
+      return text.trim();
+    } catch (error) {
+      console.warn(
+        `⚠ Unable to get text from ${description}. Reason: ${(error as Error).message}`
+      );
+      return '';
+    }
+  }
+
+
+  /**
+  * Retrieves the visible innerText of an element.
+  *
+  * @param locator - Locator of the target element
+  * @param options - Optional action settings
+  * @param options.timeout - Maximum time to wait for the element to become visible (default: 1500)
+  * @param options.description - Description of the element used for logging
+  *
+  * @example
+  * const text = await getInnerText(title);
+  *
+  * @example
+  * const text = await getInnerText(title, {description: 'Page title',timeout: 3000
+  * });
+  *
+  * @returns Trimmed innerText, or empty string if unavailable
+  */
+  static async getInnerText(locator: Locator, options: ActionOptions = {}
+  ): Promise<string> {
+    const { description } = this.resolveOptions(options);
+    try {
+      const target = locator.first();
+      this.waitForVisible(target, options);
+      await this.highlight(target);
+
+      return (await target.innerText()).trim();
+    } catch (error) {
+      console.warn(`⚠ Unable to get innerText from ${description}`,
+        (error as Error).message
+      );
+      return '';
+    }
+  }
+
+  /**
+ * Gets trimmed innerText values from a list of elements.
+ *
+ * @param locatorList - Locator representing multiple elements
+ * @param options - Optional action settings
+ * @param options.timeout - Maximum wait time for at least one element to become visible (default: 1500)
+ * @param options.description - Description of the element list used for logging
+ *
+ * @example
+ * const texts = await CommonUtils.getAllInnerText(listItems);
+ *
+ * @example
+ * const texts = await CommonUtils.getAllInnerText(listItems, {
+ *   description: 'Fruit list items',
+ *   timeout: 5000
+ * });
+ *
+ * @returns Array of trimmed innerText values, or empty array if none found
+ */
+  static async getAllInnerText(locatorList: Locator, options: ActionOptions = {}
+  ): Promise<string[]> {
+    const { description = 'Element list' } = options;
+    try {
+      const first = locatorList.first();
+      this.waitForVisible(first, options);
+      await this.highlight(first);
+
+      const texts = await locatorList.allInnerTexts();
+      return texts.map(t => t.trim());
+    } catch (error) {
+      console.warn(`⚠ Unable to get innerText values from ${description}:`, (error as Error).message);
+      return [];
+    }
+  }
+
+  /**
+   * Gets trimmed textContent values from a list of elements.
+   *
+   * @param locatorList - Locator representing multiple elements
+   * @param options - Optional action settings
+   * @param options.timeout - Maximum wait time for at least one element to be attached (default: 1500)
+   * @param options.description - Description of the element list used for logging
+   *
+   * @example
+   * const texts = await CommonUtils.getAllText(listItems);
+   *
+   * @example
+   * const texts = await CommonUtils.getAllText(listItems, {
+   *   description: 'Fruit list items',
+   *   timeout: 5000
+   * });
+   *
+   * @returns Array of trimmed textContent values, or empty array if none found
+   */
+  static async getAllText(locatorList: Locator, options: ActionOptions = {}
+  ): Promise<string[]> {
+    const { description = 'Element list' } = options;
+
+    try {
+      const first = locatorList.first();
+      this.waitForVisible(first, options);
+      await this.highlight(first);
+
+      const texts = await locatorList.allTextContents();
+      return texts.map(t => t.trim());
+    } catch (error) {
+      console.warn(`⚠ Unable to get textContent values from ${description}:`, (error as Error).message);
+      return [];
+    }
+  }
+
+  /**
+ * Fetches the trimmed text of a specific child tag inside a locator.
+ *
+ * @param locator - Locator of the parent element
+ * @param tagName - Tag name of the child element to fetch text from (e.g., 'span', 'p')
+ * @param options - Optional action settings
+ * @param options.timeout - Maximum time to wait for the element (default: 15000)
+ * @param options.description - Description of the element used for logging
+ *
+ * @example
+ * const spanText = await CommonUtils.getTextByTag(parentDiv, 'span');
+ *
+ * @example
+ * const spanText = await CommonUtils.getTextByTag(parentDiv, 'span', {
+ *   description: 'Amount label',
+ *   timeout: 5000
+ * });
+ *
+ * @returns Trimmed text of the child element, or empty string if not found
+ */
+  static async getTextByTag(locator: Locator, tagName: string,
+    options: ActionOptions = {}
+  ): Promise<string> {
+    const { timeout, description } = this.resolveOptions(options);
+
+    try {
+      await this.waitForVisible(locator, options);
+      await this.highlight(locator);
+
+      const child = locator.locator(tagName).first();
+      await child.waitFor({ state: 'visible', timeout });
+
+      const text = await child.innerText();
+      return text.trim();
+    } catch (error) {
+      console.warn(`⚠ Unable to get text from <${tagName}> of ${description}: ${(error as Error).message}`);
+      return '';
+    }
+  }
+
+  /**
+   * Finds the index of the first element whose innerText exactly matches the expected value.
+   *
+   * @param locatorList - Locator representing a list of elements
+   * @param expected - Exact text to match against each element's innerText
+   * @param options - Optional action settings
+   * @param options.timeout - Maximum time to wait for at least one element to become visible (default: 1500)
+   * @param options.description - Description of the element list used for logging
+   *
+   * @example
+   * const index = await getIndexOfExpected(listItems, 'Apple');
+   * 
+   * @example
+   * const index = await getIndexOfExpected(listItems,'Apple',
+   *   { description: 'Fruit list items', timeout: 5000 }
+   * );
+   *
+   * @returns Zero-based index of the matched element, or -1 if not found
+   */
+  static async getIndexOfExpected(locatorList: Locator, expected: string,
+    options: ActionOptions = {}
+  ): Promise<number> {
+
+    const { timeout, description } = this.resolveOptions(options);
+
+    try {
+      await locatorList.first().waitFor({ state: 'visible', timeout });
+
+      const count = await locatorList.count();
+
+      for (let i = 0; i < count; i++) {
+        const item = locatorList.nth(i);
+        await this.highlight(item);
+
+        const text = await this.getInnerText(item);
+        if (text === expected) return i;
+      }
+
+      console.warn(`⚠ "${expected}" not found in ${description}`);
+      return -1;
+    } catch (error) {
+      console.warn(
+        `⚠ Unable to get index for "${expected}" in ${description}`,
+        (error as Error).message
+      );
+      return -1;
+    }
+  }
+
+  /**
+ * Checks if an element's innerText exactly matches the expected text.
+ *
+ * @param locator - Locator of the target element
+ * @param expected - Expected text to match exactly against the element's innerText
+ * @param options - Optional action settings
+ * @param options.timeout - Maximum time to wait for the element to become visible (default: 1500)
+ * @param options.description - Description of the element used for logging
+ *
+ * @example
+ * const isMatch = await isElementTextMatchInnerText(title, 'Welcome');
+ *
+ * @example
+ * const isMatch = await isElementTextMatchInnerText(title, 'Welcome', {
+ *   description: 'Page title',
+ *   timeout: 3000
+ * });
+ *
+ * @returns True if the element's innerText matches the expected text exactly, otherwise false
+ */
+  static async isElementTextMatchInnerText(locator: Locator, expected: string,
+    options: ActionOptions = {}
+  ): Promise<boolean> {
+    const { description } = this.resolveOptions(options);
+    try {
+      await this.waitForVisible(locator, options);
+      await this.highlight(locator);
+
+      const actualText = await this.getInnerText(locator);
+      return actualText === expected;
+    } catch {
+      console.warn(`⚠ innerText of ${description} does not match "${expected}"`);
+      return false;
+    }
+  }
+
+  /**
+   * Checks if an element's innerText contains the expected text.
+   *
+   * @param locator - Locator of the target element
+   * @param expected - Text expected to be contained within the element's innerText
+   * @param options - Optional action settings
+   * @param options.timeout - Maximum time to wait for the element to become visible (default: 1500)
+   * @param options.description - Description of the element used for logging
+   *
+   * @example
+   * const contains = await isElementTextContainsInnerText(message, 'Success');
+   *
+   * @example
+   * const contains = await isElementTextContainsInnerText(message, 'Success', {
+   *   description: 'Toast message'
+   * });
+   *
+   * @returns True if the element's innerText contains the expected text, otherwise false
+   */
+  static async isElementTextContainsInnerText(locator: Locator, expected: string,
+    options: ActionOptions = {}
+  ): Promise<boolean> {
+    const { description } = this.resolveOptions(options);
+    try {
+      await this.waitForVisible(locator, options);
+      await this.highlight(locator);
+
+      const actualText = await this.getInnerText(locator);
+      return actualText.includes(expected);
+    } catch {
+      console.warn(`⚠ innerText of ${description} does not contain "${expected}"`);
+      return false;
+    }
+  }
+
+  /**
+ * Checks if an element's textContent exactly matches the expected text.
+ *
+ * @param locator - Locator of the target element
+ * @param expected - Expected text to match exactly against the element's textContent
+ * @param options - Optional action settings
+ * @param options.timeout - Maximum time to wait for the element to become visible (default: 1500)
+ * @param options.description - Description of the element used for logging
+ *
+ * @example
+ * const isExact = await isElementTextMatchText(label, 'Username');
+ *
+ * @example
+ * const isExact = await isElementTextMatchText(label, 'Username', {
+ *   description: 'Username label'
+ * });
+ *
+ * @returns True if the element's textContent matches the expected text exactly, otherwise false
+ */
+  static async isElementTextMatchText(locator: Locator, expected: string,
+    options: ActionOptions = {}
+  ): Promise<boolean> {
+    const { description } = this.resolveOptions(options);
+    try {
+      await this.waitForVisible(locator, options);
+      await this.highlight(locator);
+
+      const actualText = await this.getText(locator);
+      return actualText === expected;
+    } catch {
+      console.warn(`⚠ textContent of ${description} does not match "${expected}"`);
+      return false;
+    }
+  }
+
+  /**
+ * Checks if an element's textContent contains the expected text.
+ *
+ * @param locator - Locator of the target element
+ * @param expected - Text expected to be contained within the element's textContent
+ * @param options - Optional action settings
+ * @param options.timeout - Maximum time to wait for the element to become visible (default: 1500)
+ * @param options.description - Description of the element used for logging
+ *
+ * @example
+ * const contains = await isElementTextContainsText(button, 'Submit');
+ *
+ * @example
+ * const contains = await isElementTextContainsText(button, 'Submit', {description: 'Submit button',
+ *   timeout: 4000
+ * });
+ *
+ * @returns True if the element's textContent contains the expected text, otherwise false
+ */
+  static async isElementTextContainsText(locator: Locator, expected: string,
+    options: ActionOptions = {}
+  ): Promise<boolean> {
+
+    const { description } = this.resolveOptions(options);
+
+    try {
+      await this.waitForVisible(locator, options);
+      await this.highlight(locator);
+
+      const actualText = await this.getText(locator);
+      return typeof actualText === 'string' && actualText.includes(expected);
+    } catch {
+      console.warn(`⚠ textContent of ${description} does not contain "${expected}"`);
+      return false;
+    }
+  }
+
+  /**
+   * Checks if the given list is sorted in ascending order.
+   * @param list List of comparable values
+   * @returns true if sorted ascending, else false
+   */
+  static isAscending<T>(list: T[]): boolean {
+    try {
+      if (!list || list.length <= 1) return true;
+
+      for (let i = 0; i < list.length - 1; i++) {
+        if (list[i] > list[i + 1]) return false;
+      }
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Checks if the given list is sorted in descending order.
+   * @param list List of comparable values
+   * @returns true if sorted descending, else false
+   */
+  static isDescending<T>(list: T[]): boolean {
+    try {
+      if (!list || list.length <= 1) return true;
+
+      for (let i = 0; i < list.length - 1; i++) {
+        if (list[i] < list[i + 1]) return false;
+      }
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+
+
+  /**
+   * Sorts a list of values in ascending or descending order.
+   * @param values Values to sort
+   * @param order Sorting order ('asc' or 'desc')
+   * @returns Sorted array
+   */
+  static sortValues(values: any[], order: 'asc' | 'desc'): any[] {
+
+    const sorted = [...values].sort((a, b) => {
+      if (a === b) return 0;
+      if (a > b) return 1;
+      return -1;
+    });
+
+    return order === 'asc' ? sorted : sorted.reverse();
+  }
+  /**
+    * Sort date strings from Newest to Oldest using given format.
+    * @param dateStrings Date strings from UI
+    * @param format Date format (e.g. 'MMM dd, yyyy HH:mm:s')
+    * @returns Sorted date strings (Newest first)
+    */
+  static sortDateNewestToOldest(dateStrings: string[], format: string): string[] {
+    if (!dateStrings || dateStrings.length === 0) return [];
+
+    const dates = dateStrings.map(d =>
+      this.parseDateGeneric(d.trim(), format)
+    );
+
+    dates.sort((a, b) => b.getTime() - a.getTime());
+
+    return dates.map(d => this.formatDateGeneric(d, format));
+  }
+
+  /**
+   * Sort date strings from Oldest to Newest using given format.
+   * @param dateStrings Date strings from UI
+   * @param format Date format (e.g. 'MMM dd, yyyy HH:mm:s')
+   * @returns Sorted date strings (Oldest first)
+   */
+  static sortDateOldestToNewest(dateStrings: string[], format: string): string[] {
+    if (!dateStrings || dateStrings.length === 0) return [];
+
+    const dates = dateStrings.map(d =>
+      this.parseDateGeneric(d.trim(), format)
+    );
+
+    dates.sort((a, b) => a.getTime() - b.getTime());
+
+    return dates.map(d => this.formatDateGeneric(d, format));
+  }
+
+  /**
+    * Month name to month index mapping for parsing 'MMM' format.
+    */
+  static readonly MONTH_MAP: Record<string, number> = {
+    Jan: 0, Feb: 1, Mar: 2, Apr: 3,
+    May: 4, Jun: 5, Jul: 6, Aug: 7,
+    Sep: 8, Oct: 9, Nov: 10, Dec: 11
+  }
+
+  /**
+ * Parses a date string into a Date object using a generic format.
+ * Supports multiple date tokens like yyyy, MM, MMM, dd, HH, mm, ss.
+ * @param dateStr Date string from UI
+ * @param format Format of the date string
+ * @returns Parsed Date object
+ */
+  static parseDateGeneric(dateStr: string, format: string): Date {
+    const tokenRegex = /(yyyy|MMM|MM|dd|HH|mm|ss|s)/g;
+    const formatTokens = format.match(tokenRegex);
+    const dateParts = dateStr.match(/\w+/g);
+
+    if (!formatTokens || !dateParts || formatTokens.length !== dateParts.length) {
+      throw new Error(`Invalid date or format: ${dateStr}`);
+    }
+
+    let year = 1970, month = 0, day = 1;
+    let hour = 0, minute = 0, second = 0;
+
+    formatTokens.forEach((token, i) => {
+      const value = dateParts[i];
+      switch (token) {
+        case "yyyy": year = Number(value); break;
+        case "MM": month = Number(value) - 1; break;
+        case "MMM": month = this.MONTH_MAP[value]; break;
+        case "dd": day = Number(value); break;
+        case "HH": hour = Number(value); break;
+        case "mm": minute = Number(value); break;
+        case "s":
+        case "ss": second = Number(value); break;
+      }
+    });
+
+    return new Date(year, month, day, hour, minute, second);
+  }
+
+  /**
+  * Formats a Date object into a string using the provided format.
+  * @param date Date object
+  * @param format Desired output format
+  * @returns Formatted date string
+  */
+  static formatDateGeneric(date: Date, format: string): string {
+    const pad = (n: number) => n.toString().padStart(2, "0");
+
+    return format
+      .replace("yyyy", date.getFullYear().toString())
+      .replace("MMM", Object.keys(this.MONTH_MAP)
+        .find(k => this.MONTH_MAP[k] === date.getMonth())!)
+      .replace("MM", pad(date.getMonth() + 1))
+      .replace("dd", pad(date.getDate()))
+      .replace("HH", pad(date.getHours()))
+      .replace("mm", pad(date.getMinutes()))
+      .replace("ss", pad(date.getSeconds()))
+      .replace("s", date.getSeconds().toString());
+  }
+
+  /**
+ * Selects an option from a list of locators based on visible text.
+ *
+ * @param optionsList - Locator representing list of selectable options
+ * @param optionText - Visible text of the option to select
+ * @param options - Optional action settings
+ * @param options.timeout - Maximum wait time (default: 15000)
+ *
+ * @returns true if option is clicked successfully, otherwise false
+ */
+  static async clickOnFilterOptionFromList(optionsList: Locator, optionText: string,
+    options: ActionOptions = {}
+  ): Promise<boolean> {
+
+    const { timeout = 15000 } = this.resolveOptions(options);
+
+    try {
+      if (!optionText || optionText.trim() === '') {
+        console.error('⚠ Option text must be a non-empty string');
+        return false;
+      }
+
+      const count = await optionsList.count();
+
+      for (let i = 0; i < count; i++) {
+        const option = optionsList.nth(i);
+        const text = (await option.innerText())
+          .replace(/\s+/g, ' ')
+          .trim();
+        console.log("fileter options:", text);
+
+        if (text.toLowerCase() === (optionText.toLowerCase())) {
+          await option.scrollIntoViewIfNeeded();
+          await this.click(option, { timeout });
+          return true;
+        }
+      }
+
+      console.error(`⚠ Option "${optionText}" not found in list`);
+      return false;
+
+    } catch (error) {
+      console.error(
+        `⚠ Failed to select option "${optionText}": ${(error as Error).message}`
+      );
+      return false;
+    }
+  }
+
+  /**
+ * Selects an option from a native <select> dropdown using visible text.
+ *
+ * @param dropdown - Locator pointing to the <select> element
+ * @param optionText - Visible text of the option to select
+ * @param options - Optional configuration (timeout, description)
+ */
+  static async selectByText(dropdown: Locator, optionText: string, options: ActionOptions = {}
+  ): Promise<void> {
+    const { timeout, description } = this.resolveOptions(options);
+
+    try {
+      await this.waitForVisible(dropdown, options);
+      await this.highlight(dropdown);
+      await dropdown.scrollIntoViewIfNeeded();
+
+      await dropdown.selectOption(
+        { label: optionText },
+        { timeout }
+      );
+
+      const selected = await dropdown.inputValue();
+      if (!selected) {
+        console.warn(`⚠ Option "${optionText}" may not be selected in ${description}`);
+      }
+    } catch (error) {
+      console.warn(
+        `⚠ ${description}: Unable to select option "${optionText}". ${(error as Error).message}`
+      );
+    }
+  }
+
+  /**
+   * Selects an option from a native <select> dropdown using the option's value attribute.
+   *
+   * @param dropdown - Locator pointing to the <select> element
+   * @param value - Value attribute of the option to select
+   * @param options - Optional configuration (timeout, description)
+   */
+  static async selectByValue(dropdown: Locator, value: string, options: ActionOptions = {}
+  ): Promise<void> {
+    const { timeout, description } = this.resolveOptions(options);
+
+    try {
+      await this.waitForVisible(dropdown, options);
+      await this.highlight(dropdown);
+      await dropdown.scrollIntoViewIfNeeded();
+
+      await dropdown.selectOption(
+        { value },
+        { timeout }
+      );
+
+      const selected = await dropdown.inputValue();
+      if (selected !== value) {
+        console.warn(`⚠ Value "${value}" may not be selected in ${description}`);
+      }
+    } catch (error) {
+      console.warn(
+        `⚠ ${description}: Unable to select value "${value}". ${(error as Error).message}`
+      );
+    }
+  }
+  /**
+   * Selects an option from a native <select> dropdown using the option index (0-based).
+   *
+   * @param dropdown - Locator pointing to the <select> element
+   * @param index - Index of the option (0-based)
+   * @param options - Optional configuration (timeout, description)
+   */
+  static async selectByIndex(dropdown: Locator, index: number,
+    options: ActionOptions = {}
+  ): Promise<void> {
+    const { timeout, description } = this.resolveOptions(options);
+
+    try {
+      await this.waitForVisible(dropdown, options);
+      await this.highlight(dropdown);
+      await dropdown.scrollIntoViewIfNeeded();
+
+      await dropdown.selectOption({ index }, { timeout }
+      );
+
+      const selected = await dropdown.inputValue();
+      if (!selected) {
+        console.warn(`⚠ Option at index ${index} may not be selected in ${description}`);
+      }
+    } catch (error) {
+      console.warn(
+        `⚠ ${description}: Unable to select index ${index}. ${(error as Error).message}`
+      );
+    }
+  }
+
+  /**
+   * Selects an option from a custom (non-<select>) dropdown using visible text.
+   *
+   * @param dropdown - Locator for the dropdown trigger element
+   * @param optionsList - Locator representing all dropdown option elements
+   * @param value - Visible text of the option to select
+   * @param options - Optional configuration (timeout, description)
+   */
+  static async selectFromCustomDropdown(dropdown: Locator, optionsList: Locator, value: string,
+    options: ActionOptions = {}
+  ): Promise<void> {
+    const { timeout, description } = this.resolveOptions(options);
+
+    try {
+      await this.waitForVisible(dropdown, options);
+      await this.highlight(dropdown);
+      await dropdown.click({ timeout });
+
+      const firstOption = optionsList.first();
+      await firstOption.waitFor({ state: 'visible', timeout });
+
+      const count = await optionsList.count();
+
+      for (let i = 0; i < count; i++) {
+        const option = optionsList.nth(i);
+        await this.highlight(option);
+
+        const text = (await option.innerText()).trim();
+        if (text === value) {
+          await option.click({ timeout });
+          return;
+        }
+      }
+
+      console.warn(`⚠ ${description}: Option "${value}" not found`);
+    } catch (error) {
+      console.warn(
+        `⚠ ${description}: Failed selecting "${value}". ${(error as Error).message}`
+      );
+    }
+  }
+  /**
+   * Retrieves all visible option texts from a dropdown or options list.
+   *
+   * @param optionsList - Locator pointing to dropdown option elements
+   * @param options - Optional configuration (timeout, description)
+   * @returns Array of trimmed option texts or empty array
+   */
+  static async getAllOptions(optionsList: Locator, options: ActionOptions = {}
+  ): Promise<string[]> {
+    const { timeout, description } = this.resolveOptions(options);
+
+    try {
+      const first = optionsList.first();
+      await first.waitFor({ state: 'visible', timeout });
+      await this.highlight(first);
+
+      const count = await optionsList.count();
+      const values: string[] = [];
+
+      for (let i = 0; i < count; i++) {
+        const option = optionsList.nth(i);
+        const text = (await option.innerText()).trim();
+        values.push(text);
+      }
+
+      return values;
+    } catch (error) {
+      console.warn(
+        `⚠ ${description}: Unable to fetch dropdown options. ${(error as Error).message}`
+      );
+      return [];
+    }
+  }
+  /**
+   * Checks whether a dropdown/options list contains a specific visible option.
+   *
+   * @param optionsList - Locator representing dropdown option elements
+   * @param value - Option text to verify
+   * @param options - Optional configuration (timeout, description)
+   * @returns true if option exists, otherwise false
+   */
+  static async hasOption(optionsList: Locator, value: string,
+    options: ActionOptions = {}
+  ): Promise<boolean> {
+    const { timeout, description } = this.resolveOptions(options);
+
+    try {
+      const first = optionsList.first();
+      await first.waitFor({ state: 'visible', timeout });
+
+      const count = await optionsList.count();
+
+      for (let i = 0; i < count; i++) {
+        const option = optionsList.nth(i);
+        const text = (await option.innerText()).trim();
+
+        if (text === value) {
+          return true;
+        }
+      }
+
+      return false;
+    } catch (error) {
+      console.warn(
+        `⚠ ${description}: Error while checking option "${value}". ${(error as Error).message}`
+      );
+      return false;
+    }
+  }
+  /**
+   * Retrieves the currently selected option text from a native <select> dropdown.
+   *
+   * @param dropdown - Locator for the <select> element
+   * @param options - Optional configuration (timeout, description)
+   * @returns The text of the selected option, or null if none is selected
+   */
+  static async getSelectedOption(dropdown: Locator, options: ActionOptions = {}
+  ): Promise<string | null> {
+    const { description } = this.resolveOptions(options);
+
+    try {
+      await this.waitForVisible(dropdown, options);
+      await this.highlight(dropdown);
+
+      const selectedOptions = await dropdown.evaluate((select: HTMLSelectElement) => {
+        const selected = Array.from(select.options).filter(option => option.selected);
+        return selected.map(option => option.text.trim());
+      });
+
+      if (!selectedOptions || selectedOptions.length === 0) {
+        console.warn(`⚠ ${description}: No option is currently selected`);
+        return null;
+      }
+
+      return selectedOptions[0];
+    } catch (error) {
+      console.warn(
+        `⚠ ${description}: Unable to get selected option. ${(error as Error).message}`
+      );
+      return null;
+    }
+  }
+
+
+  //**Pagination Methods */
+
+  /**
+   * Determines the total number of pages by navigating to the last page
+   * and reading the active page number.
+   *
+   * @param paginationContainer - Locator for the pagination container
+   * @param options - Optional configuration (timeout, description, locators)
+   * @returns Total number of pages, or 0 if it cannot be determined
+   */
+  static async getTotalPaginationCount(paginationContainer: Locator, options: ActionOptions = {}
+  ): Promise<number> {
+
+    const {
+      timeout = 15000,
+      description = 'Pagination',
+      lastButtonLocator = 'button.pagination-btn-last',
+      activePageLocator = 'button.pagination-btn.active'
+    } = options;
+
+    try {
+      const page = paginationContainer.page();
+      await this.waitForVisible(paginationContainer, { timeout, description });
+
+      const activePage = paginationContainer.locator(activePageLocator).first();
+      await this.waitForVisible(activePage, { timeout, description: 'Active Page Button' });
+
+      const beforeText = (await activePage.innerText()).trim();
+
+      const lastButton = paginationContainer.locator(lastButtonLocator).first();
+
+      if ((await lastButton.count()) === 0) {
+        console.warn(`⚠ ${description}: Last page button not found`);
+        return 0;
+      }
+
+      await this.waitForVisible(lastButton, { timeout, description: 'Last Page Button' });
+      await this.highlight(lastButton);
+      await lastButton.click({ timeout });
+
+      // Wait until active page number changes
+      const handle = await activePage.elementHandle();
+      if (handle) {
+        await page.waitForFunction(
+          ([el, previous]) => (el as HTMLElement).innerText.trim() !== previous,
+          [handle, beforeText],
+          { timeout }
+        );
+      }
+
+      const finalText = (await activePage.innerText()).trim();
+      const total = Number(finalText);
+
+      if (Number.isNaN(total)) {
+        console.warn(`⚠ ${description}: Invalid total page number "${finalText}"`);
+        return 0;
+      }
+
+      return total;
+
+    } catch (error) {
+      console.warn(
+        `⚠ ${description}: Unable to determine total pagination count. ${(error as Error).message}`
+      );
+      return 0;
+    }
+  }
+
+  /**
+   * Clicks the "Next" button in pagination, if available.
+   *
+   * @param paginationContainer - Locator for the pagination container
+   * @param options - Optional configuration (timeout, description, locators)
+   * @returns True if the next button was clicked, otherwise false
+   */
+  static async clickNextPagination( paginationContainer: Locator, options: ActionOptions = {}
+  ): Promise<boolean> {
+
+    const {
+      timeout = 15000,
+      description = 'Pagination Next Button',
+      nextButtonLocator = 'button[data-page="next"]'
+    } = options;
+
+    try {
+      await this.waitForVisible(paginationContainer, { timeout, description });
+
+      const nextBtn = paginationContainer.locator(nextButtonLocator).first();
+
+      if ((await nextBtn.count()) === 0) {
+        console.warn(`⚠ ${description}: Next button not found`);
+        return false;
+      }
+
+      await this.waitForVisible(nextBtn, { timeout });
+      await this.highlight(nextBtn);
+      await nextBtn.scrollIntoViewIfNeeded();
+      await nextBtn.click({ timeout });
+
+      return true;
+
+    } catch (error) {
+      console.warn(
+        `⚠ ${description}: Failed to click next pagination button. ${(error as Error).message}`
+      );
+      return false;
+    }
+  }
+
+  /**
+   * Clicks the "Previous" button in pagination, if available.
+   *
+   * @param paginationContainer - Locator for the pagination container
+   * @param options - Optional configuration (timeout, description, locators)
+   * @returns True if the previous button was clicked, otherwise false
+   */
+  static async clickPrevPagination(paginationContainer: Locator,options: ActionOptions = {}
+  ): Promise<boolean> {
+
+    const {
+      timeout = 15000,
+      description = 'Pagination Previous Button',
+      prevButtonLocator = 'button[data-page="prev"]'
+    } = options;
+
+    try {
+      await this.waitForVisible(paginationContainer, { timeout, description });
+
+      const prevBtn = paginationContainer.locator(prevButtonLocator).first();
+
+      if ((await prevBtn.count()) === 0) {
+        console.warn(`⚠ ${description}: Previous button not found`);
+        return false;
+      }
+
+      await this.waitForVisible(prevBtn, { timeout });
+      await this.highlight(prevBtn);
+      await prevBtn.scrollIntoViewIfNeeded();
+      await prevBtn.click({ timeout });
+
+      return true;
+
+    } catch (error) {
+      console.warn(
+        `⚠ ${description}: Failed to click previous pagination button. ${(error as Error).message}`
+      );
+      return false;
+    }
+  }
+
+  /**
+   * Clicks the "Last" page button in pagination.
+   *
+   * @param paginationContainer - Locator for the pagination container
+   * @param options - Optional configuration (timeout, description, locators)
+   * @returns True if the last button was clicked successfully, otherwise false
+   */
+  static async clickLastPagination(paginationContainer: Locator, options: ActionOptions = {}
+  ): Promise<boolean> {
+
+    const {
+      timeout = 15000,
+      description = 'Pagination Last Button',
+      lastButtonLocator = 'button[data-page="last"]'
+    } = options;
+
+    try {
+      await this.waitForVisible(paginationContainer, { timeout, description });
+
+      const lastBtn = paginationContainer.locator(lastButtonLocator).first();
+
+      if ((await lastBtn.count()) === 0) {
+        console.warn(`⚠ ${description}: Last button not found`);
+        return false;
+      }
+
+      await this.waitForVisible(lastBtn, { timeout });
+      await this.highlight(lastBtn);
+      await lastBtn.scrollIntoViewIfNeeded();
+      await lastBtn.click({ timeout });
+
+      return true;
+
+    } catch (error) {
+      console.warn(
+        `⚠ ${description}: Failed to click last pagination button. ${(error as Error).message}`
+      );
+      return false;
+    }
+  }
+
+  /**
+   * Retrieves the currently active page number from pagination.
+   *
+   * @param paginationContainer - Locator for the pagination container
+   * @param options - Optional configuration (timeout, description, locators)
+   * @returns Active page number, or 0 if not found or invalid
+   */
+  static async getActivePaginationPage(paginationContainer: Locator, options: ActionOptions = {}
+  ): Promise<number> {
+
+    const {
+      timeout = 15000,
+      description = 'Active Pagination Page',
+      activePageLocator = 'button.pagination-btn.active'
+    } = options;
+
+    try {
+      await this.waitForVisible(paginationContainer, { timeout, description });
+
+      const activeBtn = paginationContainer.locator(activePageLocator).first();
+
+      if ((await activeBtn.count()) === 0) {
+        console.warn(`⚠ ${description}: Active page button not found`);
+        return 0;
+      }
+
+      await this.waitForVisible(activeBtn, { timeout });
+      await this.highlight(activeBtn);
+
+      const text = (await activeBtn.innerText()).trim();
+      const pageNumber = Number(text);
+
+      if (Number.isNaN(pageNumber)) {
+        console.warn(`⚠ ${description}: Invalid page number text "${text}"`);
+        return 0;
+      }
+
+      return pageNumber;
+
+    } catch (error) {
+      console.warn(
+        `⚠ ${description}: Failed to get active pagination page. ${(error as Error).message}`
+      );
+      return 0;
+    }
+  }
+
+  /**
+   * Clicks the "Start" (first page) button in pagination, if available.
+   *
+   * @param paginationContainer - Locator for the pagination container
+   * @param options - Optional configuration (timeout, description, locators)
+   * @returns True if the start button was clicked, otherwise false
+   */
+  static async clickStartPagination(paginationContainer: Locator,options: ActionOptions = {}
+  ): Promise<boolean> {
+
+    const {
+      timeout = 15000,
+      description = 'Pagination Start Button',
+      firstButtonLocator = 'button.pagination-btn-start'
+    } = options;
+
+    try {
+      await this.waitForVisible(paginationContainer, { timeout, description });
+
+      const startBtn = paginationContainer.locator(firstButtonLocator).first();
+
+      if ((await startBtn.count()) === 0) {
+        console.warn(`⚠ ${description}: Start button not found`);
+        return false;
+      }
+
+      await this.waitForVisible(startBtn, { timeout });
+      await this.highlight(startBtn);
+      await startBtn.scrollIntoViewIfNeeded();
+      await startBtn.click({ timeout });
+
+      return true;
+
+    } catch (error) {
+      console.warn(
+        `⚠ ${description}: Failed to click start pagination button. ${(error as Error).message}`
+      );
+      return false;
+    }
+  }
+
+  /**
+   * Clicks a specific page number button in pagination.
+   *
+   * @param paginationContainer - Locator for the pagination container
+   * @param pageNumber - Page number to navigate to (1-based)
+   * @param options - Optional configuration (timeout, description, locators)
+   * @returns True if the page number button was clicked, otherwise false
+   */
+  static async clickPaginationPageNumber( paginationContainer: Locator,pageNumber: number,
+    options: ActionOptions = {}
+  ): Promise<boolean> {
+
+    const {
+      timeout = 15000,
+      description = `Pagination Page ${pageNumber} Button`,
+      pageButtonLocator = 'button.pagination-btn'
+    } = options;
+
+    try {
+      await this.waitForVisible(paginationContainer, { timeout, description });
+
+      const pageButtons = paginationContainer.locator(pageButtonLocator);
+      const count = await pageButtons.count();
+
+      if (count === 0) {
+        console.warn(`⚠ ${description}: No pagination buttons found`);
+        return false;
+      }
+
+      for (let i = 0; i < count; i++) {
+        const btn = pageButtons.nth(i);
+        const text = (await btn.innerText()).trim();
+
+        if (text === String(pageNumber)) {
+          await this.waitForVisible(btn, { timeout });
+          await this.highlight(btn);
+          await btn.scrollIntoViewIfNeeded();
+          await btn.click({ timeout });
+          return true;
+        }
+      }
+
+      console.warn(`⚠ ${description}: Page button "${pageNumber}" not found`);
+      return false;
+
+    } catch (error) {
+      console.warn(
+        `⚠ ${description}: Failed to click page number "${pageNumber}". ${(error as Error).message}`
+      );
+      return false;
+    }
+  }
+}