@wix-pilot/webdriverio-appium 1.0.2 → 1.0.4

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.
@@ -10,7 +16,7 @@ export declare class WebdriverIOAppiumFrameworkDriver implements TestingFramewor
      * Captures a screenshot of the current device screen and saves it to a temp directory.
      * Returns the path to the saved screenshot if successful, or undefined otherwise.
      */
-    captureSnapshotImage(): Promise<string | undefined>;
+    captureSnapshotImage(_: boolean): Promise<string | undefined>;
     /**
      * Returns the API catalog describing the testing capabilities
      * (matchers, actions, assertions, device/system APIs, etc.)

package/dist/index.js

@@ -32,22 +32,33 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 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");
+const os_1 = __importDefault(require("os"));
 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";
@@ -57,8 +68,8 @@ class WebdriverIOAppiumFrameworkDriver {
      * Captures a screenshot of the current device screen and saves it to a temp directory.
      * Returns the path to the saved screenshot if successful, or undefined otherwise.
      */
-    async captureSnapshotImage() {
-        const tempDir = "temp";
+    async captureSnapshotImage(_) {
+        const tempDir = path.resolve(os_1.default.tmpdir(), "pilot-snapshot");
         if (!fs.existsSync(tempDir)) {
             fs.mkdirSync(tempDir);
         }
@@ -155,7 +166,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 +218,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 +321,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 +359,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.4",
   "description": "WebdriverIO and Appium driver for Wix Pilot usage",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,12 +19,9 @@
     "test": "echo No tests available for this package",
     "test:example": "wdio run examples/wdio.conf.ts",
     "build:app": "cd ../detox/ExampleApp &&  npm run build:ios",
-    "bump-version:patch": "npm version patch && git commit -am 'chore: bump patch version' && git push",
-    "release:patch": "npm run test && npm run bump-version:patch && npm run build && npm publish --access public",
-    "bump-version:minor": "npm version minor && git commit -am 'chore: bump minor version' && git push",
-    "release:minor": "npm run test && npm run bump-version:minor && npm run build && npm publish --access public",
-    "bump-version:major": "npm version major && git commit -am 'chore: bump major version' && git push",
-    "release:major": "npm run test && npm run bump-version:major && npm run build && npm publish --access public",
+    "release:patch": "node ../../../scripts/release-package.js patch",
+    "release:minor": "node ../../../scripts/release-package.js minor",
+    "release:major": "node ../../../scripts/release-package.js major",
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "type-check": "tsc --noEmit"
@@ -32,11 +29,9 @@
   "bugs": {
     "url": "https://github.com/wix-incubator/pilot/issues"
   },
-  "dependencies": {
-    "@wix-pilot/core": "^2.0.0"
-  },
   "peerDependencies": {
-    "@wdio/globals": ">=8.0.0"
+    "@wdio/globals": ">=8.0.0",
+    "@wix-pilot/core": "^3.1.6"
   },
   "devDependencies": {
     "@wdio/globals": "^9.9.1",

package/dist/wdio.conf.d.ts

@@ -1,28 +0,0 @@
-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

@@ -1,34 +0,0 @@
-"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;
-    },
-};