@redhat-developer/page-objects 1.17.0 → 1.18.1

package/out/errors/ExTesterError.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License", destination); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VersionNotSupportedError = exports.PlatformNotSupportedError = exports.LocatorError = exports.TimeoutError = exports.ElementRecoveryError = exports.StaleElementError = exports.ElementNotInteractableError = exports.ElementNotVisibleError = exports.ElementNotFoundError = exports.ExTesterError = void 0;
+exports.wrapError = wrapError;
+/**
+ * Base error class for all ExTester-specific errors.
+ * Provides rich context for debugging test failures.
+ */
+class ExTesterError extends Error {
+    context;
+    timestamp;
+    constructor(message, context = {}) {
+        super(message);
+        this.name = 'ExTesterError';
+        this.context = context;
+        this.timestamp = new Date();
+        // Maintain proper stack trace in V8 environments
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Get a detailed string representation of the error for logging.
+     */
+    toDetailedString() {
+        const lines = [`${this.name}: ${this.message}`, `  Timestamp: ${this.timestamp.toISOString()}`];
+        if (this.context.component) {
+            lines.push(`  Component: ${this.context.component}`);
+        }
+        if (this.context.action) {
+            lines.push(`  Action: ${this.context.action}`);
+        }
+        if (this.context.vscodeVersion) {
+            lines.push(`  VS Code Version: ${this.context.vscodeVersion}`);
+        }
+        if (this.context.locator) {
+            lines.push(`  Locator: ${this.context.locator}`);
+        }
+        if (this.context.details) {
+            lines.push(`  Details: ${this.context.details}`);
+        }
+        if (this.context.cause) {
+            lines.push(`  Caused by: ${this.context.cause.name}: ${this.context.cause.message}`);
+        }
+        return lines.join('\n');
+    }
+    toString() {
+        return this.toDetailedString();
+    }
+}
+exports.ExTesterError = ExTesterError;
+/**
+ * Error thrown when an element cannot be found in the DOM.
+ */
+class ElementNotFoundError extends ExTesterError {
+    constructor(message, context = {}) {
+        super(message, context);
+        this.name = 'ElementNotFoundError';
+    }
+}
+exports.ElementNotFoundError = ElementNotFoundError;
+/**
+ * Error thrown when an element exists but is not visible.
+ */
+class ElementNotVisibleError extends ExTesterError {
+    constructor(message, context = {}) {
+        super(message, context);
+        this.name = 'ElementNotVisibleError';
+    }
+}
+exports.ElementNotVisibleError = ElementNotVisibleError;
+/**
+ * Error thrown when an element cannot be interacted with (e.g., blocked, disabled).
+ */
+class ElementNotInteractableError extends ExTesterError {
+    constructor(message, context = {}) {
+        super(message, context);
+        this.name = 'ElementNotInteractableError';
+    }
+}
+exports.ElementNotInteractableError = ElementNotInteractableError;
+/**
+ * Error thrown when an element reference has become stale (DOM was modified).
+ */
+class StaleElementError extends ExTesterError {
+    constructor(message, context = {}) {
+        super(message, context);
+        this.name = 'StaleElementError';
+    }
+}
+exports.StaleElementError = StaleElementError;
+/**
+ * Error thrown when element recovery/reinitialization fails.
+ */
+class ElementRecoveryError extends ExTesterError {
+    constructor(message, context = {}) {
+        super(message, context);
+        this.name = 'ElementRecoveryError';
+    }
+}
+exports.ElementRecoveryError = ElementRecoveryError;
+/**
+ * Error thrown when a timeout occurs waiting for a condition.
+ */
+class TimeoutError extends ExTesterError {
+    timeoutMs;
+    constructor(message, timeoutMs, context = {}) {
+        super(message, context);
+        this.name = 'TimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+    toDetailedString() {
+        const base = super.toDetailedString();
+        return `${base}\n  Timeout: ${this.timeoutMs}ms`;
+    }
+}
+exports.TimeoutError = TimeoutError;
+/**
+ * Error thrown when a locator fails to match any elements.
+ */
+class LocatorError extends ExTesterError {
+    constructor(message, context = {}) {
+        super(message, context);
+        this.name = 'LocatorError';
+    }
+}
+exports.LocatorError = LocatorError;
+/**
+ * Error thrown for platform-specific limitations (e.g., macOS native dialogs).
+ */
+class PlatformNotSupportedError extends ExTesterError {
+    platform;
+    constructor(message, platform = process.platform, context = {}) {
+        super(message, context);
+        this.name = 'PlatformNotSupportedError';
+        this.platform = platform;
+    }
+    toDetailedString() {
+        const base = super.toDetailedString();
+        return `${base}\n  Platform: ${this.platform}`;
+    }
+}
+exports.PlatformNotSupportedError = PlatformNotSupportedError;
+/**
+ * Error thrown when an operation is not supported for the current VS Code version.
+ */
+class VersionNotSupportedError extends ExTesterError {
+    requiredVersion;
+    currentVersion;
+    constructor(message, requiredVersion, currentVersion, context = {}) {
+        super(message, { ...context, vscodeVersion: currentVersion });
+        this.name = 'VersionNotSupportedError';
+        this.requiredVersion = requiredVersion;
+        this.currentVersion = currentVersion;
+    }
+    toDetailedString() {
+        const base = super.toDetailedString();
+        return `${base}\n  Required Version: ${this.requiredVersion}`;
+    }
+}
+exports.VersionNotSupportedError = VersionNotSupportedError;
+/**
+ * Utility to wrap native Selenium errors with ExTester context.
+ */
+function wrapError(originalError, context) {
+    const message = originalError.message;
+    if (originalError.name === 'StaleElementReferenceError') {
+        return new StaleElementError(message, { ...context, cause: originalError });
+    }
+    if (originalError.name === 'NoSuchElementError') {
+        return new ElementNotFoundError(message, { ...context, cause: originalError });
+    }
+    if (originalError.name === 'ElementNotInteractableError' || originalError.name === 'ElementClickInterceptedError') {
+        return new ElementNotInteractableError(message, { ...context, cause: originalError });
+    }
+    if (originalError.name === 'ElementNotVisibleError') {
+        return new ElementNotVisibleError(message, { ...context, cause: originalError });
+    }
+    if (originalError.name === 'TimeoutError') {
+        return new TimeoutError(message, 0, { ...context, cause: originalError });
+    }
+    // Generic fallback
+    return new ExTesterError(message, { ...context, cause: originalError });
+}
+//# sourceMappingURL=ExTesterError.js.map

package/out/index.d.ts

@@ -18,6 +18,8 @@ import { WebDriver } from 'selenium-webdriver';
 export * from 'selenium-webdriver';
 export * from './locators/locators';
 export * from './errors/NullAttributeError';
+export * from './errors/ExTesterError';
+export * from './utils/WaitHelper';
 export * from './components/menu/Menu';
 export * from './components/menu/MenuItem';
 export * from './components/menu/TitleBar';

package/out/index.js

@@ -37,6 +37,8 @@ const loader_1 = require("./locators/loader");
 __exportStar(require("selenium-webdriver"), exports);
 __exportStar(require("./locators/locators"), exports);
 __exportStar(require("./errors/NullAttributeError"), exports);
+__exportStar(require("./errors/ExTesterError"), exports);
+__exportStar(require("./utils/WaitHelper"), exports);
 __exportStar(require("./components/menu/Menu"), exports);
 __exportStar(require("./components/menu/MenuItem"), exports);
 __exportStar(require("./components/menu/TitleBar"), exports);

package/out/utils/WaitHelper.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License", destination); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { WebDriver, WebElement, Locator } from 'selenium-webdriver';
+export interface WaitOptions {
+    /** Maximum time to wait in milliseconds */
+    timeout?: number;
+    /** Interval between condition checks in milliseconds */
+    pollInterval?: number;
+    /** Custom error message when timeout is reached */
+    message?: string;
+}
+export interface RetryOptions {
+    /** Maximum number of retry attempts */
+    maxRetries?: number;
+    /** Delay between retries in milliseconds */
+    retryDelay?: number;
+    /** Multiplier for exponential backoff (default: 1 = linear) */
+    backoffMultiplier?: number;
+    /** Function to determine if error is retryable */
+    isRetryable?: (error: Error) => boolean;
+}
+export interface StabilityOptions extends WaitOptions {
+    /** Number of consecutive stable checks required */
+    stableChecks?: number;
+    /** Interval between stability checks in milliseconds */
+    stabilityInterval?: number;
+}
+/**
+ * Utility class for condition-based waiting operations.
+ * Replaces arbitrary sleep() calls with intelligent waiting strategies.
+ */
+export declare class WaitHelper {
+    private readonly driver;
+    private readonly defaultTimeout;
+    private readonly defaultPollInterval;
+    constructor(driver: WebDriver, defaultTimeout?: number, defaultPollInterval?: number);
+    /**
+     * Wait for a condition to become truthy.
+     * @param condition Async function that returns a value - waiting stops when value is truthy
+     * @param options Wait configuration options
+     * @returns The truthy value returned by the condition
+     */
+    forCondition<T>(condition: () => Promise<T>, options?: WaitOptions): Promise<T>;
+    /**
+     * Wait for an element's attribute to have a specific value.
+     * @param element The WebElement to check
+     * @param attribute Name of the attribute
+     * @param value Expected value
+     * @param options Wait configuration options
+     */
+    forAttributeValue(element: WebElement, attribute: string, value: string, options?: WaitOptions): Promise<void>;
+    /**
+     * Wait for an element's attribute to contain a specific value.
+     * @param element The WebElement to check
+     * @param attribute Name of the attribute
+     * @param value Value to search for
+     * @param options Wait configuration options
+     */
+    forAttributeContains(element: WebElement, attribute: string, value: string, options?: WaitOptions): Promise<void>;
+    /**
+     * Wait for an element to become stable (position/size stops changing).
+     * Useful for waiting after animations or dynamic content loading.
+     *
+     * Note: If the element becomes stale (removed from DOM), this method returns
+     * successfully since element removal is a form of "stability".
+     *
+     * @param element The WebElement to monitor
+     * @param options Stability configuration options
+     */
+    forStable(element: WebElement, options?: StabilityOptions): Promise<void>;
+    /**
+     * Wait for an element to become visible.
+     * @param element The WebElement to check
+     * @param options Wait configuration options
+     */
+    forVisible(element: WebElement, options?: WaitOptions): Promise<void>;
+    /**
+     * Wait for an element to become invisible.
+     * @param element The WebElement to check
+     * @param options Wait configuration options
+     */
+    forNotVisible(element: WebElement, options?: WaitOptions): Promise<void>;
+    /**
+     * Wait for an element to become enabled.
+     * @param element The WebElement to check
+     * @param options Wait configuration options
+     */
+    forEnabled(element: WebElement, options?: WaitOptions): Promise<void>;
+    /**
+     * Wait for the number of elements matching a condition to stabilize.
+     * Useful for lists that are loading items dynamically.
+     * @param getCount Function that returns the current count
+     * @param options Stability configuration options
+     */
+    forCountStable(getCount: () => Promise<number>, options?: StabilityOptions): Promise<number>;
+    /**
+     * Wait for text content to be present in an element.
+     * @param element The WebElement to check
+     * @param text Expected text (partial match)
+     * @param options Wait configuration options
+     */
+    forTextPresent(element: WebElement, text: string, options?: WaitOptions): Promise<void>;
+    /**
+     * Wait for an element's class list to contain a specific class.
+     * @param element The WebElement to check
+     * @param className Class name to look for
+     * @param options Wait configuration options
+     */
+    forClass(element: WebElement, className: string, options?: WaitOptions): Promise<void>;
+    /**
+     * Wait for an element's class list to NOT contain a specific class.
+     * @param element The WebElement to check
+     * @param className Class name that should not be present
+     * @param options Wait configuration options
+     */
+    forNoClass(element: WebElement, className: string, options?: WaitOptions): Promise<void>;
+    /**
+     * Wait for an element to be clickable (visible AND enabled).
+     * @param element The WebElement to check
+     * @param options Wait configuration options
+     */
+    forClickable(element: WebElement, options?: WaitOptions): Promise<void>;
+    /**
+     * Wait for text content to match exactly or a regex pattern.
+     * @param element The WebElement to check
+     * @param expected Expected text string or RegExp pattern
+     * @param options Wait configuration options
+     */
+    forTextContent(element: WebElement, expected: string | RegExp, options?: WaitOptions): Promise<void>;
+    /**
+     * Wait for a specific number of elements to be present.
+     * @param parent Parent element or driver to search within
+     * @param locator Locator for the elements
+     * @param expectedCount Expected number of elements
+     * @param options Wait configuration options
+     */
+    forElementCount(parent: WebElement | WebDriver, locator: Locator, expectedCount: number, options?: WaitOptions): Promise<WebElement[]>;
+    /**
+     * Wait for at least one element matching the locator to be present.
+     * @param parent Parent element or driver to search within
+     * @param locator Locator for the element
+     * @param options Wait configuration options
+     * @returns The first matching element
+     */
+    forElementLocated(parent: WebElement | WebDriver, locator: Locator, options?: WaitOptions): Promise<WebElement>;
+    /**
+     * Wait for no elements matching the locator to be present (element removed).
+     * @param parent Parent element or driver to search within
+     * @param locator Locator for the element
+     * @param options Wait configuration options
+     */
+    forNoElement(parent: WebElement | WebDriver, locator: Locator, options?: WaitOptions): Promise<void>;
+    /**
+     * Wait for element to be removed from DOM or become stale.
+     * @param element The WebElement to monitor
+     * @param options Wait configuration options
+     */
+    forElementRemoved(element: WebElement, options?: WaitOptions): Promise<void>;
+    /**
+     * Wait for any of the conditions to be met (OR logic).
+     * @param conditions Array of condition functions
+     * @param options Wait configuration options
+     * @returns Index of the first condition that was met
+     */
+    forAnyCondition(conditions: Array<() => Promise<boolean>>, options?: WaitOptions): Promise<number>;
+    /**
+     * Execute a function with automatic retry on failure.
+     * @param fn The function to execute
+     * @param options Retry configuration options
+     * @returns The result of the function
+     */
+    withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+    /**
+     * Simple sleep helper - use sparingly and prefer condition-based waits.
+     * @param ms Milliseconds to sleep
+     */
+    sleep(ms: number): Promise<void>;
+    /**
+     * Get the WebDriver instance.
+     */
+    getDriver(): WebDriver;
+    private rectsEqual;
+}
+/**
+ * Create a WaitHelper instance bound to a WebDriver.
+ * Convenience factory function for quick access.
+ */
+export declare function createWaitHelper(driver: WebDriver, defaultTimeout?: number): WaitHelper;