playwright-automation-core 1.0.0

package/dist/mobile/mobile.driver.js

@@ -0,0 +1,808 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MobileDriver = exports.AppState = void 0;
+const webdriverio_1 = require("webdriverio");
+const types_1 = require("../types");
+const base_driver_1 = require("../core/base.driver");
+const hook_manager_1 = require("../core/hook.manager");
+const utils_1 = require("../utils");
+/**
+ * App state enum
+ */
+var AppState;
+(function (AppState) {
+    AppState[AppState["NOT_INSTALLED"] = 0] = "NOT_INSTALLED";
+    AppState[AppState["NOT_RUNNING"] = 1] = "NOT_RUNNING";
+    AppState[AppState["RUNNING_BACKGROUND_SUSPENDED"] = 2] = "RUNNING_BACKGROUND_SUSPENDED";
+    AppState[AppState["RUNNING_BACKGROUND"] = 3] = "RUNNING_BACKGROUND";
+    AppState[AppState["RUNNING_FOREGROUND"] = 4] = "RUNNING_FOREGROUND";
+})(AppState || (exports.AppState = AppState = {}));
+/**
+ * Mobile Driver implementation using WebdriverIO with Appium.
+ * Supports both Android and iOS platforms.
+ */
+class MobileDriver extends base_driver_1.BaseDriver {
+    /** WebdriverIO browser/driver instance */
+    driver = null;
+    /** Mobile-specific configuration */
+    config;
+    /** Hook manager */
+    hooks;
+    /** Current context (NATIVE_APP or WEBVIEW_xxx) */
+    currentContext = "NATIVE_APP";
+    /**
+     * Create a new MobileDriver instance
+     */
+    constructor(config, logger) {
+        super(types_1.Platform.MOBILE, config, logger);
+        this.config = config;
+        this.hooks = (0, hook_manager_1.getHookManager)();
+    }
+    /**
+     * Initialize the mobile driver
+     */
+    async initialize() {
+        if (this.initialized) {
+            this.logger.warn("MobileDriver already initialized");
+            return;
+        }
+        // Execute before init hooks
+        await this.hooks.execute(hook_manager_1.HookEvent.BEFORE_DRIVER_INIT, {
+            platform: this.platform,
+            data: { config: this.getSafeConfig() },
+        });
+        try {
+            this.logger.info("Initializing MobileDriver", {
+                mobilePlatform: this.config.platform,
+                deviceName: this.config.deviceName,
+            });
+            // Build capabilities
+            const capabilities = this.buildCapabilities();
+            // Create WebdriverIO remote session
+            this.driver = await (0, webdriverio_1.remote)({
+                hostname: this.config.appiumHost || "localhost",
+                port: this.config.appiumPort || 4723,
+                path: this.config.appiumPath || "/wd/hub",
+                capabilities,
+                logLevel: "warn",
+                connectionRetryTimeout: this.config.timeout || 60000,
+                connectionRetryCount: 3,
+            });
+            // Generate session ID and mark initialized
+            this.generateSessionId();
+            this.markInitialized();
+            // Execute after init hooks
+            await this.hooks.execute(hook_manager_1.HookEvent.AFTER_DRIVER_INIT, {
+                platform: this.platform,
+                driverStatus: this.getStatus(),
+                data: {
+                    mobilePlatform: this.config.platform,
+                    deviceName: this.config.deviceName,
+                },
+            });
+        }
+        catch (error) {
+            const err = error;
+            this.logger.error("Failed to initialize MobileDriver", {
+                error: err.message,
+            });
+            throw new utils_1.DriverInitializationError(this.platform, `Failed to initialize mobile driver: ${err.message}`, {
+                mobilePlatform: this.config.platform,
+                deviceName: this.config.deviceName,
+            });
+        }
+    }
+    /**
+     * Build Appium capabilities from configuration
+     */
+    buildCapabilities() {
+        const isIOS = this.config.platform === types_1.MobilePlatform.IOS;
+        const caps = {
+            platformName: isIOS ? "iOS" : "Android",
+            "appium:deviceName": this.config.deviceName,
+            "appium:automationName": this.config.automationName || (isIOS ? "XCUITest" : "UiAutomator2"),
+            "appium:newCommandTimeout": this.config.newCommandTimeout || 300,
+        };
+        // Add app capability
+        if (this.config.app) {
+            caps["appium:app"] = this.config.app;
+        }
+        // Platform-specific capabilities
+        if (isIOS) {
+            if (this.config.platformVersion) {
+                caps["appium:platformVersion"] = this.config.platformVersion;
+            }
+            if (this.config.udid) {
+                caps["appium:udid"] = this.config.udid;
+            }
+            if (this.config.bundleId) {
+                caps["appium:bundleId"] = this.config.bundleId;
+            }
+        }
+        else {
+            // Android
+            if (this.config.appPackage) {
+                caps["appium:appPackage"] = this.config.appPackage;
+            }
+            if (this.config.appActivity) {
+                caps["appium:appActivity"] = this.config.appActivity;
+            }
+            if (this.config.avd) {
+                caps["appium:avd"] = this.config.avd;
+            }
+        }
+        // Additional capabilities
+        if (this.config.noReset !== undefined) {
+            caps["appium:noReset"] = this.config.noReset;
+        }
+        if (this.config.fullReset !== undefined) {
+            caps["appium:fullReset"] = this.config.fullReset;
+        }
+        // Merge additional capabilities
+        if (this.config.additionalCapabilities) {
+            Object.assign(caps, this.config.additionalCapabilities);
+        }
+        return caps;
+    }
+    /**
+     * Get the underlying WebdriverIO driver
+     */
+    getDriver() {
+        this.ensureInitialized("getDriver");
+        return this.driver;
+    }
+    /**
+     * Get browser (alias for getDriver to match interface)
+     */
+    getBrowser() {
+        return this.getDriver();
+    }
+    // ============ Element Finding ============
+    /**
+     * Find element using locator
+     */
+    async findElement(locator) {
+        this.ensureInitialized("findElement");
+        const selector = this.buildSelector(locator);
+        return await this.driver.$(selector);
+    }
+    /**
+     * Find multiple elements using locator
+     */
+    async findElements(locator) {
+        this.ensureInitialized("findElements");
+        const selector = this.buildSelector(locator);
+        const elements = await this.driver.$$(selector);
+        // Convert ElementArray to regular array
+        return Array.from(elements);
+    }
+    /**
+     * Build selector string from locator
+     */
+    buildSelector(locator) {
+        if (typeof locator === "string") {
+            return locator;
+        }
+        const isIOS = this.config.platform === types_1.MobilePlatform.IOS;
+        switch (locator.strategy) {
+            case "accessibility":
+                return `~${locator.value}`;
+            case "id":
+                return isIOS
+                    ? `~${locator.value}`
+                    : `android=new UiSelector().resourceId("${locator.value}")`;
+            case "xpath":
+                return locator.value;
+            case "class":
+                return isIOS
+                    ? `-ios class chain:**/${locator.value}`
+                    : `android=new UiSelector().className("${locator.value}")`;
+            case "name":
+                return isIOS
+                    ? `-ios predicate string:name == "${locator.value}"`
+                    : `android=new UiSelector().text("${locator.value}")`;
+            case "text":
+                return isIOS
+                    ? `-ios predicate string:label == "${locator.value}"`
+                    : `android=new UiSelector().text("${locator.value}")`;
+            default:
+                return locator.value;
+        }
+    }
+    // ============ Element Actions ============
+    /**
+     * Click on element
+     */
+    async click(locator, _options) {
+        this.ensureInitialized("click");
+        const description = typeof locator === "string" ? locator : locator.value;
+        this.logger.elementAction("click", description);
+        const element = await this.findElement(locator);
+        await element.click();
+    }
+    /**
+     * Tap at coordinates
+     */
+    async tap(x, y) {
+        this.ensureInitialized("tap");
+        this.logger.debug(`Tap at coordinates: (${x}, ${y})`);
+        await this.driver.action("pointer", {
+            parameters: { pointerType: "touch" },
+        })
+            .move({ x, y })
+            .down()
+            .up()
+            .perform();
+    }
+    /**
+     * Tap on element (convenience method)
+     */
+    async tapElement(locator) {
+        await this.click(locator);
+    }
+    /**
+     * Double tap on element
+     */
+    async doubleTap(locator) {
+        this.ensureInitialized("doubleTap");
+        const description = typeof locator === "string" ? locator : locator.value;
+        this.logger.elementAction("doubleTap", description);
+        const element = await this.findElement(locator);
+        await element.doubleClick();
+    }
+    /**
+     * Long press on element
+     */
+    async longPress(locator, duration = 1000) {
+        this.ensureInitialized("longPress");
+        const description = typeof locator === "string" ? locator : locator.value;
+        this.logger.elementAction("longPress", description);
+        const element = await this.findElement(locator);
+        const location = await element.getLocation();
+        const size = await element.getSize();
+        const centerX = location.x + size.width / 2;
+        const centerY = location.y + size.height / 2;
+        await this.driver.action("pointer", {
+            parameters: { pointerType: "touch" },
+        })
+            .move({ x: Math.round(centerX), y: Math.round(centerY) })
+            .down()
+            .pause(duration)
+            .up()
+            .perform();
+    }
+    // ============ Swipe Actions ============
+    /**
+     * Swipe in direction
+     */
+    async swipe(direction, options) {
+        this.ensureInitialized("swipe");
+        this.logger.debug(`Swipe ${direction}`);
+        const { width, height } = await this.getWindowSize();
+        const duration = options?.duration || 300;
+        let startX, startY, endX, endY;
+        switch (direction) {
+            case "up":
+                startX = Math.round(width / 2);
+                startY = Math.round(height * 0.7);
+                endX = Math.round(width / 2);
+                endY = Math.round(height * 0.3);
+                break;
+            case "down":
+                startX = Math.round(width / 2);
+                startY = Math.round(height * 0.3);
+                endX = Math.round(width / 2);
+                endY = Math.round(height * 0.7);
+                break;
+            case "left":
+                startX = Math.round(width * 0.8);
+                startY = Math.round(height / 2);
+                endX = Math.round(width * 0.2);
+                endY = Math.round(height / 2);
+                break;
+            case "right":
+                startX = Math.round(width * 0.2);
+                startY = Math.round(height / 2);
+                endX = Math.round(width * 0.8);
+                endY = Math.round(height / 2);
+                break;
+        }
+        await this.driver.action("pointer", {
+            parameters: { pointerType: "touch" },
+        })
+            .move({ x: startX, y: startY })
+            .down()
+            .pause(50)
+            .move({ x: endX, y: endY, duration })
+            .up()
+            .perform();
+    }
+    /**
+     * Swipe with specific coordinates
+     */
+    async swipeCoordinates(startX, startY, endX, endY, duration = 300) {
+        this.ensureInitialized("swipeCoordinates");
+        await this.driver.action("pointer", {
+            parameters: { pointerType: "touch" },
+        })
+            .move({ x: startX, y: startY })
+            .down()
+            .pause(50)
+            .move({ x: endX, y: endY, duration })
+            .up()
+            .perform();
+    }
+    /**
+     * Scroll to element
+     */
+    async scrollToElement(locator) {
+        this.ensureInitialized("scrollToElement");
+        const description = typeof locator === "string" ? locator : locator.value;
+        this.logger.debug(`Scrolling to element: ${description}`);
+        const maxScrolls = 5;
+        for (let i = 0; i < maxScrolls; i++) {
+            try {
+                const element = await this.findElement(locator);
+                if (await element.isDisplayed()) {
+                    return;
+                }
+            }
+            catch {
+                // Element not found, continue scrolling
+            }
+            await this.swipe("up");
+        }
+        throw new utils_1.MobileOperationError("scrollToElement", types_1.Platform.MOBILE, `Element not found after ${maxScrolls} scrolls: ${description}`, { locator: description });
+    }
+    // ============ Input Actions ============
+    /**
+     * Type text into element
+     */
+    async type(locator, text, _options) {
+        this.ensureInitialized("type");
+        const description = typeof locator === "string" ? locator : locator.value;
+        this.logger.elementAction("type", description);
+        const element = await this.findElement(locator);
+        await element.setValue(text);
+    }
+    /**
+     * Clear element text
+     */
+    async clear(locator, _options) {
+        this.ensureInitialized("clear");
+        const description = typeof locator === "string" ? locator : locator.value;
+        this.logger.elementAction("clear", description);
+        const element = await this.findElement(locator);
+        await element.clearValue();
+    }
+    /**
+     * Get element text
+     */
+    async getText(locator, _options) {
+        this.ensureInitialized("getText");
+        const element = await this.findElement(locator);
+        return await element.getText();
+    }
+    /**
+     * Get element attribute
+     */
+    async getAttribute(locator, attribute) {
+        this.ensureInitialized("getAttribute");
+        const element = await this.findElement(locator);
+        return await element.getAttribute(attribute);
+    }
+    /**
+     * Check if element is displayed
+     */
+    async isDisplayed(locator) {
+        this.ensureInitialized("isDisplayed");
+        try {
+            const element = await this.findElement(locator);
+            return await element.isDisplayed();
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Check if element is enabled
+     */
+    async isEnabled(locator) {
+        this.ensureInitialized("isEnabled");
+        try {
+            const element = await this.findElement(locator);
+            return await element.isEnabled();
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Wait for element to be visible
+     */
+    async waitForVisible(locator, options) {
+        this.ensureInitialized("waitForVisible");
+        const element = await this.findElement(locator);
+        await element.waitForDisplayed({
+            timeout: options?.timeout || this.getTimeout(),
+        });
+    }
+    /**
+     * Wait for element to be clickable
+     */
+    async waitForClickable(locator, options) {
+        this.ensureInitialized("waitForClickable");
+        const element = await this.findElement(locator);
+        await element.waitForClickable({
+            timeout: options?.timeout || this.getTimeout(),
+        });
+    }
+    /**
+     * Wait for element to be displayed (same as waitForVisible)
+     */
+    async waitForDisplayed(locator, timeout) {
+        this.ensureInitialized("waitForDisplayed");
+        const element = await this.findElement(locator);
+        await element.waitForDisplayed({
+            timeout: timeout || this.getTimeout(),
+        });
+        return element;
+    }
+    /**
+     * Wait for element to not be displayed
+     */
+    async waitForNotDisplayed(locator, timeout) {
+        this.ensureInitialized("waitForNotDisplayed");
+        const element = await this.findElement(locator);
+        await element.waitForDisplayed({
+            timeout: timeout || this.getTimeout(),
+            reverse: true,
+        });
+    }
+    // ============ Context Handling ============
+    /**
+     * Get available contexts
+     */
+    async getContexts() {
+        this.ensureInitialized("getContexts");
+        return (await this.driver.getContexts());
+    }
+    /**
+     * Get current context
+     */
+    async getContext() {
+        this.ensureInitialized("getContext");
+        this.currentContext = (await this.driver.getContext());
+        return this.currentContext;
+    }
+    /**
+     * Switch to context
+     */
+    async switchContext(context) {
+        this.ensureInitialized("switchContext");
+        this.logger.debug(`Switching to context: ${context}`);
+        await this.driver.switchContext(context);
+        this.currentContext = context;
+    }
+    /**
+     * Switch to native context
+     */
+    async switchToNative() {
+        await this.switchContext("NATIVE_APP");
+    }
+    /**
+     * Switch to webview context
+     */
+    async switchToWebview() {
+        this.ensureInitialized("switchToWebview");
+        const contexts = await this.getContexts();
+        const webviews = contexts.filter((c) => c.includes("WEBVIEW"));
+        if (webviews.length === 0) {
+            throw new utils_1.MobileOperationError("switchToWebview", types_1.Platform.MOBILE, "No webview contexts available");
+        }
+        await this.switchContext(webviews[0]);
+    }
+    // ============ App Management ============
+    /**
+     * Install app
+     */
+    async installApp(appPath) {
+        this.ensureInitialized("installApp");
+        this.logger.info(`Installing app: ${appPath}`);
+        await this.driver.installApp(appPath);
+    }
+    /**
+     * Remove app
+     */
+    async removeApp(appId) {
+        this.ensureInitialized("removeApp");
+        this.logger.info(`Removing app: ${appId}`);
+        await this.driver.removeApp(appId);
+    }
+    /**
+     * Check if app is installed
+     */
+    async isAppInstalled(appId) {
+        this.ensureInitialized("isAppInstalled");
+        return await this.driver.isAppInstalled(appId);
+    }
+    /**
+     * Launch app
+     */
+    async launchApp() {
+        this.ensureInitialized("launchApp");
+        this.logger.info("Launching app");
+        await this.driver.execute("mobile: launchApp", {});
+    }
+    /**
+     * Close/terminate app
+     */
+    async closeApp() {
+        this.ensureInitialized("closeApp");
+        const appId = this.config.appPackage || this.config.bundleId;
+        if (!appId) {
+            throw new utils_1.MobileOperationError("closeApp", types_1.Platform.MOBILE, "App ID not provided");
+        }
+        this.logger.info(`Closing app: ${appId}`);
+        await this.driver.terminateApp(appId, {});
+    }
+    /**
+     * Terminate app (alias for closeApp)
+     */
+    async terminateApp(appId) {
+        this.ensureInitialized("terminateApp");
+        const id = appId || this.config.appPackage || this.config.bundleId;
+        if (!id) {
+            throw new utils_1.MobileOperationError("terminateApp", types_1.Platform.MOBILE, "App ID not provided");
+        }
+        this.logger.info(`Terminating app: ${id}`);
+        await this.driver.terminateApp(id, {});
+    }
+    /**
+     * Activate app (bring to foreground)
+     */
+    async activateApp(appId) {
+        this.ensureInitialized("activateApp");
+        const id = appId || this.config.appPackage || this.config.bundleId;
+        if (!id) {
+            throw new utils_1.MobileOperationError("activateApp", types_1.Platform.MOBILE, "App ID not provided");
+        }
+        this.logger.info(`Activating app: ${id}`);
+        await this.driver.activateApp(id);
+    }
+    /**
+     * Get app state
+     */
+    async getAppState(appId) {
+        this.ensureInitialized("getAppState");
+        const id = appId || this.config.appPackage || this.config.bundleId;
+        if (!id) {
+            throw new utils_1.MobileOperationError("getAppState", types_1.Platform.MOBILE, "App ID not provided");
+        }
+        return (await this.driver.queryAppState(id));
+    }
+    /**
+     * Background app for duration
+     */
+    async backgroundApp(seconds = -1) {
+        this.ensureInitialized("backgroundApp");
+        this.logger.info(`Backgrounding app for ${seconds} seconds`);
+        await this.driver.background(seconds);
+    }
+    /**
+     * Reset app (clear data)
+     */
+    async resetApp() {
+        this.ensureInitialized("resetApp");
+        this.logger.info("Resetting app");
+        const appId = this.config.appPackage || this.config.bundleId;
+        if (appId) {
+            await this.terminateApp(appId);
+            await this.activateApp(appId);
+        }
+    }
+    // ============ Device Actions ============
+    /**
+     * Get window/screen size
+     */
+    async getWindowSize() {
+        this.ensureInitialized("getWindowSize");
+        return await this.driver.getWindowSize();
+    }
+    /**
+     * Get device orientation
+     */
+    async getOrientation() {
+        this.ensureInitialized("getOrientation");
+        const orientation = await this.driver.getOrientation();
+        return orientation.toUpperCase();
+    }
+    /**
+     * Set device orientation
+     */
+    async setOrientation(orientation) {
+        this.ensureInitialized("setOrientation");
+        this.logger.debug(`Setting orientation: ${orientation}`);
+        await this.driver.setOrientation(orientation);
+    }
+    /**
+     * Rotate device
+     */
+    async rotate() {
+        this.ensureInitialized("rotate");
+        const current = await this.getOrientation();
+        const next = current === "PORTRAIT" ? "LANDSCAPE" : "PORTRAIT";
+        await this.setOrientation(next);
+    }
+    /**
+     * Lock device
+     */
+    async lock(seconds) {
+        this.ensureInitialized("lock");
+        this.logger.debug("Locking device");
+        await this.driver.lock(seconds);
+    }
+    /**
+     * Unlock device
+     */
+    async unlock() {
+        this.ensureInitialized("unlock");
+        this.logger.debug("Unlocking device");
+        await this.driver.unlock();
+    }
+    /**
+     * Check if device is locked
+     */
+    async isLocked() {
+        this.ensureInitialized("isLocked");
+        return await this.driver.isLocked();
+    }
+    /**
+     * Press hardware back button (Android only)
+     */
+    async back() {
+        this.ensureInitialized("back");
+        if (this.config.platform !== types_1.MobilePlatform.ANDROID) {
+            this.logger.warn("Back button is only available on Android");
+            return;
+        }
+        await this.driver.back();
+    }
+    /**
+     * Press home button
+     */
+    async home() {
+        this.ensureInitialized("home");
+        if (this.config.platform === types_1.MobilePlatform.ANDROID) {
+            await this.driver.execute("mobile: pressKey", { keycode: 3 });
+        }
+        else {
+            await this.driver.execute("mobile: pressButton", { name: "home" });
+        }
+    }
+    /**
+     * Hide keyboard
+     */
+    async hideKeyboard() {
+        this.ensureInitialized("hideKeyboard");
+        try {
+            await this.driver.hideKeyboard();
+        }
+        catch {
+            // Keyboard might not be visible
+            this.logger.debug("Keyboard was not visible");
+        }
+    }
+    /**
+     * Check if keyboard is shown
+     */
+    async isKeyboardShown() {
+        this.ensureInitialized("isKeyboardShown");
+        return await this.driver.isKeyboardShown();
+    }
+    // ============ Additional Device Methods ============
+    /**
+     * Get device time
+     */
+    async getDeviceTime() {
+        this.ensureInitialized("getDeviceTime");
+        return (await this.driver.execute("mobile: getDeviceTime", {}));
+    }
+    /**
+     * Press back button (Android) - alias for back()
+     */
+    async pressBack() {
+        await this.back();
+    }
+    /**
+     * Press home button - alias for home()
+     */
+    async pressHome() {
+        await this.home();
+    }
+    /**
+     * Shake device
+     */
+    async shake() {
+        this.ensureInitialized("shake");
+        this.logger.debug("Shaking device");
+        await this.driver.execute("mobile: shake", {});
+    }
+    /**
+     * Get battery info
+     */
+    async getBatteryInfo() {
+        this.ensureInitialized("getBatteryInfo");
+        const info = (await this.driver.execute("mobile: batteryInfo", {}));
+        return info;
+    }
+    /**
+     * Push file to device
+     */
+    async pushFile(remotePath, data) {
+        this.ensureInitialized("pushFile");
+        this.logger.debug(`Pushing file to: ${remotePath}`);
+        await this.driver.pushFile(remotePath, data);
+    }
+    /**
+     * Pull file from device
+     */
+    async pullFile(remotePath) {
+        this.ensureInitialized("pullFile");
+        this.logger.debug(`Pulling file from: ${remotePath}`);
+        return await this.driver.pullFile(remotePath);
+    }
+    // ============ Screenshot ============
+    /**
+     * Take a screenshot
+     */
+    async takeScreenshot(options = {}) {
+        this.ensureInitialized("takeScreenshot");
+        const base64 = await this.driver.takeScreenshot();
+        const buffer = Buffer.from(base64, "base64");
+        // Save to file if path specified
+        if (options.path) {
+            await this.saveScreenshot(buffer, options);
+        }
+        return buffer;
+    }
+    /**
+     * Execute script
+     */
+    async executeScript(script, ...args) {
+        this.ensureInitialized("executeScript");
+        return (await this.driver.execute(script, ...args));
+    }
+    // ============ Cleanup ============
+    /**
+     * Quit the driver and cleanup
+     */
+    async quit() {
+        if (!this.initialized) {
+            return;
+        }
+        // Execute before quit hooks
+        await this.hooks.execute(hook_manager_1.HookEvent.BEFORE_DRIVER_QUIT, {
+            platform: this.platform,
+            driverStatus: this.getStatus(),
+        });
+        try {
+            if (this.driver) {
+                await this.driver.deleteSession();
+                this.driver = null;
+            }
+            await super.quit();
+            // Execute after quit hooks
+            await this.hooks.execute(hook_manager_1.HookEvent.AFTER_DRIVER_QUIT, {
+                platform: this.platform,
+            });
+        }
+        catch (error) {
+            this.logger.error("Error during MobileDriver quit", {
+                error: error.message,
+            });
+        }
+    }
+}
+exports.MobileDriver = MobileDriver;
+//# sourceMappingURL=mobile.driver.js.map