@probolabs/playwright 0.4.19 → 0.4.21

package/README.md

@@ -1,136 +1,136 @@
-# Probolib: drive your playwright scripts with AI superpowers
-
-Probolib is a powerful AI-driven automation library that enhances Playwright testing and automation by making your scripts more robust and maintainable. Instead of relying on brittle CSS selectors or complex XPath expressions, Probolib uses natural language to interact with web elements.
-
-## Why Probolib?
-
-- **Natural Language Automation**: Write human-readable instructions instead of complex selectors
-- **More Resilient Tests**: AI-powered element detection that adapts to UI changes
-- **Simpler Maintenance**: Reduce the need to update selectors when the UI changes
-- **Faster Development**: Write automation scripts in plain English
-
-## Example
-
-Instead of writing:
-
-```
-page.click('some > super > complex > css > and non robust selector')
-```
-
-You can simply write:
-
-```
-probo.runStep(page, 'click on the save button')
-```
-
-## Quickstart
-
-```
-npm install @probolabs/playwright
-```
-
-## Accessing our backend
-
-the heavy lifting of the AI reasoning is done at the moment on our backend server. in order to access it you would need to tell the library how to access it.
-
-## easyiest - set ENV var
-
-probolib expects the existance of 2 env vars:
-
-```
-export PROBO_API_ENDPOINT=api.probolabs.ai
-export PROBO_API_KEY=<api key we will give you>
-
-```
-
-Or use dotenv
-
-```
-// npm install dotenv
-// in your script add this line
-import 'dotenv/config' // ES6
-
-// .env file located in the root of your project (the same level as your package.json)
-PROBO_API_ENDPOINT=https://api.probolabs.ai
-PROBO_API_KEY=<api key we will give you>
-
-```
-
-## A complete example for Playwright integration. step by step
-
-**step 1:** init a playwright project
-
-```
-# from your work directory
-mkdir probo-example
-cd probo-example
-npm init playwright@latest
-# follow the instructions and wait till the installation is finished
-# verify that playwright is installed properly
-npx playwright test --project chromium
-```
-
-**step 2**: integrate probolabs
-
-```
-npm install @probolabs/playwright dotenv
-```
-
-**step 3:** configure the env with our endpoint and api key
-
-```
-touch .env
-```
-
-edit the .env file
-
-```
-#.env
-PROBO_API_ENDPOINT=https://api.probolabs.ai
-PROBO_API_KEY=<api key we will give you>
-
-```
-
-**step 4:** create a file under the tests folder named `probo-example-todo-mvc.spec.mjs`
-
-```
-// tests/probo-example-todo-mvc.spec.mjs
-import 'dotenv/config';
-import { test} from '@playwright/test';
-import { Probo } from '@probolabs/playwright';
-
-//
-// Important: Before running this script set PROBO_API_KEY and PROBO_API_ENDPOINT
-//
-
-test.describe('Todo MVC', () => {
-  test('basic example', async ({ page }) => {
-    try {
-      // Initialize Probo
-      const probo = new Probo({
-        scenarioName: 'probo-example-todo-mvc' // important for caching the AI reasoning
-      });
-
-      //Goto page
-      await page.goto('https://demo.playwright.dev/todomvc');
-
-      // Run test steps
-      console.log('Running test steps...');
-      await probo.runStep(page, 'enter a new todo item: "Buy groceries"');
-      await probo.runStep(page, 'press the Enter key');
-
-      console.log('✨ Test completed successfully!');
-    } catch (error) {
-      console.error('❌ Test failed:', error);
-      throw error; // Re-throw to mark the test as failed
-    }
-  });
-});
-
-```
-
-**run the example**
-
-```
-npx playwright test tests/probo-example-todo-mvc.spec.mjs --headed --project chromium
-```
+# Probolib: drive your playwright scripts with AI superpowers
+
+Probolib is a powerful AI-driven automation library that enhances Playwright testing and automation by making your scripts more robust and maintainable. Instead of relying on brittle CSS selectors or complex XPath expressions, Probolib uses natural language to interact with web elements.
+
+## Why Probolib?
+
+- **Natural Language Automation**: Write human-readable instructions instead of complex selectors
+- **More Resilient Tests**: AI-powered element detection that adapts to UI changes
+- **Simpler Maintenance**: Reduce the need to update selectors when the UI changes
+- **Faster Development**: Write automation scripts in plain English
+
+## Example
+
+Instead of writing:
+
+```
+page.click('some > super > complex > css > and non robust selector')
+```
+
+You can simply write:
+
+```
+probo.runStep(page, 'click on the save button')
+```
+
+## Quickstart
+
+```
+npm install @probolabs/playwright
+```
+
+## Accessing our backend
+
+the heavy lifting of the AI reasoning is done at the moment on our backend server. in order to access it you would need to tell the library how to access it.
+
+## easyiest - set ENV var
+
+probolib expects the existance of 2 env vars:
+
+```
+export PROBO_API_ENDPOINT=api.probolabs.ai
+export PROBO_API_KEY=<api key we will give you>
+
+```
+
+Or use dotenv
+
+```
+// npm install dotenv
+// in your script add this line
+import 'dotenv/config' // ES6
+
+// .env file located in the root of your project (the same level as your package.json)
+PROBO_API_ENDPOINT=https://api.probolabs.ai
+PROBO_API_KEY=<api key we will give you>
+
+```
+
+## A complete example for Playwright integration. step by step
+
+**step 1:** init a playwright project
+
+```
+# from your work directory
+mkdir probo-example
+cd probo-example
+npm init playwright@latest
+# follow the instructions and wait till the installation is finished
+# verify that playwright is installed properly
+npx playwright test --project chromium
+```
+
+**step 2**: integrate probolabs
+
+```
+npm install @probolabs/playwright dotenv
+```
+
+**step 3:** configure the env with our endpoint and api key
+
+```
+touch .env
+```
+
+edit the .env file
+
+```
+#.env
+PROBO_API_ENDPOINT=https://api.probolabs.ai
+PROBO_API_KEY=<api key we will give you>
+
+```
+
+**step 4:** create a file under the tests folder named `probo-example-todo-mvc.spec.mjs`
+
+```
+// tests/probo-example-todo-mvc.spec.mjs
+import 'dotenv/config';
+import { test} from '@playwright/test';
+import { Probo } from '@probolabs/playwright';
+
+//
+// Important: Before running this script set PROBO_API_KEY and PROBO_API_ENDPOINT
+//
+
+test.describe('Todo MVC', () => {
+  test('basic example', async ({ page }) => {
+    try {
+      // Initialize Probo
+      const probo = new Probo({
+        scenarioName: 'probo-example-todo-mvc' // important for caching the AI reasoning
+      });
+
+      //Goto page
+      await page.goto('https://demo.playwright.dev/todomvc');
+
+      // Run test steps
+      console.log('Running test steps...');
+      await probo.runStep(page, 'enter a new todo item: "Buy groceries"');
+      await probo.runStep(page, 'press the Enter key');
+
+      console.log('✨ Test completed successfully!');
+    } catch (error) {
+      console.error('❌ Test failed:', error);
+      throw error; // Re-throw to mark the test as failed
+    }
+  });
+});
+
+```
+
+**run the example**
+
+```
+npx playwright test tests/probo-example-todo-mvc.spec.mjs --headed --project chromium
+```

