@wix-pilot/webdriverio-appium 1.0.1 → 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";
@@ -99,31 +106,49 @@ class WebdriverIOAppiumFrameworkDriver {
                             signature: `$('~accessibilityId')`,
                             description: "Locate an element by its accessibility ID (commonly used in Appium).",
                             example: `const loginButton = await $('~loginButton'); // Accessibility ID`,
+                            guidelines: [
+                                "Always prefer using test IDs when available; if no ID is present, use another stable identifier.",
+                            ],
                         },
                         {
                             signature: `$('android=uiSelector')`,
                             description: "Locate an element using an Android UIAutomator selector.",
                             example: `const el = await $('android=new UiSelector().text("Login")');`,
+                            guidelines: [
+                                "For Android, use UIAutomator selectors to target elements by text, resource-id, or other properties. Ensure selectors are precise to avoid ambiguity.",
+                            ],
                         },
                         {
                             signature: `$('ios=predicateString')`,
                             description: "Locate an element using an iOS NSPredicate string.",
                             example: `const el = await $('ios=predicate string:type == "XCUIElementTypeButton" AND name == "Login"');`,
+                            guidelines: [
+                                "For iOS, use NSPredicate strings to define clear and concise conditions for element identification. Validate the predicate to ensure it uniquely identifies the element.",
+                            ],
                         },
                         {
                             signature: `$$('#elementSelector')`,
                             description: "Locate all elements with a given selector",
                             example: `const firstSite = await $$('#Site')[index];`,
+                            guidelines: [
+                                "Use this to select multiple elements. Make sure your selector targets a specific subset of elements to avoid excessive matches.",
+                            ],
                         },
                         {
                             signature: `$('//*[@text="Login"]')`,
                             description: "Locate an element using an XPath expression.",
                             example: `const el = await $('//*[@text="Login"]');`,
+                            guidelines: [
+                                "Use XPath as a last resort when other selectors are not available, as XPath can be slower and more brittle. Ensure your XPath expression is optimized for performance.",
+                            ],
                         },
                         {
                             signature: `$('#elementId'), $('elementTag'), $('.className')`,
                             description: "Web-like selectors (useful if your app is a hybrid or has a web context).",
                             example: `const el = await $('.someNativeClass');`,
+                            guidelines: [
+                                "Use web-like selectors in hybrid apps or web contexts. Ensure selectors are unique and adhere to best practices for CSS selectors.",
+                            ],
                         },
                     ],
                 },
@@ -136,6 +161,9 @@ class WebdriverIOAppiumFrameworkDriver {
                             example: `
               await (await $('~loginButton')).waitForEnabled();
               await (await $('~loginButton')).click();`,
+                            guidelines: [
+                                "Allways use await (await $('~element')).waitForEnabled() before clicking on the element",
+                            ],
                         },
                         {
                             signature: `.setValue(value: string)`,
@@ -163,11 +191,6 @@ await (await $('~dragHandle')).touchAction([
 ]);
               `,
                         },
-                        {
-                            signature: `.scrollIntoView() (web/hybrid context only)`,
-                            description: "Scrolls the element into view (if in a web context).",
-                            example: `await (await $('#someElement')).scrollIntoView();`,
-                        },
                         {
                             signature: `.dragAndDrop(target, duration?)`,
                             description: "Drags the element to the target location (native or web context).",
@@ -187,31 +210,55 @@ await (await $('~draggable')).dragAndDrop(
                             signature: `toBeDisplayed()`,
                             description: "Asserts that the element is displayed (visible).",
                             example: `await expect(await $('~loginButton')).toBeDisplayed();`,
+                            guidelines: [
+                                "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.",
                             example: `await expect(await $('~usernameInput')).toExist();`,
+                            guidelines: [
+                                "Use this matcher to check that the element exists in the DOM or view hierarchy.",
+                            ],
                         },
                         {
                             signature: `toHaveText(text: string)`,
                             description: "Asserts that the element's text matches the given string.",
                             example: `await expect(await $('~welcomeMessage')).toHaveText('Welcome, user!');`,
+                            guidelines: [
+                                "Use this matcher to verify the text content of an element exactly matches the expected value.",
+                            ],
                         },
                         {
                             signature: `toHaveValue(value: string)`,
                             description: "Asserts that the element's value matches the given string (for inputs, etc.).",
                             example: `await expect(await $('~usernameInput')).toHaveValue('myusername');`,
+                            guidelines: [
+                                "Use this matcher for form elements to verify that the input value is correct.",
+                            ],
                         },
                         {
                             signature: `toBeEnabled() / toBeDisabled()`,
                             description: "Asserts that an element is enabled/disabled (if applicable).",
                             example: `await expect(await $('~submitButton')).toBeEnabled();`,
+                            guidelines: [
+                                "Use these matchers to assert that an element is enabled or disabled as required by the test scenario.",
+                            ],
                         },
                         {
                             signature: `not`,
                             description: "Negates the expectation.",
                             example: `await expect(await $('~spinner')).not.toBeDisplayed();`,
+                            guidelines: [
+                                "Use this matcher to invert the condition of any expectation, ensuring the element does not meet the specified criteria.",
+                            ],
                         },
                     ],
                 },
@@ -270,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
 });
               `,
                         },
@@ -331,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/dist/wdio.conf.d.ts

@@ -0,0 +1,28 @@
+export declare const config: {
+    runner: string;
+    specs: string[];
+    maxInstances: number;
+    capabilities: {
+        platformName: string;
+        deviceName: string;
+        automationName: string;
+        app: string;
+    }[];
+    logLevel: string;
+    bail: number;
+    baseUrl: string;
+    waitforTimeout: number;
+    connectionRetryTimeout: number;
+    connectionRetryCount: number;
+    services: string[];
+    appium: {
+        command: string;
+    };
+    framework: string;
+    reporters: string[];
+    mochaOpts: {
+        ui: string;
+        timeout: number;
+    };
+    before: () => void;
+};

package/dist/wdio.conf.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+// wdio.conf.ts
+exports.config = {
+    runner: 'local',
+    specs: ['./examples/**/*.test.ts'],
+    maxInstances: 1,
+    capabilities: [{
+            platformName: 'iOS',
+            deviceName: 'iPhone 14',
+            automationName: 'XCUITest',
+            app: './Users/tzviels/Library/Developer/Xcode/DerivedData/ExampleApp-ccggovixskkojadmtpriqiridvii/Build/Products/Debug-iphonesimulator/ExampleApp.app',
+        }],
+    logLevel: 'info',
+    bail: 0,
+    baseUrl: 'http://localhost',
+    waitforTimeout: 10000,
+    connectionRetryTimeout: 90000,
+    connectionRetryCount: 3,
+    services: ['appium'],
+    appium: {
+        command: 'appium',
+    },
+    framework: 'mocha',
+    reporters: ['spec'],
+    mochaOpts: {
+        ui: 'bdd',
+        timeout: 60000,
+    },
+    before: function () {
+        global.driver = browser;
+    },
+};

package/package.json

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