@autifyhq/aximo-cli 0.4.0 → 0.5.0

package/dist/mobile-control/appium-controller.test.js

@@ -0,0 +1,252 @@
+import { describe, expect, it } from "vitest";
+import { AppiumController } from "./appium-controller.js";
+import { ELEMENT_KEY } from "./webdriver.js";
+function pngWithWidth(width) {
+    const buf = Buffer.alloc(24);
+    buf.writeUInt32BE(width, 16);
+    buf.writeUInt32BE(width, 20);
+    return buf.toString("base64");
+}
+function fakeTransport(options = {}) {
+    const calls = [];
+    const windowWidth = options.windowWidth ?? 400;
+    const screenshotWidth = options.screenshotWidth ?? 400;
+    const transport = {
+        async request(method, path, body) {
+            calls.push({ method, path, body });
+            if (method === "POST" && path === "/session") {
+                return { sessionId: "sess-1" };
+            }
+            if (path.endsWith("/screenshot")) {
+                return pngWithWidth(screenshotWidth);
+            }
+            if (path.endsWith("/window/rect")) {
+                return { width: windowWidth, height: windowWidth * 2, x: 0, y: 0 };
+            }
+            if (path.endsWith("/element/active")) {
+                const ref = options.activeElement === undefined ? "active-el" : options.activeElement;
+                return ref ? { [ELEMENT_KEY]: ref } : null;
+            }
+            if (method === "POST" && path.endsWith("/element")) {
+                const ref = options.findElementRef === undefined ? "found-el" : options.findElementRef;
+                return ref ? { [ELEMENT_KEY]: ref } : null;
+            }
+            return {};
+        },
+    };
+    return { transport, calls };
+}
+function makeController(platform, options) {
+    const { transport, calls } = fakeTransport(options);
+    return {
+        controller: new AppiumController({
+            endpoint: "http://x",
+            platform,
+            target: "udid-1",
+            transport,
+        }),
+        calls,
+    };
+}
+function bodyOf(calls, predicate) {
+    const call = calls.find(predicate);
+    if (!call)
+        throw new Error("expected a matching recorded call");
+    return (call.body ?? {});
+}
+function executeBody(calls) {
+    return bodyOf(calls, (c) => c.path.endsWith("/execute/sync"));
+}
+function caps(calls) {
+    const body = bodyOf(calls, (c) => c.path === "/session" && c.method === "POST");
+    return body["capabilities"].alwaysMatch;
+}
+function pointerActions(calls) {
+    const body = bodyOf(calls, (c) => c.path.endsWith("/actions") && c.method === "POST");
+    const groups = body["actions"];
+    return groups[0]?.actions ?? [];
+}
+describe("AppiumController session capabilities", () => {
+    it("sends Android UiAutomator2 caps", async () => {
+        const { controller, calls } = makeController("android");
+        await controller.screenshot();
+        const c = caps(calls);
+        expect(c["platformName"]).toBe("Android");
+        expect(c["appium:automationName"]).toBe("UiAutomator2");
+        expect(c["appium:udid"]).toBe("udid-1");
+        expect(c["appium:noReset"]).toBe(true);
+        expect(c["appium:autoLaunch"]).toBe(false);
+        expect(c["appium:newCommandTimeout"]).toBe(0);
+    });
+    it("sends iOS XCUITest caps", async () => {
+        const { controller, calls } = makeController("ios");
+        await controller.screenshot();
+        const c = caps(calls);
+        expect(c["platformName"]).toBe("iOS");
+        expect(c["appium:automationName"]).toBe("XCUITest");
+        expect(c["appium:newCommandTimeout"]).toBe(0);
+    });
+    it("creates the session lazily and only once", async () => {
+        const { controller, calls } = makeController("android");
+        await controller.screenshot();
+        await controller.screenshot();
+        expect(calls.filter((c) => c.path === "/session" && c.method === "POST")).toHaveLength(1);
+    });
+});
+describe("AppiumController coordinate scaling", () => {
+    it("halves pixel coords when screenshot is 800px and window is 400pt (iOS)", async () => {
+        const { controller, calls } = makeController("ios", { windowWidth: 400, screenshotWidth: 800 });
+        await controller.tap(200, 100);
+        const actions = pointerActions(calls);
+        const move = actions[0];
+        expect(move.type).toBe("pointerMove");
+        expect(move.x).toBe(100);
+        expect(move.y).toBe(50);
+    });
+    it("keeps coords ~1:1 for Android when scale is 1", async () => {
+        const { controller, calls } = makeController("android", {
+            windowWidth: 400,
+            screenshotWidth: 400,
+        });
+        await controller.tap(123, 45);
+        const move = pointerActions(calls)[0];
+        expect(move.x).toBe(123);
+        expect(move.y).toBe(45);
+    });
+});
+describe("AppiumController touch actions", () => {
+    it("tap builds move/down/pause/up", async () => {
+        const { controller, calls } = makeController("android");
+        await controller.tap(10, 20);
+        const actions = pointerActions(calls).map((a) => a.type);
+        expect(actions).toEqual(["pointerMove", "pointerDown", "pause", "pointerUp"]);
+        expect(calls.some((c) => c.method === "DELETE" && c.path.endsWith("/actions"))).toBe(true);
+    });
+    it("long_press holds for the requested duration", async () => {
+        const { controller, calls } = makeController("android");
+        await controller.longPress(10, 20, 1500);
+        const pause = pointerActions(calls).find((a) => a.type === "pause");
+        expect(pause.duration).toBe(1500);
+    });
+    it("swipe moves start->end with the duration on the second move", async () => {
+        const { controller, calls } = makeController("android");
+        await controller.swipe(10, 20, 30, 40, 250);
+        const actions = pointerActions(calls);
+        expect(actions[0].x).toBe(10);
+        const endMove = actions[2];
+        expect(endMove.type).toBe("pointerMove");
+        expect(endMove.x).toBe(30);
+        expect(endMove.duration).toBe(250);
+    });
+    it("double_tap performs two down/up cycles", async () => {
+        const { controller, calls } = makeController("ios");
+        await controller.doubleTap(5, 5);
+        const downs = pointerActions(calls).filter((a) => a.type === "pointerDown");
+        expect(downs).toHaveLength(2);
+    });
+});
+describe("AppiumController text + keys", () => {
+    it("typeText on Android uses mobile: type", async () => {
+        const { controller, calls } = makeController("android");
+        const result = await controller.typeText("hello");
+        expect(result.ok).toBe(true);
+        const exec = executeBody(calls);
+        expect(exec.script).toBe("mobile: type");
+        expect(exec.args[0]?.["text"]).toBe("hello");
+    });
+    it("typeText on iOS sends keys to the active element", async () => {
+        const { controller, calls } = makeController("ios");
+        await controller.typeText("hi");
+        expect(calls.some((c) => c.path.endsWith("/element/active"))).toBe(true);
+        const send = bodyOf(calls, (c) => c.path.endsWith("/element/active-el/value"));
+        expect(send["text"]).toBe("hi");
+    });
+    it("clearText clears the active element when present", async () => {
+        const { controller, calls } = makeController("android", { activeElement: "el-9" });
+        const result = await controller.clearText();
+        expect(result.ok).toBe(true);
+        expect(calls.some((c) => c.path.endsWith("/element/el-9/clear"))).toBe(true);
+    });
+    it("clearText falls back to Ctrl+A + delete on Android when no active element", async () => {
+        const { controller, calls } = makeController("android", { activeElement: null });
+        const result = await controller.clearText();
+        expect(result.ok).toBe(true);
+        const execs = calls.filter((c) => c.path.endsWith("/execute/sync"));
+        expect(execs).toHaveLength(2);
+        const first = executeBody(calls);
+        expect(first.args[0]?.["keycode"]).toBe(29);
+    });
+    it("clearText returns a structured error on iOS with no active element", async () => {
+        const { controller } = makeController("ios", { activeElement: null });
+        const result = await controller.clearText();
+        expect(result.ok).toBe(false);
+        expect(result.error).toContain("focus");
+    });
+    it("pressKey maps Android keys to mobile: pressKey keycodes", async () => {
+        const { controller, calls } = makeController("android");
+        expect((await controller.pressKey("back")).ok).toBe(true);
+        expect(executeBody(calls).args[0]?.["keycode"]).toBe(4);
+    });
+    it("pressKey rejects 'back' on iOS", async () => {
+        const { controller } = makeController("ios");
+        const result = await controller.pressKey("back");
+        expect(result.ok).toBe(false);
+        expect(result.error).toContain("Android-only");
+    });
+    it("pressKey returns an error for unsupported keys", async () => {
+        const { controller } = makeController("android");
+        const result = await controller.pressKey("f13");
+        expect(result.ok).toBe(false);
+    });
+});
+describe("AppiumController findElement", () => {
+    it("clicks the located element and tries accessibility id first on Android", async () => {
+        const { controller, calls } = makeController("android", { findElementRef: "btn-1" });
+        const result = await controller.findElement("Sign in");
+        expect(result.ok).toBe(true);
+        const firstFind = bodyOf(calls, (c) => c.method === "POST" && c.path.endsWith("/element"));
+        expect(firstFind["using"]).toBe("accessibility id");
+        expect(calls.some((c) => c.path.endsWith("/element/btn-1/click"))).toBe(true);
+    });
+    it("tries the iOS button predicate first", async () => {
+        const { controller, calls } = makeController("ios", { findElementRef: "btn-1" });
+        await controller.findElement("OK");
+        const firstFind = bodyOf(calls, (c) => c.method === "POST" && c.path.endsWith("/element"));
+        expect(firstFind["using"]).toBe("-ios predicate string");
+    });
+    it("returns not-found when no strategy locates the element", async () => {
+        const { controller } = makeController("android", { findElementRef: null });
+        const result = await controller.findElement("Nope");
+        expect(result.ok).toBe(false);
+        expect(result.error).toContain("not found");
+    });
+});
+describe("AppiumController launch + lifecycle", () => {
+    it("launchApp uses mobile: activateApp with appId on Android", async () => {
+        const { controller, calls } = makeController("android");
+        await controller.launchApp("com.example.app");
+        const exec = executeBody(calls);
+        expect(exec.script).toBe("mobile: activateApp");
+        expect(exec.args[0]?.["appId"]).toBe("com.example.app");
+    });
+    it("launchApp uses bundleId on iOS", async () => {
+        const { controller, calls } = makeController("ios");
+        await controller.launchApp("com.example.app");
+        expect(executeBody(calls).args[0]?.["bundleId"]).toBe("com.example.app");
+    });
+    it("hideKeyboard swallows errors and acks ok", async () => {
+        const { controller, calls } = makeController("android");
+        await controller.screenshot();
+        const result = await controller.hideKeyboard();
+        expect(result.ok).toBe(true);
+        const exec = calls.find((c) => c.path.endsWith("/execute/sync") &&
+            c.body.script === "mobile: hideKeyboard");
+        expect(exec).toBeDefined();
+    });
+    it("close deletes the session", async () => {
+        const { controller, calls } = makeController("android");
+        await controller.screenshot();
+        await controller.close();
+        expect(calls.some((c) => c.method === "DELETE" && c.path === "/session/sess-1")).toBe(true);
+    });
+});