package/dist/index.d.ts

@@ -1,15 +1,24 @@
-import { Page } from 'playwright';
-import { PlaywrightAction, ElementTag, ProboLogLevel } from '@probolabs/probo-shared';
+import { Page, Locator } from 'playwright';
+import { PlaywrightAction, ElementTag, PlaywrightTimeoutConfig, AIModel, ServerResponse, ProboLogLevel } from '@probolabs/probo-shared';
 export { ElementInfo, ElementTag, PlaywrightAction, ProboLogLevel } from '@probolabs/probo-shared';
+import { Page as Page$1 } from '@playwright/test';
 
 /**
  * Execute a given Playwright action, mirroring Python's _perform_action
  */
-declare function executePlaywrightAction(page: Page, action: PlaywrightAction, value: string, iframe_selector: string, element_css_selector: string): Promise<boolean>;
+declare function executePlaywrightAction(page: Page, action: PlaywrightAction, value: string | boolean, iframe_selector: string, element_css_selector: string): Promise<boolean | string>;
 /**
  * Execute a given Playwright action using native Playwright functions where possible
  */
-declare function executeCachedPlaywrightAction(page: Page, action: PlaywrightAction, value: string, iframe_selector: string, element_css_selector: string): Promise<boolean>;
+declare function executeCachedPlaywrightAction(page: Page, action: PlaywrightAction, value: string | boolean, iframe_selector: string, element_css_selector: string): Promise<boolean | string>;
+/**
+   * Traverses up the DOM from the given locator to find the closest visible ancestor.
+   * Returns a Locator for the first visible element found, or null if none is visible up to <html>.
+   *
+   * @param locator - The Playwright locator to start searching from
+   * @returns Promise that resolves to a visible ancestor locator or null if none found
+   */
+declare function findClosestVisibleElement(locator: Locator): Promise<Locator | null>;
 
 type ElementTagType = typeof ElementTag[keyof typeof ElementTag];
 declare global {
@@ -87,22 +96,79 @@ declare class Highlighter {
     getMatchingCandidateCached(page: Page): Promise<any>;
 }
 
-/**
- * Available AI models for LLM operations
- */
-declare enum AIModel {
-    AZURE_GPT4 = "AZURE_GPT4",
-    AZURE_GPT4_MINI = "AZURE_GPT4_MINI",
-    GEMINI_1_5_FLASH = "GEMINI_1_5_FLASH",
-    GEMINI_2_5_FLASH = "GEMINI_2_5_FLASH",
-    GPT4 = "GPT4",
-    GPT4_MINI = "GPT4_MINI",
-    CLAUDE_3_5 = "CLAUDE_3_5",
-    GROK_2 = "GROK_2",
-    LLAMA_4_SCOUT = "LLAMA_4_SCOUT",
-    DEEPSEEK_V3 = "DEEPSEEK_V3",
-    DEFAULT_AI_MODEL = "DEFAULT_AI_MODEL"
+interface RunStepParams extends Partial<PlaywrightTimeoutConfig> {
+    iframeSelector?: string;
+    elementSelector?: string;
+    action: PlaywrightAction | PlaywrightAction[] | string | string[];
+    argument?: string | string[];
+    annotation?: string;
+}
+interface RunStepResult {
+    key: string;
+    value: any;
+}
+declare class ProboPlaywright {
+    private readonly config;
+    private page;
+    constructor(config?: PlaywrightTimeoutConfig, 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.
+     */
+    setPage(page: Page$1 | null): void;
+    /**
+     * 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
+     */
+    runStep(params: RunStepParams): Promise<RunStepResult | void>;
+    /**
+     * 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
+     */
+    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
+     */
+    private robustFill;
+    /**
+     * 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
+     */
+    private getTextValue;
 }
+
 /**
  * Configuration options for Probo client
  */
@@ -128,16 +194,19 @@ declare class Probo {
     private readonly scenarioName;
     private readonly aiModel;
     constructor({ scenarioName, token, apiUrl, enableConsoleLogs, logToConsole, logToFile, debugLevel, aiModel }: ProboConfig);
-    runStep(page: Page, stepPrompt: string, argument?: string | null, options?: RunStepOptions): Promise<boolean>;
+    askAI(page: Page, question: string): Promise<any>;
+    runStep(page: Page, stepPrompt: string, argument?: string | boolean | null, options?: RunStepOptions): Promise<boolean | string>;
     private _handleCachedStep;
     private _handleStepCreation;
     private setupConsoleLogs;
     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>;
+    waitForMutationsToSettle(page: Page, timeout?: number, initTimeout?: number): Promise<boolean>;
     screenshot(page: Page): Promise<string>;
     private _handlePerformAction;
+    askAIHelper(page: Page, question: string): Promise<ServerResponse>;
 }
 
-export { AIModel, Highlighter, Probo, executeCachedPlaywrightAction, executePlaywrightAction };
+export { Highlighter, Probo, ProboPlaywright, executeCachedPlaywrightAction, executePlaywrightAction, findClosestVisibleElement };
 export type { ElementTagType, RunStepOptions };