@probolabs/playwright 1.0.17 → 1.0.20

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Locator, Page } from 'playwright';
-import { ElementTag, PlaywrightTimeoutConfig, PlaywrightAction, AIModel, InitialPageState, FindCandidateInput, ServerResponse, ProboLogLevel } from '@probolabs/probo-shared';
-export { ElementInfo, ElementTag, PlaywrightAction, ProboLogLevel } from '@probolabs/probo-shared';
+import { SmartSelector, ElementTag, ProboLogLevel, PlaywrightTimeoutConfig, PlaywrightAction, TotpConfig, AIModel, InitialPageState, FindCandidateInput, ServerResponse } from '@probolabs/probo-shared';
+export { AIModel, ElementInfo, ElementTag, PlaywrightAction, ProboLogLevel } from '@probolabs/probo-shared';
 import { Page as Page$1 } from '@playwright/test';
 
 /**
@@ -24,8 +24,10 @@ declare global {
             highlightElements: (elements: Array<{
                 css_selector: string;
                 iframe_selector: string;
-                index: string;
-            }>) => void;
+                smart_selector: SmartSelector | null;
+                smart_iframe_selector: SmartSelector | null;
+                index: number;
+            }>, enableSmartSelectors: boolean) => void;
             unhighlightElements: () => void;
             findElements: (elementTypes: string) => any[];
             getElementInfo: (element: Element, index: number) => any;
@@ -34,7 +36,7 @@ declare global {
             actual?: any;
             matchingCandidate?: any;
             findAndCacheCandidateElements?: (elementTypes: string[]) => number;
-            findAndCacheActualElement?: (cssSelector: string, iframeSelector: string | null, isHover: boolean) => boolean;
+            findAndCacheActualElement?: (iframeSelector: string | SmartSelector, elementSelector: string | SmartSelector, isHover: boolean, useSmartSelectors: boolean) => boolean;
             findAndCacheMatchingCandidate?: () => boolean;
             highlightCachedElements?: (which: 'candidates' | 'actual' | 'matching') => void;
             unhighlight?: () => void;
@@ -42,16 +44,19 @@ declare global {
             getCandidates?: () => any[];
             getActual?: () => any;
             getMatchingCandidate?: () => any;
+            setLoggerDebugLevel?: (debugLevel: ProboLogLevel) => void;
         };
     }
 }
 declare class Highlighter {
-    private enableConsoleLogs;
-    constructor(enableConsoleLogs?: boolean);
+    private readonly enableSmartSelectors;
+    private readonly enableConsoleLogs;
+    private readonly debugLevel;
+    constructor(enableSmartSelectors?: boolean, enableConsoleLogs?: boolean, debugLevel?: ProboLogLevel);
     private ensureHighlighterScript;
     highlightElements(page: Page, elementTags: [ElementTagType]): Promise<any>;
     unhighlightElements(page: Page): Promise<void>;
-    highlightElement(page: Page, element_css_selector: string, iframe_selector: string, element_index: string): Promise<void>;
+    highlightElement(page: Page, element_css_selector: string, iframe_selector: string, smart_selector: SmartSelector | null, smart_iframe_selector: SmartSelector | null, element_index: number): Promise<void>;
     /**
      * Find and cache candidate elements of a given type (e.g., 'CLICKABLE').
      * Returns the number of candidates found.
@@ -61,7 +66,7 @@ declare class Highlighter {
      * Find and cache the actual interaction element by CSS and iframe selector.
      * Returns true if found, false otherwise.
      */
-    findAndCacheActualElement(page: Page, cssSelector: string, iframeSelector: string | null, isHover?: boolean): Promise<boolean>;
+    findAndCacheActualElement(page: Page, iframeSelector: string | SmartSelector, elementSelector: string | SmartSelector, isHover?: boolean): Promise<boolean>;
     /**
      * Find and cache the best matching candidate for the actual element.
      * Returns true if a match was found, false otherwise.
@@ -91,73 +96,106 @@ declare class Highlighter {
 interface RunStepParams extends Partial<PlaywrightTimeoutConfig> {
     iframeSelector?: string;
     elementSelector?: string;
+    smartSelector?: SmartSelector | null;
+    smartIFrameSelector?: SmartSelector | null;
     action: PlaywrightAction;
     argument?: string | string[];
     annotation?: string;
     pollingInterval?: number;
     timeout?: number;
+    totpConfig?: TotpConfig;
+}
+interface ProboPlaywrightConfig {
+    timeoutConfig?: Partial<PlaywrightTimeoutConfig>;
+    enableSmartSelectors?: boolean;
+    debugLevel?: ProboLogLevel;
 }
 declare class ProboPlaywright {
+    private readonly enableSmartSelectors;
     private readonly timeoutConfig;
     private page;
-    constructor(timeoutConfig?: Partial<PlaywrightTimeoutConfig>, page?: Page$1 | null);
+    private params;
+    constructor({ enableSmartSelectors, timeoutConfig, debugLevel }: ProboPlaywrightConfig, page?: Page$1 | null);
     /**
-     * Sets the Playwright page instance for this ProboPlaywright instance.
-     * Also applies the configured default navigation and action timeouts to the page.
-     *
-     * @param page - The Playwright Page instance to use, or null to unset.
-     */
+    * Sets the Playwright page instance for this ProboPlaywright instance.
+    * Also applies the configured default navigation and action timeouts to the page.
+    *
+    * @param page - The Playwright Page instance to use, or null to unset.
+    */
     setPage(page: Page$1 | null): void;