package/dist/mobile-control/appium-import.d.ts

@@ -0,0 +1,7 @@
+interface AppiumModule {
+    main: (args: Record<string, unknown>) => Promise<{
+        close(): Promise<void>;
+    }>;
+}
+export declare function importAppium(): Promise<AppiumModule>;
+export {};

package/dist/mobile-control/appium-import.js

@@ -0,0 +1,6 @@
+const APPIUM = "appium";
+export async function importAppium() {
+    // Appium 3 is CJS, so its `main` is under `.default` when imported from ESM.
+    const mod = (await import(APPIUM));
+    return mod.default ?? mod;
+}

package/dist/mobile-control/appium-import.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mobile-control/appium-import.test.js

@@ -0,0 +1,9 @@
+import { describe, expect, it } from "vitest";
+import { importAppium } from "./appium-import.js";
+// Guards the CJS-default unwrap with a real import (Appium 3 exposes `main` under `.default`).
+describe("importAppium", () => {
+    it("resolves the appium module with a callable main()", async () => {
+        const mod = await importAppium();
+        expect(typeof mod.main).toBe("function");
+    });
+});

package/dist/mobile-control/appium-server.d.ts

@@ -0,0 +1,30 @@
+export interface AppiumServerHandle {
+    endpoint: string;
+    stop: () => Promise<void>;
+}
+interface RunningServer {
+    close(): Promise<void>;
+}
+export type AppiumLauncher = (args: Record<string, unknown>) => Promise<RunningServer>;
+export interface StartAppiumServerOptions {
+    launch?: AppiumLauncher;
+    appiumHome?: string;
+    useDrivers?: string[];
+    readyTimeoutMs?: number;
+}
+export declare function getAppiumHome(): string;
+export interface ResolveAndroidSdkDeps {
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    platform?: NodeJS.Platform;
+    exists?: (path: string) => boolean;
+}
+/**
+ * Resolve the Android SDK location. Honours ANDROID_HOME / ANDROID_SDK_ROOT when
+ * set and valid, else probes the standard per-OS install location. Appium's
+ * UiAutomator2 driver requires this even when `adb` is already on PATH.
+ */
+export declare function resolveAndroidSdk(deps?: ResolveAndroidSdkDeps): string | null;
+export declare function pickFreePort(): Promise<number>;
+export declare function startAppiumServer(options?: StartAppiumServerOptions): Promise<AppiumServerHandle>;
+export {};

