@wix-pilot/webdriverio-appium 1.0.2 → 1.0.3

package/README.md

@@ -0,0 +1,77 @@
+# @wix-pilot/appium 📱
+
+> Appium driver for Wix Pilot - Cross-platform mobile testing with natural language
+
+## Overview
+
+The `@wix-pilot/webdriverio-appium` package provides Appium integration for Wix Pilot, enabling:
+- Native iOS and Android app testing
+- Hybrid app testing
+- Mobile web testing
+- Cross-platform test automation
+
+## Installation
+
+```bash
+# npm
+npm install --save-dev @wix-pilot/webdriverio-appium webdriverio @wix-pilot/core
+
+# yarn
+yarn add -D @wix-pilot/webdriverio-appium webdriverio @wix-pilot/core
+```
+
+## Usage
+
+### 1. Set up your LLM Handler
+```typescript
+import { PromptHandler } from '@wix-pilot/core';
+
+class CustomPromptHandler implements PromptHandler {
+  async runPrompt(prompt: string, image?: string): Promise<string> {
+    // Integrate with your preferred LLM service
+    const response = await yourLLMService.complete({
+      prompt,
+      imageUrl: image, // Optional: for visual testing support
+    });
+    return response.text;
+  }
+
+  isSnapshotImageSupported(): boolean {
+    return true; // Set to true if your LLM supports image analysis
+  }
+}
+```
+
+### 2. Create and Run Tests
+```typescript
+import pilot from '@wix-pilot/core';
+import { WebdriverIOAppiumFrameworkDriver } from '@wix-pilot/webdriverio-appium';
+
+describe('Mobile App Testing', () => {
+  beforeAll(async () => {
+    pilot.init({
+      driver: new WebdriverIOAppiumFrameworkDriver(),
+      promptHandler: new CustomPromptHandler(),
+    });
+  });
+
+  beforeEach(() => pilot.start());
+  afterEach(() => pilot.end());
+
+  it('should handle shopping cart flow', async () => {
+    await pilot.perform([
+      'Launch the app',
+      'Allow any permission prompts',
+      'Tap the "Products" tab',
+      'Scroll to "Wireless Headphones"',
+      'Add item to cart',
+      'The cart badge should show "1"'
+    ]);
+  });
+});
+```
+
+## Related Packages
+
+- [@wix-pilot/core](../../core) - Core Wix Pilot engine
+- [@wix-pilot/detox](../detox) - Alternative React Native testing driver

package/dist/examples/example.test.js