+    /**
+     * Sets the parameters object for template literal interpolation
+     * Stores a reference to the params object so mutations are automatically reflected
+     * @param params The parameters object containing values to use for interpolation
+     */
+    setParams(params: Record<string, any>): void;
+    /**
+     * Interpolates a string using the current params and optional additional context
+     * @param str The string to interpolate (may contain ${variable} syntax)
+     * @param additionalContext Optional additional context to merge with params
+     * @returns The interpolated string
+     */
+    private interpolate;
     /**
      * Executes a single step in the test scenario with the specified action on the target element.
-     * Handles iframe navigation, element highlighting, and various Playwright actions like click, fill, validate, etc.
-     *
-     * @param params - Configuration object containing element selectors, action type, arguments, and display options
-     * @returns Promise that resolves to a result object for extract actions, or void for other actions
-     * @throws Error if element is not found or validation fails
+    * Handles iframe navigation, element highlighting, and various Playwright actions like click, fill, validate, etc.
+    *
+    * @param params - Configuration object containing element selectors, action type, arguments, and display options
+    * @returns Promise that resolves to a string for extract actions, boolean for assert actions, or void for other actions
+    * @throws Error if element is not found or validation fails
+    */
+    runStep(params: RunStepParams): Promise<string | boolean | void>;
+    /**
+     * Public method to generate TOTP code using the provided secret, digits, and algorithm
+     * @param secret - The TOTP secret (base32 encoded)
+     * @param digits - Number of digits in the TOTP code (default: 6)
+     * @param algorithm - Hash algorithm to use (default: 'SHA1')
+     * @returns The generated TOTP code
      */
-    runStep(params: RunStepParams): Promise<string | void>;
     generateOTP(secret: string, digits?: number, algorithm?: string): string;
+    private getLocator;
+    private getLocatorOrFrame;
     /**
-     * Creates a visual highlight overlay on the target element with optional annotation text.
-     * The highlight appears as a red border around the element and can include descriptive text.
-     *
-     * @param locator - The Playwright locator for the element to highlight
-     * @param annotation - Optional text annotation to display above/below the highlighted element
-     */
+    * Creates a visual highlight overlay on the target element with optional annotation text.
+    * The highlight appears as a red border around the element and can include descriptive text.
+    *
+    * @param locator - The Playwright locator for the element to highlight
+    * @param annotation - Optional text annotation to display above/below the highlighted element
+    */
     private highlight;
     /**
-     * Removes the highlight overlay from the target element.
-     * Cleans up the visual highlighting created by the highlight method.
-     *
-     * @param locator - The Playwright locator for the element to unhighlight
-     */
+    * Removes the highlight overlay from the target element.
+    * Cleans up the visual highlighting created by the highlight method.
+    *
+    * @param locator - The Playwright locator for the element to unhighlight
+    */
     private unhighlight;
     /**
-     * Attempts to fill a form field with the specified value using multiple fallback strategies.
-     * First tries the standard fill method, then falls back to click + type if needed.
-     *
-     * @param locator - The Playwright locator for the input element
-     * @param value - The text value to fill into the input field
-     */
+    * Attempts to fill a form field with the specified value using multiple fallback strategies.
+    * First tries the standard fill method, then falls back to click + type if needed.
+    *
+    * @param locator - The Playwright locator for the input element
+    * @param value - The text value to fill into the input field
+    */
     private robustFill;
     private robustTypeKeys;
     /**
-     * Performs a robust click operation using multiple fallback strategies.
-     * Attempts standard click first, then mouse click at center coordinates, and finally native DOM events.
-     *
-     * @param locator - The Playwright locator for the element to click
-     * @throws Error if all click methods fail
-     */
-    private robustClick;
-    /**
-     * Extracts text content from an element using multiple strategies.
-     * Tries textContent first, then inputValue, and finally looks for nested input elements.
-     * Returns normalized and trimmed text for consistent comparison.
-     *
-     * @param locator - The Playwright locator for the element to extract text from
-     * @returns Normalized text content with consistent whitespace handling
-     */
+    * Performs a robust mouse action (click or hover) using multiple fallback strategies.
+    * Attempts standard click first, then mouse click at center coordinates, and finally native DOM events.
+    *
+    * @param locator - The Playwright locator for the element to click
+    * @param action - The mouse action to perform ('click' or 'hover')
+    * @throws Error if all mouse action methods fail
+    */
+    private robustMouseAction;
+    /**
+    * Extracts text content from an element using multiple strategies.
+    * Tries textContent first, then inputValue, and finally looks for nested input elements.
+    * Returns normalized and trimmed text for consistent comparison.
+    *
+    * @param locator - The Playwright locator for the element to extract text from
+    * @returns Normalized text content with consistent whitespace handling
+    */
     private getTextValue;
     private setSliderValue;
 }