package/dist/mobile-control/appium-server.js

@@ -0,0 +1,110 @@
+import { existsSync } from "node:fs";
+import { createServer } from "node:net";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import { getAximoDir } from "../commands/device/paths.js";
+import { importAppium } from "./appium-import.js";
+export function getAppiumHome() {
+    return join(getAximoDir(), "appium-home");
+}
+function isValidSdk(dir, exists) {
+    return exists(dir) && exists(join(dir, "platform-tools"));
+}
+/**
+ * Resolve the Android SDK location. Honours ANDROID_HOME / ANDROID_SDK_ROOT when
+ * set and valid, else probes the standard per-OS install location. Appium's
+ * UiAutomator2 driver requires this even when `adb` is already on PATH.
+ */
+export function resolveAndroidSdk(deps = {}) {
+    const env = deps.env ?? process.env;
+    const home = deps.home ?? homedir();
+    const os = deps.platform ?? platform();
+    const exists = deps.exists ?? existsSync;
+    for (const candidate of [env["ANDROID_HOME"], env["ANDROID_SDK_ROOT"]]) {
+        if (candidate && isValidSdk(candidate, exists))
+            return candidate;
+    }
+    const standard = os === "darwin"
+        ? join(home, "Library", "Android", "sdk")
+        : os === "win32"
+            ? join(env["LOCALAPPDATA"] ?? join(home, "AppData", "Local"), "Android", "Sdk")
+            : join(home, "Android", "Sdk");
+    return isValidSdk(standard, exists) ? standard : null;
+}
+export async function pickFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.on("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const address = srv.address();
+            if (address && typeof address === "object") {
+                const { port } = address;
+                srv.close(() => resolve(port));
+            }
+            else {
+                srv.close(() => reject(new Error("Could not determine a free port")));
+            }
+        });
+    });
+}
+const defaultLaunch = async (args) => {
+    const mod = await importAppium();
+    return mod.main(args);
+};
+async function pollReady(endpoint, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(`${endpoint}/status`);
+            if (res.ok)
+                return;
+        }
+        catch (error) {
+            lastError = error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    const detail = lastError instanceof Error ? `: ${lastError.message}` : "";
+    throw new Error(`Appium server did not become ready within ${timeoutMs}ms${detail}`);
+}
+export async function startAppiumServer(options = {}) {
+    const launch = options.launch ?? defaultLaunch;
+    const appiumHome = options.appiumHome ?? getAppiumHome();
+    const useDrivers = options.useDrivers ?? ["uiautomator2"];
+    const readyTimeoutMs = options.readyTimeoutMs ?? 30_000;
+    // Appium's UiAutomator2 driver reads ANDROID_HOME/ANDROID_SDK_ROOT from the
+    // environment; it runs in-process via main(), so we export a resolved SDK
+    // path here when neither is set, otherwise sessions fail to start.
+    if (!process.env["ANDROID_HOME"] && !process.env["ANDROID_SDK_ROOT"]) {
+        const sdk = resolveAndroidSdk();
+        if (sdk) {
+            process.env["ANDROID_HOME"] = sdk;
+            process.env["ANDROID_SDK_ROOT"] = sdk;
+            console.error(`Using auto-detected Android SDK at ${sdk} (set ANDROID_HOME to override).`);
+        }
+    }
+    const port = await pickFreePort();
+    const endpoint = `http://127.0.0.1:${port}`;
+    const server = await launch({
+        port,
+        basePath: "/",
+        host: "127.0.0.1",
+        appiumHome,
+        useDrivers,
+        loglevel: "warn",
+    });
+    try {
+        await pollReady(endpoint, readyTimeoutMs);
+    }
+    catch (error) {
+        await server.close().catch(() => { });
+        throw error;
+    }
+    return {
+        endpoint,
+        stop: async () => {
+            await server.close();
+        },
+    };
+}

