@loadmill/droid-cua 2.13.0 → 2.15.1

package/build/src/cli/headless-runner.js

@@ -0,0 +1,245 @@
+import path from "path";
+import { mkdir } from "fs/promises";
+import { getCurrentPlatform as getBrowserCurrentPlatform, getScreenshotAsBase64 as getBrowserScreenshotAsBase64, } from "../browser/connection.js";
+import { handleModelAction as handleBrowserModelAction } from "../browser/actions.js";
+import { ExecutionEngine } from "../core/execution-engine.js";
+import { buildExecutionModePrompt } from "../core/prompts.js";
+import { ExecutionMode } from "../modes/execution-mode.js";
+import { printCliOutput } from "../utils/console-output.js";
+import { emitDesktopDebug } from "../utils/desktop-debug.js";
+import { loadHeadlessInstructions } from "./headless-instructions.js";
+function sanitizePathSegment(value) {
+    return String(value || "test")
+        .replace(/\.dcua$/i, "")
+        .trim()
+        .replace(/[^a-zA-Z0-9._-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^[-_.]+|[-_.]+$/g, "") || "test";
+}
+function createHeadlessRunId(index = 0) {
+    const suffix = index > 0 ? `-${index + 1}` : "";
+    return `run-${Date.now()}${suffix}`;
+}
+function getRecordScreenshotDirForTest(baseScreenshotDir, testName, isBatchRun) {
+    if (!baseScreenshotDir || !isBatchRun) {
+        return baseScreenshotDir;
+    }
+    return path.join(baseScreenshotDir, sanitizePathSegment(testName));
+}
+function emitCliAppContextDebug(runId, appContext, appContextText) {
+    if (appContext.status === "loaded" || appContext.status === "empty") {
+        emitDesktopDebug("app_context.loaded", "execution", { runId }, {
+            source: "cli_context_flag",
+            contextPath: appContext.contextPath,
+            status: appContext.status,
+            text: appContextText
+        });
+        if (appContextText) {
+            console.log(`Using app context from: ${appContext.contextPath}`);
+        }
+    }
+    else if (appContext.status === "failed") {
+        emitDesktopDebug("app_context.loaded", "execution", { runId }, {
+            source: "cli_context_flag",
+            contextPath: appContext.contextPath,
+            status: "failed",
+            message: appContext.message
+        });
+        console.warn(`Warning: could not load app context from ${appContext.contextPath}. Running without it.`);
+    }
+    else {
+        emitDesktopDebug("app_context.loaded", "execution", { runId }, {
+            source: "cli_context_flag",
+            contextPath: appContext.contextPath,
+            status: appContext.status
+        });
+    }
+}
+function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, executionPrompt, screenshotRecorder, recordScreenshots, screenshotDir, isBrowserTarget, isLambdaTestTarget }) {
+    const executionEngineOptions = {
+        toolCapabilities: {
+            assert: true,
+            navigate: isBrowserTarget,
+            loadmill: true,
+        },
+        baseSystemPrompt: executionPrompt,
+        isHeadlessMode: true,
+    };
+    const engineOptions = screenshotRecorder
+        ? {
+            recordScreenshots: true,
+            screenshotRecorder,
+            stepDelayMs: runtimeContext.config.stepDelayMs,
+            sendCUARequest: (requestArgs) => runtimeContext.openAi.sendCUARequest({
+                ...requestArgs,
+                aimAssistMode: headlessConfig.aimAssistMode,
+            }),
+            reviseTestScript: runtimeContext.openAi.reviseTestScript,
+            ...executionEngineOptions,
+        }
+        : {
+            recordScreenshots,
+            screenshotDir,
+            stepDelayMs: runtimeContext.config.stepDelayMs,
+            sendCUARequest: (requestArgs) => runtimeContext.openAi.sendCUARequest({
+                ...requestArgs,
+                aimAssistMode: headlessConfig.aimAssistMode,
+            }),
+            reviseTestScript: runtimeContext.openAi.reviseTestScript,
+            ...executionEngineOptions,
+        };
+    if (isBrowserTarget) {
+        engineOptions.getScreenshotAsBase64 = (browserSessionId, browserInfo) => getBrowserScreenshotAsBase64(browserSessionId, browserInfo);
+        engineOptions.handleModelAction = (browserSessionId, action, scale, actionContext) => handleBrowserModelAction(browserSessionId, action, scale, actionContext);
+        engineOptions.getCurrentPlatform = getBrowserCurrentPlatform;
+    }
+    else if (isLambdaTestTarget) {
+        engineOptions.connectToDevice = async () => {
+            throw new Error("LambdaTest cloud session disconnected; automatic CLI reconnect is not supported yet.");
+        };
+    }
+    return engineOptions;
+}
+async function runHeadlessTest({ runId, testPath, testName, instructions, session, deviceInfo, headlessConfig, appContext, runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isLambdaTestTarget }) {
+    let executionMode = null;
+    try {
+        await headlessDebug.startExecutionSession(runId, {
+            testName,
+            platform: deviceInfo.platform,
+            deviceName: deviceInfo.device_name,
+            aimAssistMode: headlessConfig.aimAssistMode
+        });
+        const currentLogFilePath = await headlessDebug.getCurrentLogFilePath();
+        if (currentLogFilePath) {
+            console.log(`Debug logging enabled: ${currentLogFilePath}`);
+        }
+        console.log(`\nRunning test from: ${testPath}\n`);
+        console.log(`Using CUA model: ${runtimeContext.config.cuaModel}`);
+        const appContextText = appContext.text;
+        emitCliAppContextDebug(runId, appContext, appContextText);
+        session.updateResponseId(undefined);
+        session.clearMessages();
+        const executionPrompt = buildExecutionModePrompt(deviceInfo, headlessConfig.promptCustomizations, appContextText, { aimAssistMode: headlessConfig.aimAssistMode });
+        session.setSystemPrompt(executionPrompt);
+        const screenshotRecorder = headlessDebug.createExecutionScreenshotRecorder({
+            runId,
+            recordScreenshots,
+            screenshotDir
+        });
+        const engineOptions = buildHeadlessEngineOptions({
+            runtimeContext,
+            headlessConfig,
+            executionPrompt,
+            screenshotRecorder,
+            recordScreenshots,
+            screenshotDir,
+            isBrowserTarget,
+            isLambdaTestTarget
+        });
+        const engine = new ExecutionEngine(session, engineOptions);
+        executionMode = new ExecutionMode(session, engine, instructions, true);
+        const result = await executionMode.execute({
+            runId,
+            addOutput: printCliOutput,
+            openAiClient: runtimeContext.openAiClient,
+            loadmillClient: runtimeContext.loadmillClient,
+            runtimeCredentials: runtimeContext.credentials,
+        });
+        const stats = executionMode.stats || {};
+        const durationMs = stats.startTime ? Math.max(0, Date.now() - stats.startTime) : 0;
+        await headlessDebug.endExecutionSession(runId, {
+            success: Boolean(result.success),
+            error: result.error ?? null,
+            durationMs,
+            instructionsTotal: instructions.length,
+            instructionsCompleted: stats.instructionsCompleted ?? 0,
+            actionsTotal: stats.actionCount ?? 0,
+            assertionsPassed: stats.assertionsPassed ?? 0,
+            assertionsFailed: stats.assertionsFailed ?? 0,
+            retries: stats.retryCount ?? 0
+        });
+        if (!result.success) {
+            console.error(`\nTest failed: ${result.error}`);
+        }
+        return {
+            success: Boolean(result.success),
+            error: result.error ?? null
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Failed to start execution.";
+        const stats = executionMode?.stats || {};
+        const durationMs = stats.startTime ? Math.max(0, Date.now() - stats.startTime) : 0;
+        await headlessDebug.endExecutionSession(runId, {
+            success: false,
+            error: message,
+            ...(stats.startTime
+                ? {
+                    durationMs,
+                    instructionsTotal: instructions.length,
+                    instructionsCompleted: stats.instructionsCompleted ?? 0,
+                    actionsTotal: stats.actionCount ?? 0,
+                    assertionsPassed: stats.assertionsPassed ?? 0,
+                    assertionsFailed: stats.assertionsFailed ?? 0,
+                    retries: stats.retryCount ?? 0
+                }
+                : { reason: "start_failed" })
+        });
+        throw error;
+    }
+}
+export async function runHeadlessInstructionRuns({ runs, instructionsTarget, session, deviceInfo, headlessConfig, appContext, runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isLambdaTestTarget }) {
+    const isBatchRun = instructionsTarget?.type === "directory";
+    if (isBatchRun) {
+        console.log(`\nRunning ${runs.length} tests from: ${instructionsTarget.path}\n`);
+    }
+    let failures = 0;
+    for (const [index, run] of runs.entries()) {
+        const runId = createHeadlessRunId(index);
+        const testScreenshotDir = getRecordScreenshotDirForTest(screenshotDir, run.testName, isBatchRun);
+        if (isBatchRun) {
+            console.log(`\n[${index + 1}/${runs.length}] ${run.testName}`);
+        }
+        try {
+            const instructions = run.instructions ?? await loadHeadlessInstructions(run.testPath);
+            if (recordScreenshots && testScreenshotDir) {
+                await mkdir(testScreenshotDir, { recursive: true });
+            }
+            const result = await runHeadlessTest({
+                runId,
+                testPath: run.testPath,
+                testName: run.testName,
+                instructions,
+                session,
+                deviceInfo,
+                headlessConfig,
+                appContext,
+                runtimeContext,
+                headlessDebug,
+                recordScreenshots,
+                screenshotDir: testScreenshotDir,
+                isBrowserTarget,
+                isLambdaTestTarget
+            });
+            if (!result.success) {
+                failures += 1;
+            }
+        }
+        catch (error) {
+            failures += 1;
+            if (!isBatchRun) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`\nTest failed: ${run.testName}: ${message}`);
+        }
+    }
+    if (isBatchRun) {
+        const passed = runs.length - failures;
+        console.log(`\nFolder run complete: ${passed}/${runs.length} passed`);
+    }
+    return {
+        exitCode: failures === 0 ? 0 : 1,
+        failures
+    };
+}