@@ -332,6 +370,7 @@ interface ProboConfig {
     scenarioName: string;
     token?: string;
     apiUrl?: string;
+    enableSmartSelectors?: boolean;
     enableConsoleLogs?: boolean;
     logToConsole?: boolean;
     logToFile?: boolean;
@@ -348,27 +387,44 @@ interface AskAIOptions {
     stepId?: number;
     createStep?: boolean;
 }
+
 declare class Probo {
     private highlighter;
     private apiClient;
+    private readonly debugLevel;
     private readonly enableConsoleLogs;
     private readonly scenarioName;
     private readonly aiModel;
+    private readonly enableSmartSelectors;
     private readonly timeoutConfig;
-    constructor({ scenarioName, token, apiUrl, enableConsoleLogs, logToConsole, logToFile, debugLevel, aiModel, timeoutConfig }: ProboConfig);
-    askAI(page: Page, question: string, options: AskAIOptions): Promise<any>;
-    runStep(page: Page, stepPrompt: string, argument?: string | boolean | null, options?: RunStepOptions): Promise<string | void>;
+    private params;
+    constructor({ scenarioName, token, apiUrl, enableConsoleLogs, enableSmartSelectors, logToConsole, logToFile, debugLevel, aiModel, timeoutConfig }: ProboConfig);
+    /**
+     * Sets the parameters object for template literal interpolation
+     * Stores a reference to the params object so mutations are automatically reflected
+     * @param params The parameters object containing values to use for interpolation
+     */
+    setParams(params: Record<string, any>): void;
+    /**
+     * Interpolates a string using the current params and optional additional context
+     * @param str The string to interpolate (may contain ${variable} syntax)
+     * @param additionalContext Optional additional context to merge with params
+     * @returns The interpolated string
+     */
+    private interpolate;
+    askAI(page: Page, question: string, options: AskAIOptions, assertAnswer?: string): Promise<any>;
+    runStep(page: Page, stepPrompt: string, argument?: string | boolean | null, options?: RunStepOptions): Promise<string | boolean | void>;
     private _handleCachedStep;
     private setupConsoleLogs;
     getInitialPageState(page: Page): Promise<InitialPageState>;
     findAndHighlightCandidateElements(page: Page, elementTags: string[]): Promise<FindCandidateInput>;
     highlightElements(page: Page, elementTags: [ElementTagType]): Promise<any>;
     unhighlightElements(page: Page): Promise<void>;
-    highlightElement(page: Page, element_css_selector: string, iframe_selector: string, element_index: string): Promise<void>;
+    highlightElement(page: Page, element_css_selector: string, iframe_selector: string, smart_selector: SmartSelector | null, smart_iframe_selector: SmartSelector | null, element_index: number): Promise<void>;
     waitForMutationsToSettle(page: Page, timeout?: number, initTimeout?: number): Promise<boolean>;
     screenshot(page: Page): Promise<string>;
     private _handlePerformAction;
-    askAIHelper(page: Page, question: string, options: AskAIOptions): Promise<ServerResponse>;
+    askAIHelper(page: Page, question: string, options: AskAIOptions, assertAnswer?: string): Promise<ServerResponse>;
 }
 
 export { Highlighter, NavTracker, OTP, Probo, ProboPlaywright, findClosestVisibleElement };