package/dist/mobile-control/appium-server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mobile-control/appium-server.test.js

@@ -0,0 +1,108 @@
+import { join } from "node:path";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { pickFreePort, resolveAndroidSdk, startAppiumServer, } from "./appium-server.js";
+const realFetch = globalThis.fetch;
+beforeAll(() => {
+    process.env["AXIMO_HOME"] = "/tmp/aximo-appium-test";
+});
+afterEach(() => {
+    globalThis.fetch = realFetch;
+    vi.restoreAllMocks();
+});
+describe("pickFreePort", () => {
+    it("returns a usable, positive port", async () => {
+        const port = await pickFreePort();
+        expect(port).toBeGreaterThan(0);
+        expect(port).toBeLessThan(65_536);
+    });
+});
+describe("startAppiumServer", () => {
+    it("launches on a free port, polls /status, and stops", async () => {
+        let statusHits = 0;
+        globalThis.fetch = vi.fn(async (input) => {
+            const url = String(input);
+            expect(url).toContain("/status");
+            statusHits++;
+            return new Response("{}", { status: statusHits >= 2 ? 200 : 503 });
+        });
+        const close = vi.fn(async () => { });
+        const launchArgs = [];
+        const launch = async (args) => {
+            launchArgs.push(args);
+            return { close };
+        };
+        const handle = await startAppiumServer({ launch, readyTimeoutMs: 5000 });
+        expect(handle.endpoint).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/);
+        const args = launchArgs[0];
+        expect(args["host"]).toBe("127.0.0.1");
+        expect(args["basePath"]).toBe("/");
+        expect(typeof args["port"]).toBe("number");
+        expect(args["useDrivers"]).toEqual(["uiautomator2"]);
+        expect(statusHits).toBeGreaterThanOrEqual(2);
+        await handle.stop();
+        expect(close).toHaveBeenCalledOnce();
+    });
+    it("closes the server and throws when readiness times out", async () => {
+        globalThis.fetch = vi.fn(async () => new Response("nope", { status: 503 }));
+        const close = vi.fn(async () => { });
+        const launch = async () => ({ close });
+        await expect(startAppiumServer({ launch, readyTimeoutMs: 300 })).rejects.toThrow(/did not become ready/);
+        expect(close).toHaveBeenCalledOnce();
+    });
+});
+describe("resolveAndroidSdk", () => {
+    const exists = (valid) => (path) => path === valid || path === join(valid, "platform-tools");
+    it("honours a valid ANDROID_HOME", () => {
+        const result = resolveAndroidSdk({
+            env: { ANDROID_HOME: "/opt/sdk" },
+            exists: exists("/opt/sdk"),
+        });
+        expect(result).toBe("/opt/sdk");
+    });
+    it("falls back to ANDROID_SDK_ROOT when ANDROID_HOME is invalid", () => {
+        const result = resolveAndroidSdk({
+            env: { ANDROID_HOME: "/bad", ANDROID_SDK_ROOT: "/opt/root" },
+            exists: exists("/opt/root"),
+        });
+        expect(result).toBe("/opt/root");
+    });
+    it("probes the standard macOS location when env is unset", () => {
+        const expected = join("/Users/dev", "Library", "Android", "sdk");
+        const result = resolveAndroidSdk({
+            env: {},
+            home: "/Users/dev",
+            platform: "darwin",
+            exists: exists(expected),
+        });
+        expect(result).toBe(expected);
+    });
+    it("probes the standard Linux location when env is unset", () => {
+        const expected = join("/home/dev", "Android", "Sdk");
+        const result = resolveAndroidSdk({
+            env: {},
+            home: "/home/dev",
+            platform: "linux",
+            exists: exists(expected),
+        });
+        expect(result).toBe(expected);
+    });
+    it("probes LOCALAPPDATA on Windows when env is unset", () => {
+        const expected = join("C:\\Users\\dev\\AppData\\Local", "Android", "Sdk");
+        const result = resolveAndroidSdk({
+            env: { LOCALAPPDATA: "C:\\Users\\dev\\AppData\\Local" },
+            home: "C:\\Users\\dev",
+            platform: "win32",
+            exists: exists(expected),
+        });
+        expect(result).toBe(expected);
+    });
+    it("returns null when no SDK is found", () => {
+        const result = resolveAndroidSdk({
+            env: {},
+            home: "/home/dev",
+            platform: "linux",
+            exists: () => false,
+        });
+        expect(result).toBeNull();
+    });
+});