@@ -1,28 +1,26 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-const core_1 = __importDefault(require("@wix-pilot/core"));
+const core_1 = require("@wix-pilot/core");
 const promptHandler_1 = require("../utils/promptHandler");
 const index_1 = require("../index");
 describe("Example Test Suite", () => {
     let frameworkDriver;
+    let pilot;
     before(async () => {
         const promptHandler = new promptHandler_1.PromptHandler();
         frameworkDriver = new index_1.WebdriverIOAppiumFrameworkDriver();
-        core_1.default.init({
+        pilot = new core_1.Pilot({
             frameworkDriver,
             promptHandler,
         });
     });
     beforeEach(async () => {
-        core_1.default.start();
+        pilot.start();
     });
     afterEach(async () => {
-        core_1.default.end();
+        pilot.end();
     });
     it("perform test with pilot", async () => {
-        await core_1.default.autopilot("earn 2 points in the game");
+        await pilot.autopilot("earn 2 points in the game");
     });
 });

package/dist/index.d.ts

@@ -1,6 +1,12 @@
-import { TestingFrameworkAPICatalog, TestingFrameworkDriver } from "@wix-pilot/core";
+import { TestingFrameworkAPICatalog, TestingFrameworkDriver, TestingFrameworkDriverConfig } from "@wix-pilot/core";
 export declare class WebdriverIOAppiumFrameworkDriver implements TestingFrameworkDriver {
     constructor();
+    /**
+     * Additional driver configuration.
+     *
+     * @property useSnapshotStabilitySync - Indicates whether the driver should use wait for screen stability.
+     */
+    get driverConfig(): TestingFrameworkDriverConfig;
     /**
      * Attempts to capture the current view hierarchy (source) of the mobile app as XML.
      * If there's no active session or the app isn't running, returns an error message.

package/dist/index.js

@@ -36,18 +36,25 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebdriverIOAppiumFrameworkDriver = void 0;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const getStableViewHierarchy_1 = require("./utils/getStableViewHierarchy");
 class WebdriverIOAppiumFrameworkDriver {
     constructor() { }
+    /**
+     * Additional driver configuration.
+     *
+     * @property useSnapshotStabilitySync - Indicates whether the driver should use wait for screen stability.
+     */
+    get driverConfig() {
+        return { useSnapshotStabilitySync: true };
+    }
     /**
      * Attempts to capture the current view hierarchy (source) of the mobile app as XML.
      * If there's no active session or the app isn't running, returns an error message.
      */
     async captureViewHierarchyString() {
         try {
-            // In WebdriverIO + Appium, you can retrieve the current page source (UI hierarchy) via:
-            // https://webdriver.io/docs/api/browser/getPageSource (driver is an alias for browser)
-            const pageSource = await driver.getPageSource();
-            return pageSource;
+            const result = await (0, getStableViewHierarchy_1.waitForStableState)();
+            return result ?? "";
         }
         catch (_error) {
             return "NO ACTIVE APP FOUND, LAUNCH THE APP TO SEE THE VIEW HIERARCHY";
@@ -155,7 +162,7 @@ class WebdriverIOAppiumFrameworkDriver {
               await (await $('~loginButton')).waitForEnabled();
               await (await $('~loginButton')).click();`,
                             guidelines: [
-                                "Before clicking on an element make sure it is enabled",
+                                "Allways use await (await $('~element')).waitForEnabled() before clicking on the element",
                             ],
                         },
                         {
@@ -207,6 +214,12 @@ await (await $('~draggable')).dragAndDrop(
                                 "Use this matcher to verify that the element is visible to the user.",
                             ],
                         },
+                        {
+                            signature: `.waitForEnabled()`,
+                            description: "Waits until the element is enabled and ready to be clicked",
+                            example: `await (await $('~usernameInput')).waitForEnabled();`,
+                            guidelines: ["Allways use this before clicking on an element"],
+                        },
                         {
                             signature: `toExist()`,
                             description: "Asserts that the element exists in the DOM/hierarchy.",
@@ -304,29 +317,6 @@ await driver.setGeoLocation({
   latitude: 37.7749,
   longitude: -122.4194,
   altitude: 10
-});
-              `,
-                        },
-                        {
-                            signature: `driver.getContext() / driver.switchContext(name: string)`,
-                            description: "Gets or switches the current context (NATIVE_APP or WEBVIEW_xxx).",
-                            example: `
-const contexts = await driver.getContexts();
-await driver.switchContext(contexts[1]); // Switch to webview
-await driver.switchContext('NATIVE_APP'); // Switch back
-              `,
-                        },
-                        {
-                            signature: `driver.rotate(params: { x: number; y: number; duration: number; radius: number; rotation: number; touchCount: number })`,
-                            description: "Simulates a rotation gesture on the device (iOS only).",
-                            example: `
-await driver.rotate({
-  x: 100,
-  y: 100,
-  duration: 2,
-  radius: 50,
-  rotation: 180,
-  touchCount: 2
 });
               `,
                         },
@@ -365,49 +355,6 @@ await driver.performTouchAction({
                         },
                     ],
                 },
-                {
-                    title: "Web APIs (Hybrid / Mobile Web)",
-                    items: [
-                        {
-                            signature: `driver.switchContext('WEBVIEW')`,
-                            description: "Switches the context from native to web view (if a webview is present).",
-                            example: `
-const contexts = await driver.getContexts();
-await driver.switchContext(contexts.find(c => c.includes('WEBVIEW')));
-              `,
-                            guidelines: [
-                                "Use this when your app has a webview or is a hybrid app.",
-                            ],
-                        },
-                        {
-                            signature: `$('css or xpath').click()`,
-                            description: "In a webview context, click (tap) a web element using CSS or XPath.",
-                            example: `await (await $('button#login')).click();`,
-                        },
-                        {
-                            signature: `$('selector').setValue('text')`,
-                            description: "In a webview context, sets text in a web input field.",
-                            example: `await (await $('input#username')).setValue('myusername');`,
-                        },
-                        {
-                            signature: `.getText()`,
-                            description: "Retrieves the visible text of a web element (hybrid/web context).",
-                            example: `
-const text = await (await $('h1.main-title')).getText();
-expect(text).toBe('Welcome to My App');
-              `,
-                        },
-                        {
-                            signature: `driver.executeScript(script: string, args?: any[])`,
-                            description: "Executes JavaScript in the context of the webview.",
-                            example: `
-await driver.executeScript("document.getElementById('hidden-button').click()");
-const title = await driver.executeScript('return document.title');
-expect(title).toBe('My Page Title');
-              `,
-                        },
-                    ],
-                },
             ],
         };
     }

package/dist/utils/getStableViewHierarchy.d.ts

@@ -0,0 +1,3 @@
+/** Waits till the view hierarchy is stable than returns it*/
+export declare function waitForStableState(pollInterval?: number, timeout?: number): Promise<string | undefined>;
+export declare function compareViewHierarchies(current: string, last: string): boolean;

package/dist/utils/getStableViewHierarchy.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitForStableState = waitForStableState;
+exports.compareViewHierarchies = compareViewHierarchies;
+const crypto_1 = __importDefault(require("crypto"));
+const DEFAULT_POLL_INTERVAL = 500; // ms
+const DEFAULT_TIMEOUT = 5000; // ms
+/** Waits till the view hierarchy is stable than returns it*/
+async function waitForStableState(pollInterval = DEFAULT_POLL_INTERVAL, timeout = DEFAULT_TIMEOUT) {
+    const startTime = Date.now();
+    let lastSnapshot;
+    while (Date.now() - startTime < timeout) {
+        const currentSnapshot = (await driver.getPageSource()) || "";
+        if (!currentSnapshot) {
+            return undefined;
+        }
+        if (lastSnapshot) {
+            const isStable = compareViewHierarchies(currentSnapshot, lastSnapshot);
+            if (isStable) {
+                return currentSnapshot;
+            }
+        }
+        lastSnapshot = currentSnapshot;
+        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+    // Return the last snapshot if timeout is reached
+    return lastSnapshot;
+}
+function compareViewHierarchies(current, last) {
+    // Use MD5 for fast comparison of view hierarchies
+    const currentHash = crypto_1.default.createHash("md5").update(current).digest("hex");
+    const lastHash = crypto_1.default.createHash("md5").update(last).digest("hex");
+    return currentHash === lastHash;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix-pilot/webdriverio-appium",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "WebdriverIO and Appium driver for Wix Pilot usage",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",