@probolabs/playwright 0.4.11 → 0.4.12

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/actions.d.ts

@@ -0,0 +1,24 @@
+import { Page } from 'playwright';
+export declare function waitForNavigationToSettle(page: Page, options?: {
+    initialWait?: number;
+    navigationTimeout?: number;
+    totalTimeout?: number;
+}): Promise<boolean>;
+export declare function stabilizePage(page: Page): Promise<void>;
+export declare const PlaywrightAction: {
+    readonly VISIT_BASE_URL: "VISIT_BASE_URL";
+    readonly VISIT_URL: "VISIT_URL";
+    readonly CLICK: "CLICK";
+    readonly FILL_IN: "FILL_IN";
+    readonly SELECT_DROPDOWN: "SELECT_DROPDOWN";
+    readonly SELECT_MULTIPLE_DROPDOWN: "SELECT_MULTIPLE_DROPDOWN";
+    readonly CHECK_CHECKBOX: "CHECK_CHECKBOX";
+    readonly SELECT_RADIO: "SELECT_RADIO";
+    readonly TOGGLE_SWITCH: "TOGGLE_SWITCH";
+    readonly TYPE_KEYS: "TYPE_KEYS";
+    readonly VALIDATE_EXACT_VALUE: "VALIDATE_EXACT_VALUE";
+    readonly VALIDATE_CONTAINS_VALUE: "VALIDATE_CONTAINS_VALUE";
+    readonly VALIDATE_URL: "VALIDATE_URL";
+};
+export type PlaywrightActionType = typeof PlaywrightAction[keyof typeof PlaywrightAction];
+export declare const executePlaywrightAction: (page: Page, action: PlaywrightActionType, value: string, element_css_selector: string) => Promise<boolean>;

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAS,MAAM,YAAY,CAAC;AAmMzC,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;CAcnB,CAAC;AAGX,MAAM,MAAM,oBAAoB,GAAG,OAAO,gBAAgB,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAE1F,eAAO,MAAM,uBAAuB,SAC5B,IAAI,UACF,oBAAoB,SACrB,MAAM,wBACS,MAAM,qBAiF7B,CAAA"}

package/dist/actions.js