package/dist/mobile-control/controller.d.ts

@@ -0,0 +1,22 @@
+export interface ActionResult {
+    ok: boolean;
+    error?: string;
+}
+export interface MobileController {
+    screenshot(): Promise<Buffer>;
+    tap(x: number, y: number): Promise<void>;
+    doubleTap(x: number, y: number): Promise<void>;
+    longPress(x: number, y: number, durationMs: number): Promise<void>;
+    swipe(x1: number, y1: number, x2: number, y2: number, durationMs: number): Promise<void>;
+    typeText(text: string): Promise<ActionResult>;
+    pressKey(key: string): Promise<ActionResult>;
+    launchApp(app: string): Promise<ActionResult>;
+    findElement(text: string): Promise<ActionResult>;
+    clearText(): Promise<ActionResult>;
+    hideKeyboard(): Promise<ActionResult>;
+    getDeviceTime?(): Promise<{
+        datetime: string;
+        timezone: string;
+    } | null>;
+    close(): Promise<void>;
+}

package/dist/mobile-control/controller.js

@@ -0,0 +1 @@
+export {};

package/dist/mobile-control/devices.d.ts

@@ -0,0 +1,21 @@
+import { type ExecFn } from "./exec.js";
+export interface AndroidDevice {
+    serial: string;
+    state: string;
+    model?: string;
+}
+/** Parse `adb devices -l` into serial + state (+ model when present). */
+export declare function listAndroidDevices(exec?: ExecFn): Promise<AndroidDevice[]>;
+/** Resolve an adb serial: explicit (validated), else the single connected phone. */
+export declare function resolveAndroidSerial(preferred: string | undefined, exec?: ExecFn): Promise<string>;
+export interface IosPhysicalDevice {
+    udid: string;
+    name: string;
+    state?: string;
+}
+/**
+ * List physically-connected iOS devices via `idb list-targets --json` (one JSON
+ * object per line). Only entries whose `type` is `device` are returned. Returns
+ * an empty list if idb is unavailable.
+ */
+export declare function listIosPhysicalDevices(exec?: ExecFn): Promise<IosPhysicalDevice[]>;