package/build/src/commands/loadmill.js

@@ -21,12 +21,12 @@ export async function handleLoadmill(args, session, context) {
         addOutput({ type: 'info', text: '  /loadmill <command>          Execute a Loadmill flow' });
         addOutput({ type: 'info', text: '' });
         addOutput({ type: 'info', text: 'Examples:' });
-        addOutput({ type: 'info', text: '  /loadmill search for login flow' });
+        addOutput({ type: 'info', text: '  /loadmill login flow' });
         addOutput({ type: 'info', text: '  /loadmill run checkout flow with user=test123' });
         addOutput({ type: 'info', text: '  /loadmill run payment test with amount=100' });
         addOutput({ type: 'info', text: '' });
         addOutput({ type: 'info', text: 'In test scripts (.dcua files):' });
-        addOutput({ type: 'info', text: '  loadmill: run user authentication flow' });
+        addOutput({ type: 'info', text: '  run loadmill user authentication flow' });
         addOutput({ type: 'info', text: '' });
         addOutput({ type: 'info', text: 'Configuration:' });
         addOutput({ type: 'info', text: '  Set LOADMILL_API_TOKEN in your .env file' });
@@ -68,25 +68,9 @@ export async function handleLoadmill(args, session, context) {
     }
     // Display results
     if (result.success) {
-        if (result.action === "search") {
-            addOutput({ type: 'success', text: `Found ${result.result.flows.length} flow(s):` });
-            result.result.flows.forEach((flow, i) => {
-                const name = flow.description || flow.name || "Unknown";
-                const suite = flow.testSuiteDescription ? ` (Suite: ${flow.testSuiteDescription})` : '';
-                addOutput({ type: 'info', text: `  ${i + 1}. ${name}${suite}` });
-                addOutput({ type: 'info', text: `     ID: ${flow.id}` });
-            });
-            if (result.result.selectedFlow) {
-                const selectedName = result.result.selectedFlow.description || result.result.selectedFlow.name || "Unknown";
-                addOutput({ type: 'info', text: '' });
-                addOutput({ type: 'info', text: `Best match: "${selectedName}" (confidence: ${(result.result.confidence * 100).toFixed(0)}%)` });
-            }
-        }
-        else {
-            addOutput({ type: 'success', text: `Flow "${result.flowName}" passed` });
-            if (result.runId) {
-                addOutput({ type: 'info', text: `Run ID: ${result.runId}` });
-            }
+        addOutput({ type: 'success', text: `Flow "${result.flowName}" passed` });
+        if (result.runId) {
+            addOutput({ type: 'info', text: `Run ID: ${result.runId}` });
         }
     }
     else {

package/build/src/core/execution-engine.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { getScreenshotAsBase64, getCurrentPlatform } from "../device/connection.js";
-import { getBrowserInfo, navigateToUrl as navigateBrowserToUrl } from "../browser/connection.js";
+import { closeCurrentTab as closeCurrentBrowserTab, getBrowserInfo, navigateToUrl as navigateBrowserToUrl } from "../browser/connection.js";
 import { handleModelAction } from "../device/actions.js";
 import { sendCUARequest } from "../device/openai.js";
 import { executeLoadmillInstruction } from "../device/loadmill.js";
@@ -11,6 +11,7 @@ import { CAPTURE_SOURCES } from "./capture-sources.js";
 import { ScreenshotStore } from "./screenshot-store.js";
 import { handlePreviewClick } from "./tool-handlers/preview-click.js";
 import { handleNavigateToolCall } from "./tool-handlers/navigate.js";
+import { handleCloseCurrentTabToolCall } from "./tool-handlers/close-current-tab.js";
 import { handleAssertionToolCall } from "./tool-handlers/assert.js";
 import { handleLoadmillToolCall } from "./tool-handlers/loadmill.js";
 import { handleTestDesignCompleteToolCall } from "./tool-handlers/test-design-complete.js";
@@ -73,6 +74,7 @@ export class ExecutionEngine {
         this.getCurrentPlatform = options.getCurrentPlatform || getCurrentPlatform;
         this.getBrowserInfo = options.getBrowserInfo || getBrowserInfo;
         this.navigateToUrl = options.navigateToUrl || navigateBrowserToUrl;
+        this.closeCurrentTab = options.closeCurrentTab || closeCurrentBrowserTab;
         this.executeLoadmillInstruction = options.executeLoadmillInstruction || executeLoadmillInstruction;
         this.toolCapabilities = options.toolCapabilities || {};
         this.baseSystemPrompt = options.baseSystemPrompt || session?.systemPrompt || null;
@@ -102,6 +104,8 @@ export class ExecutionEngine {
                 return await handleAssertionToolCall(handlerArgs);
             case "navigate":
                 return await handleNavigateToolCall(handlerArgs);
+            case "close_current_tab":
+                return await handleCloseCurrentTabToolCall(handlerArgs);
             case "loadmill":
                 return await handleLoadmillToolCall(handlerArgs);
             case "test_design_complete":

package/build/src/core/tool-handlers/browser-session.js

@@ -0,0 +1,7 @@
+export function updateBrowserSessionInfo(session, browserInfo, fallbackUrl = null) {
+    session.browserInfo = browserInfo;
+    session.deviceInfo = browserInfo;
+    session.currentUrl = browserInfo.currentUrl || fallbackUrl || null;
+    session.browserName = browserInfo.browserName || session.currentUrl;
+    session.deviceName = session.browserName;
+}

package/build/src/core/tool-handlers/close-current-tab.js

@@ -0,0 +1,53 @@
+import { normalizeBrowserInfoForSession } from "../../browser/normalize.js";
+import { CAPTURE_SOURCES } from "../capture-sources.js";
+import { printCliOutput } from "../../utils/console-output.js";
+import { updateBrowserSessionInfo } from "./browser-session.js";
+import { buildFunctionCallOutputItem, buildPreviewOutputContent, buildTextToolOutputItem, } from "./utils.js";
+export async function handleCloseCurrentTabToolCall({ engine, callId, context = null, stepContext = null }) {
+    const session = engine.session;
+    if (session?.targetKind !== "browser" && session?.deviceInfo?.platform !== "browser") {
+        return {
+            kind: "continue",
+            outputItem: buildTextToolOutputItem(callId, "close_current_tab is only supported for web runs."),
+        };
+    }
+    const addOutput = context?.addOutput || printCliOutput;
+    const result = await engine.closeCurrentTab(session.browserSessionId);
+    if (!result.closed) {
+        return {
+            kind: "continue",
+            outputItem: buildTextToolOutputItem(callId, result.message || "No previous browser tab is available. The current tab was left open."),
+        };
+    }
+    addOutput({
+        type: "action",
+        text: "Close current tab",
+        eventType: "tool_call",
+        runId: context?.runId,
+        stepId: stepContext?.stepId,
+        instructionIndex: stepContext?.instructionIndex,
+        payload: {
+            platform: session.deviceInfo?.platform,
+            toolName: "close_current_tab",
+            restoredUrl: result.restoredUrl,
+        },
+    });
+    const browserInfo = normalizeBrowserInfoForSession(await engine.getBrowserInfo(session.browserSessionId));
+    updateBrowserSessionInfo(session, browserInfo, result.restoredUrl);
+    const screenshotBase64 = await engine.getScreenshotAsBase64(session.deviceId, session.deviceInfo);
+    const currentScreenshot = await engine.recordScreenshot(screenshotBase64, {
+        runId: context?.runId,
+        sessionId: context?.sessionId,
+        stepId: stepContext?.stepId,
+        instructionIndex: stepContext?.instructionIndex,
+        captureSource: CAPTURE_SOURCES.CALL_OUTPUT_POST_ACTION,
+    });
+    return {
+        kind: "continue",
+        outputItem: buildFunctionCallOutputItem(callId, buildPreviewOutputContent({
+            text: result.message,
+            annotatedScreenshotBase64: screenshotBase64,
+        })),
+        currentScreenshot,
+    };
+}

package/build/src/core/tool-handlers/navigate.js

@@ -2,6 +2,7 @@ import { normalizeBrowserInfoForSession } from "../../browser/normalize.js";
 import { buildExecutionNavigationRecoveryPrompt } from "../../prompts/execution.js";
 import { emitDesktopDebug } from "../../utils/desktop-debug.js";
 import { printCliOutput } from "../../utils/console-output.js";
+import { updateBrowserSessionInfo } from "./browser-session.js";
 import { buildDebugContext, buildFunctionCallOutputItem, buildPreviewOutputContent, buildTextToolOutputItem, isDesignContext, parseStringToolArgument, } from "./utils.js";
 export async function handleNavigateToolCall({ engine, callId, argumentsText, context = null, stepContext = null }) {
     const session = engine.session;
@@ -42,11 +43,7 @@ export async function handleNavigateToolCall({ engine, callId, argumentsText, co
     try {
         const normalizedUrl = await engine.navigateToUrl(session.browserSessionId, navigationTarget);
         const browserInfo = normalizeBrowserInfoForSession(await engine.getBrowserInfo(session.browserSessionId));
-        session.browserInfo = browserInfo;
-        session.deviceInfo = browserInfo;
-        session.currentUrl = browserInfo.currentUrl || normalizedUrl;
-        session.browserName = browserInfo.browserName || session.currentUrl;
-        session.deviceName = session.browserName;
+        updateBrowserSessionInfo(session, browserInfo, normalizedUrl);
         emitDesktopDebug("runner.navigate.completed", isDesignContext(context) ? "design" : "execution", buildDebugContext(context, stepContext), {
             instruction: navigationTarget,
             target: navigationTarget,

package/build/src/device/android/connection.js

@@ -3,6 +3,8 @@ import sharp from "sharp";
 import { logger } from "../../utils/logger.js";
 import { emitDesktopDebug } from "../../utils/desktop-debug.js";
 import { execAdb, execEmulator, spawnAdb, spawnEmulator } from "./tools.js";
+const AVD_READY_TIMEOUT_MS = 180000;
+const AVD_READY_TIMEOUT_SECONDS = AVD_READY_TIMEOUT_MS / 1000;
 async function listConnectedDevices() {
     const { stdout } = await execAdb(["devices"]);
     return stdout
@@ -65,6 +67,12 @@ async function waitForWindowServiceReady(deviceId, timeoutMs = 60000) {
     }
     return false;
 }
+function remainingTimeoutMs(deadline) {
+    return Math.max(0, deadline - Date.now());
+}
+function emulatorLaunchTimeoutError() {
+    return new Error(`Emulator launch timed out after ${AVD_READY_TIMEOUT_SECONDS}s. Check AVD health and retry.`);
+}
 async function findRunningEmulatorByAvdName(avdName) {
     const devices = await listConnectedDevices();
     const readyEmulators = devices.filter((entry) => entry.state === "device" && entry.id.startsWith("emulator-"));
@@ -76,7 +84,8 @@ async function findRunningEmulatorByAvdName(avdName) {
     }
     return null;
 }
-async function launchAndWaitForAvd(avdName, timeoutMs = 60000) {
+async function launchAndWaitForAvd(avdName, timeoutMs = AVD_READY_TIMEOUT_MS, options = {}) {
+    const log = options.log || console.log;
     let avdExists = false;
     try {
         const { stdout } = await execEmulator(["-list-avds"]);
@@ -92,7 +101,7 @@ async function launchAndWaitForAvd(avdName, timeoutMs = 60000) {
     }
     const baseline = await listConnectedDevices();
     const baselineReadyEmulators = new Set(baseline.filter((entry) => entry.state === "device" && entry.id.startsWith("emulator-")).map((entry) => entry.id));
-    console.log(`Launching Android emulator "${avdName}"...`);
+    log(`Launching Android emulator "${avdName}"...`);
     const emulatorProcess = spawnEmulator(["-avd", avdName], { detached: true, stdio: "ignore" });
     emulatorProcess.unref();
     const deadline = Date.now() + timeoutMs;
@@ -108,9 +117,10 @@ async function launchAndWaitForAvd(avdName, timeoutMs = 60000) {
         }
         await wait(2000);
     }
-    throw new Error("Emulator launch timed out after 60s. Check AVD health and retry.");
+    throw emulatorLaunchTimeoutError();
 }
-export async function connectToDevice(deviceTargetId) {
+export async function connectToDevice(deviceTargetId, options = {}) {
+    const log = options.log || console.log;
     emitDesktopDebug("device.connect", "device", {}, { platform: "android", stage: "start", targetId: deviceTargetId || null });
     const parsedTarget = parseTargetToken(deviceTargetId || "");
     const devices = await listConnectedDevices();
@@ -126,27 +136,28 @@ export async function connectToDevice(deviceTargetId) {
             throw new Error("No ready Android devices found. Connect a device (or start an emulator), authorize adb, and retry.");
         }
         const selected = readyDevices[0].id;
-        console.log(`Using connected Android device: ${selected}`);
+        log(`Using connected Android device: ${selected}`);
         emitDesktopDebug("device.connect", "device", {}, { platform: "android", stage: "success", deviceId: selected, reused: true });
         return selected;
     }
     if (parsedTarget.kind === "avd") {
+        const deadline = Date.now() + AVD_READY_TIMEOUT_MS;
         const alreadyRunning = await findRunningEmulatorByAvdName(parsedTarget.avdName);
         if (alreadyRunning) {
-            const ready = await waitForWindowServiceReady(alreadyRunning, 60000);
+            const ready = await waitForWindowServiceReady(alreadyRunning, remainingTimeoutMs(deadline));
             if (!ready) {
-                throw new Error("Emulator launch timed out after 60s. Check AVD health and retry.");
+                throw emulatorLaunchTimeoutError();
             }
-            console.log(`Using already-running emulator for AVD "${parsedTarget.avdName}": ${alreadyRunning}`);
+            log(`Using already-running emulator for AVD "${parsedTarget.avdName}": ${alreadyRunning}`);
             emitDesktopDebug("device.connect", "device", {}, { platform: "android", stage: "success", deviceId: alreadyRunning, reused: true });
             return alreadyRunning;
         }
-        const launchedId = await launchAndWaitForAvd(parsedTarget.avdName, 60000);
-        const ready = await waitForWindowServiceReady(launchedId, 60000);
+        const launchedId = await launchAndWaitForAvd(parsedTarget.avdName, remainingTimeoutMs(deadline), { log });
+        const ready = await waitForWindowServiceReady(launchedId, remainingTimeoutMs(deadline));
         if (!ready) {
-            throw new Error("Emulator launch timed out after 60s. Check AVD health and retry.");
+            throw emulatorLaunchTimeoutError();
         }
-        console.log(`Connected to launched emulator "${parsedTarget.avdName}" as ${launchedId}`);
+        log(`Connected to launched emulator "${parsedTarget.avdName}" as ${launchedId}`);
         emitDesktopDebug("device.connect", "device", {}, {
             platform: "android",
             stage: "success",
@@ -163,7 +174,7 @@ export async function connectToDevice(deviceTargetId) {
         if (!ready) {
             throw new Error("Selected device is connected but not ready yet. Wait a moment and retry.");
         }
-        console.log(`Using selected Android device: ${targetId}`);
+        log(`Using selected Android device: ${targetId}`);
         emitDesktopDebug("device.connect", "device", {}, { platform: "android", stage: "success", deviceId: targetId, reused: true });
         return targetId;
     }

package/build/src/device/cloud/connection.js

@@ -23,7 +23,8 @@ function buildCloudCapabilities(options) {
         }
     };
 }
-export async function connectToDevice(options) {
+export async function connectToDevice(options, logOptions = {}) {
+    const log = logOptions.log || console.log;
     if (!options || typeof options !== "object") {
         throw new Error("Cloud device connection requires a provider payload.");
     }
@@ -45,7 +46,7 @@ export async function connectToDevice(options) {
         sessionName
     });
     const client = new CloudAppiumClient(platform, adapter, credentials);
-    console.log(`Creating ${adapter.displayName} session on ${deviceName} (${osVersion})...`);
+    log(`Creating ${adapter.displayName} session on ${deviceName} (${osVersion})...`);
     const session = await client.createSession(capabilities);
     activeSession = {
         client,
@@ -55,7 +56,7 @@ export async function connectToDevice(options) {
         osVersion,
         sessionId: session.sessionId
     };
-    console.log(`Connected to ${adapter.displayName} device "${deviceName}" (${session.sessionId})`);
+    log(`Connected to ${adapter.displayName} device "${deviceName}" (${session.sessionId})`);
     return session.sessionId;
 }
 export async function getDeviceInfo(sessionId) {

package/build/src/device/connection.js

@@ -12,33 +12,35 @@ let currentBackend = null;
  * @param {string} platform - Optional platform override ('android' or 'ios')
  * @returns {Promise<string>} Device ID
  */
-export async function connectToDevice(deviceNameOrOptions, platform = null) {
+export async function connectToDevice(deviceNameOrOptions, platform = null, options = {}) {
     if (deviceNameOrOptions && typeof deviceNameOrOptions === "object" && !Array.isArray(deviceNameOrOptions)) {
         const cloudOptions = deviceNameOrOptions;
         const detectedPlatform = cloudOptions.platform || detectPlatform(cloudOptions.deviceName);
         setCurrentSource(cloudOptions.source || "local");
         setCurrentPlatform(detectedPlatform);
         currentBackend = getDeviceBackend(detectedPlatform);
-        console.log(`Platform: ${detectedPlatform}`);
-        return currentBackend.connectToDevice(cloudOptions);
+        const log = options.log || console.log;
+        log(`Platform: ${detectedPlatform}`);
+        return currentBackend.connectToDevice(cloudOptions, options);
     }
     const detectedPlatform = platform || detectPlatform(deviceNameOrOptions);
     setCurrentSource("local");
     setCurrentPlatform(detectedPlatform);
     currentBackend = getDeviceBackend(detectedPlatform);
-    console.log(`Platform: ${detectedPlatform}`);
-    return currentBackend.connectToDevice(deviceNameOrOptions);
+    const log = options.log || console.log;
+    log(`Platform: ${detectedPlatform}`);
+    return currentBackend.connectToDevice(deviceNameOrOptions, options);
 }
 /**
  * Get device info (screen dimensions and scale factor)
  * @param {string} deviceId
  * @returns {Promise<object>}
  */
-export async function getDeviceInfo(deviceId) {
+export async function getDeviceInfo(deviceId, options = {}) {
     if (!currentBackend) {
         throw new Error("Not connected to a device. Call connectToDevice first.");
     }
-    return currentBackend.getDeviceInfo(deviceId);
+    return currentBackend.getDeviceInfo(deviceId, options);
 }
 /**
  * Get screenshot as base64 string

package/build/src/device/ios/appium-server.js

@@ -89,13 +89,14 @@ async function waitForAppiumReady(timeoutMs = 30000) {
  * Start Appium server if not already running
  * @returns {Promise<void>}
  */
-export async function startAppium() {
+export async function startAppium(options = {}) {
+    const log = options.log || console.log;
     if (await isAppiumRunning()) {
-        console.log("Appium server is already running");
+        log("Appium server is already running");
         return;
     }
     const appiumCommand = resolveAppiumCommand();
-    console.log(`Starting Appium server (${appiumCommand})...`);
+    log(`Starting Appium server (${appiumCommand})...`);
     try {
         appiumProcess = await spawnAppiumProcess(appiumCommand);
     }
@@ -110,7 +111,7 @@ export async function startAppium() {
     if (!ready) {
         throw new Error("Appium server failed to start within 30 seconds");
     }
-    console.log("Appium server is ready");
+    log("Appium server is ready");
 }
 /**
  * Stop the Appium server if we started it