@@ -0,0 +1,241 @@
+import { proboLogger } from './utils';
+// Utility functions for enhanced Playwright interactions
+async function handleNavigation(page, url, navigationTimeout = 5000, totalTimeout = 10000) {
+    let navigationCount = 0;
+    let lastNavigationTime = null;
+    const startTime = Date.now();
+    // Declare the function outside try block so it's accessible in finally
+    const onFrameNavigated = (frame) => {
+        if (frame === page.mainFrame()) {
+            navigationCount++;
+            lastNavigationTime = Date.now();
+            proboLogger.debug(`Navigation ${navigationCount} detected at ${lastNavigationTime}`);
+        }
+    };
+    try {
+        // Setup navigation tracking
+        page.on('framenavigated', onFrameNavigated);
+        await page.goto(url, {
+            waitUntil: 'domcontentloaded',
+            timeout: totalTimeout
+        });
+        // Final wait only for DOM, not network
+        if (navigationCount > 0) {
+            proboLogger.debug(`Total navigations detected: ${navigationCount}`);
+            await page.waitForLoadState('domcontentloaded');
+            // Add scroll to bottom to trigger lazy loading
+            await scrollToBottomRight(page);
+        }
+    }
+    finally {
+        page.removeListener('framenavigated', onFrameNavigated);
+        proboLogger.debug('Navigation listener removed');
+    }
+}
+async function enhancedClick(page, selector, options = {}) {
+    // Track initial scroll position
+    let initScrollY = await page.evaluate(() => window.scrollY);
+    let initScrollX = await page.evaluate(() => window.scrollX);
+    // Perform the click
+    await page.click(selector, { noWaitAfter: false, ...options });
+    // Monitor for any scrolling that might occur due to the click
+    let scrollingDetected = false;
+    while (true) {
+        const currScrollX = await page.evaluate(() => window.scrollX);
+        const currScrollY = await page.evaluate(() => window.scrollY);
+        if (currScrollY !== initScrollY || currScrollX !== initScrollX) {
+            proboLogger.debug('Click detected scrolling, waiting 50ms for stabilization...');
+            scrollingDetected = true;
+            await page.waitForTimeout(50);
+            initScrollX = currScrollX;
+            initScrollY = currScrollY;
+        }
+        else {
+            break;
+        }
+    }
+    // If scrolling occurred, reset to top
+    if (scrollingDetected) {
+        await page.evaluate(() => window.scrollTo(0, 0));
+        await page.waitForTimeout(50); // Small delay between scrolls
+    }
+}
+async function selectDropdownOption(page, selector, value) {
+    // Get the element's tag name
+    const locator = page.locator(selector);
+    const tagName = await locator.evaluate(el => el.tagName.toLowerCase());
+    if (tagName === 'select') {
+        // Handle native select element
+        proboLogger.debug('selectDropdownOption: simple select tag');
+        await page.selectOption(selector, value);
+    }
+    else { // not a native select
+        try {
+            // Look for child <select> if exists
+            const listboxSelector = locator.locator('select');
+            const count = await listboxSelector.count();
+            if (count === 1) { // delegate to child <select>
+                proboLogger.debug('Identified child element with tag select');
+                await listboxSelector.selectOption(value);
+            }
+            else {
+                // Click the original locator to expose the real listbox and options
+                proboLogger.debug('Clicking container element, looking for child element with role listbox');
+                await locator.click();
+                const listbox = locator.getByRole('listbox');
+                proboLogger.debug(`Clicking option ${value}`);
+                // Handle both string and array values
+                const values = Array.isArray(value) ? value : [value];
+                for (const val of values) {
+                    const optionSelector = listbox
+                        .getByRole('option')
+                        .getByText(new RegExp(`^${val.toLowerCase()}$`, 'i'));
+                    const optionCount = await optionSelector.count();
+                    if (optionCount !== 1) {
+                        throw new Error(`Found ${optionCount} option selectors for value: ${val}`);
+                    }
+                    await optionSelector.click();
+                }
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to select option '${value}' from custom dropdown: ${error}`);
+        }
+    }
+}
+async function getElementValue(page, selector) {
+    // TODO: Implement getting all text contents
+    proboLogger.log("TODO: Implement getting all text contents");
+    return "TODO: Implement getting all text contents";
+}
+async function waitForMutationsToSettle(page) {
+    // TODO: Implement mutation observer
+    //proboLogger.log("TODO: Implement mutation observer");
+    await page.waitForTimeout(500);
+}
+async function scrollToBottomRight(page) {
+    proboLogger.debug("Scrolling to bottom of page...");
+    // Get initial page dimensions
+    let lastHeight = await page.evaluate(() => document.documentElement.scrollHeight);
+    let lastWidth = await page.evaluate(() => document.documentElement.scrollWidth);
+    while (true) {
+        let smoothingSteps = 0;
+        // Get current scroll positions and dimensions
+        const initScrollY = await page.evaluate(() => window.scrollY);
+        const initScrollX = await page.evaluate(() => window.scrollX);
+        const maxScrollY = await page.evaluate(() => document.documentElement.scrollHeight);
+        const maxScrollX = await page.evaluate(() => document.documentElement.scrollWidth);
+        const maxClientY = await page.evaluate(() => document.documentElement.clientHeight);
+        const maxClientX = await page.evaluate(() => document.documentElement.clientWidth);
+        // Scroll both horizontally and vertically in steps
+        let currScrollX = initScrollX;
+        while (currScrollX <= (maxScrollX - maxClientX)) {
+            let currScrollY = initScrollY;
+            while (currScrollY <= (maxScrollY - maxClientY)) {
+                currScrollY += maxClientY;
+                await page.evaluate(({ x, y }) => window.scrollTo(x, y), { x: currScrollX, y: currScrollY });
+                await page.waitForTimeout(50); // Small delay between scrolls
+                smoothingSteps++;
+            }
+            currScrollX += maxClientX;
+        }
+        proboLogger.debug(`Performed ${smoothingSteps} smoothing steps while scrolling`);
+        // Check if content was lazy loaded (dimensions changed)
+        const newHeight = await page.evaluate(() => document.documentElement.scrollHeight);
+        const newWidth = await page.evaluate(() => document.documentElement.scrollWidth);
+        if (newHeight === lastHeight && newWidth === lastWidth) {
+            break;
+        }
+        proboLogger.debug("Page dimensions updated, repeating smoothing steps with new dimensions");
+        lastHeight = newHeight;
+        lastWidth = newWidth;
+    }
+    // Reset scroll position to top left
+    await page.waitForTimeout(200);
+    await page.evaluate(() => window.scrollTo(0, 0));
+    await page.waitForTimeout(50);
+}
+export const PlaywrightAction = {
+    VISIT_BASE_URL: 'VISIT_BASE_URL',
+    VISIT_URL: 'VISIT_URL',
+    CLICK: 'CLICK',
+    FILL_IN: 'FILL_IN',
+    SELECT_DROPDOWN: 'SELECT_DROPDOWN',
+    SELECT_MULTIPLE_DROPDOWN: 'SELECT_MULTIPLE_DROPDOWN',
+    CHECK_CHECKBOX: 'CHECK_CHECKBOX',
+    SELECT_RADIO: 'SELECT_RADIO',
+    TOGGLE_SWITCH: 'TOGGLE_SWITCH',
+    PRESS_KEY: 'PRESS_KEY',
+    VALIDATE_EXACT_VALUE: 'VALIDATE_EXACT_VALUE',
+    VALIDATE_CONTAINS_VALUE: 'VALIDATE_CONTAINS_VALUE',
+    VALIDATE_URL: 'VALIDATE_URL'
+};
+export const executePlaywrightAction = async (page, action, value, element_css_selector) => {
+    proboLogger.info('Executing playwright action:', { action, value, element_css_selector });
+    try {
+        switch (action) {
+            case PlaywrightAction.VISIT_BASE_URL:
+            case PlaywrightAction.VISIT_URL:
+                await handleNavigation(page, value);
+                break;
+            case PlaywrightAction.CLICK:
+                await enhancedClick(page, element_css_selector);
+                break;
+            case PlaywrightAction.FILL_IN:
+                await enhancedClick(page, element_css_selector);
+                await page.fill(element_css_selector, value);
+                break;
+            case PlaywrightAction.SELECT_DROPDOWN:
+                await selectDropdownOption(page, element_css_selector, value);
+                break;
+            case PlaywrightAction.SELECT_MULTIPLE_DROPDOWN:
+                const options = value.split(',').map(opt => opt.trim());
+                await selectDropdownOption(page, element_css_selector, options);
+                break;
+            case PlaywrightAction.CHECK_CHECKBOX:
+                const checked = value.toLowerCase() === 'true';
+                await page.setChecked(element_css_selector, checked);
+                break;
+            case PlaywrightAction.SELECT_RADIO:
+            case PlaywrightAction.TOGGLE_SWITCH:
+                await enhancedClick(page, element_css_selector);
+                break;
+            case PlaywrightAction.PRESS_KEY:
+                await page.press(element_css_selector, value);
+                break;
+            case PlaywrightAction.VALIDATE_EXACT_VALUE:
+                const exactValue = await getElementValue(page, element_css_selector);
+                if (exactValue !== value) {
+                    proboLogger.info(`Validation FAIL: expected ${value} but got ${exactValue}`);
+                    return false;
+                }
+                proboLogger.info('Validation PASS');
+                return true;
+            case PlaywrightAction.VALIDATE_CONTAINS_VALUE:
+                const containsValue = await getElementValue(page, element_css_selector);
+                if (!containsValue.includes(value)) {
+                    proboLogger.info(`Validation FAIL: expected ${value} to be contained in ${containsValue}`);
+                    return false;
+                }
+                proboLogger.info('Validation PASS');
+                return true;
+            case PlaywrightAction.VALIDATE_URL:
+                const currentUrl = page.url();
+                if (currentUrl !== value) {
+                    proboLogger.info(`Validation FAIL: expected url ${value} but got ${currentUrl}`);
+                    return false;
+                }
+                proboLogger.info('Validation PASS');
+                return true;
+            default:
+                throw new Error(`Unknown action: ${action}`);
+        }
+        // Wait for mutations to settle after any action
+        await waitForMutationsToSettle(page);
+        return true;
+    }
+    catch (error) {
+        proboLogger.error(`Failed to execute action ${action}:`, error);
+        throw error;
+    }
+};

package/dist/api-client.d.ts

@@ -0,0 +1,32 @@
+export interface Instruction {
+    what_to_do: string;
+    args: any;
+    result: any;
+}
+export interface CreateStepOptions {
+    stepIdFromServer?: number | null;
+    scenarioName: string;
+    stepPrompt: string;
+    initial_screenshot_url: string;
+    initial_html_content: string;
+    use_cache: boolean;
+}
+export declare class ApiError extends Error {
+    status: number;
+    data?: any | undefined;
+    constructor(status: number, message: string, data?: any | undefined);
+    toString(): string;
+}
+export declare class ApiClient {
+    private apiUrl;
+    private token;
+    private maxRetries;
+    private initialBackoff;
+    constructor(apiUrl: string, token?: string, // Default to demo token
+    maxRetries?: number, initialBackoff?: number);
+    private handleResponse;
+    private getHeaders;
+    createStep(options: CreateStepOptions): Promise<string>;
+    resolveNextInstruction(stepId: string, instruction: Instruction | null): Promise<any>;
+    uploadScreenshot(screenshot_bytes: Buffer): Promise<string>;
+}

package/dist/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,GAAG,CAAC;IACV,MAAM,EAAE,GAAG,CAAC;CACb;AAED,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;IAClB,sBAAsB,EAAE,MAAM,CAAA;IAC9B,oBAAoB,EAAE,MAAM,CAAA;IAC5B,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,qBAAa,QAAS,SAAQ,KAAK;IAExB,MAAM,EAAE,MAAM;IAEd,IAAI,CAAC,EAAE,GAAG;gBAFV,MAAM,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACR,IAAI,CAAC,EAAE,GAAG,YAAA;IASnB,QAAQ;CAGT;AAED,qBAAa,SAAS;IAElB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,cAAc;gBAHd,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAmD,EAAG,wBAAwB;IACrF,UAAU,GAAE,MAAU,EACtB,cAAc,GAAE,MAAa;YAGzB,cAAc;IA+B5B,OAAO,CAAC,UAAU;YAWJ,SAAS;IAyBjB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBvD,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,IAAI;IAatE,gBAAgB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAclE"}