@loadmill/droid-cua 2.10.1-rc.9 → 2.12.0

package/README.md

@@ -147,6 +147,16 @@ droid-cua --platform ios --avd "iPhone 16" --instructions tests/login.dcua
 
 # Headless run with prompt-parity config
 droid-cua --avd adb:emulator-5554 --instructions tests/login.dcua --config ci/droid-cua.json
+
+# Headless LambdaTest real-device run
+LAMBDATEST_USERNAME=... LAMBDATEST_ACCESS_KEY=... droid-cua \
+  --device-source lambdatest \
+  --platform android \
+  --device-name "Galaxy S24" \
+  --os-version "14" \
+  --app ./app/build/outputs/apk/debug/app-debug.apk \
+  --instructions tests/login.dcua \
+  --config ci/droid-cua.json
 ```
 
 Example headless config:
@@ -161,7 +171,7 @@ Example headless config:
   "appContextEnabled": true,
   "appContextPath": "../tests/context.md",
   "contextOptimizationEnabled": true,
-  "contextOptimizationThreshold": 20000
+  "contextOptimizationThreshold": 30000
 }
 ```
 
@@ -177,6 +187,11 @@ droid-cua \
 Supported CLI options include:
 - `--avd`
 - `--platform`
+- `--device-source`
+- `--device-name`
+- `--os-version`
+- `--app`
+- `--browser`
 - `--instructions`
 - `--config`
 - `--cua-model`
@@ -196,13 +211,47 @@ Config and precedence rules:
 - CLI flags override config file values.
 - `--context` overrides the config app-context path.
 - `--no-context` disables app context entirely.
-- Context Optimization is enabled by default with a `20000` input-token threshold.
+- Context Optimization is enabled by default with a `30000` input-token threshold.
 - `--context-optimization-threshold <tokens>` sets the threshold and enables Context Optimization.
 - `--no-context-optimization` disables Context Optimization.
 - `--base-prompt` and `--execution-prompt` let you pass prompt customizations inline on the command line.
 - `--base-prompt-file` and `--execution-prompt-file` override the corresponding prompt customizations from config.
 - If both inline and file-based prompt overrides are provided, the inline prompt flags win.
 
+LambdaTest CLI runs:
+- Use `--device-source lambdatest` with `--platform`, `--device-name`, `--os-version`, `--app`, and `--instructions`.
+- Set `LAMBDATEST_USERNAME` and `LAMBDATEST_ACCESS_KEY` in the environment.
+- Android LambdaTest runs require an `.apk`; iOS LambdaTest runs require an `.ipa`.
+- The CLI uploads the app to LambdaTest for each run and closes the cloud session when the run finishes or fails.
+- Each CLI LambdaTest run gets a unique LambdaTest build name so repeated local runs are easy to distinguish in the LambdaTest UI.
+
+Minimal GitHub Actions shape:
+```yaml
+jobs:
+  droid-cua:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install -g @loadmill/droid-cua
+      - run: |
+          droid-cua \
+            --device-source lambdatest \
+            --platform android \
+            --device-name "Galaxy S24" \
+            --os-version "14" \
+            --app ./app/build/outputs/apk/debug/app-debug.apk \
+            --instructions tests/login.dcua \
+            --config ci/droid-cua.json \
+            --debug
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LAMBDATEST_USERNAME: ${{ secrets.LAMBDATEST_USERNAME }}
+          LAMBDATEST_ACCESS_KEY: ${{ secrets.LAMBDATEST_ACCESS_KEY }}
+```
+
 Example without a config file:
 ```sh
 droid-cua \

package/build/index.js

@@ -2,7 +2,7 @@ import minimist from "minimist";
 import dotenv from "dotenv";
 import path from "path";
 import { mkdir } from "fs/promises";
-import { connectToDevice, getDeviceInfo } from "./src/device/connection.js";
+import { connectToDevice, disconnect as disconnectDevice, getDeviceInfo } from "./src/device/connection.js";
 import { connectToBrowser, getBrowserInfo, getCurrentPlatform as getBrowserCurrentPlatform, getScreenshotAsBase64 as getBrowserScreenshotAsBase64, } from "./src/browser/connection.js";
 import { handleModelAction as handleBrowserModelAction } from "./src/browser/actions.js";
 import { normalizeBrowserInfoForSession } from "./src/browser/normalize.js";
@@ -21,8 +21,10 @@ import { resolveHeadlessTarget } from "./src/cli/headless-target.js";
 import { printCliOutput } from "./src/utils/console-output.js";
 import { emitDesktopDebug } from "./src/utils/desktop-debug.js";
 import { createHeadlessDebugArtifacts } from "./src/cli/headless-debug.js";
-import { loadHeadlessInstructions } from "./src/cli/headless-instructions.js";
+import { loadHeadlessInstructions, resolveHeadlessInstructionsPath } from "./src/cli/headless-instructions.js";
+import { resolveLambdaTestCredentials, uploadLambdaTestCliApp } from "./src/cli/lambdatest-app-upload.js";
 import { createLoadmillApiClient } from "./src/integrations/loadmill/client.js";
+import { getCloudProviderAdapter } from "./src/device/cloud/registry.js";
 dotenv.config();
 const args = minimist(process.argv.slice(2));
 const targetConfig = resolveHeadlessTarget(args);
@@ -57,9 +59,40 @@ function createCliRuntimeContext(configOverrides = {}) {
         loadmillClient,
     };
 }
+function createLambdaTestCliBuildName() {
+    return `loadmill-droid-cua-cli-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+}
+function wait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isLambdaTestAppAutomationUrl(value) {
+    return typeof value === "string" && value.startsWith("https://appautomation.lambdatest.com/test?");
+}
+async function resolveLambdaTestDashboardUrl(credentials, sessionId, { attempts = 1, delayMs = 1000 } = {}) {
+    const adapter = getCloudProviderAdapter("lambdatest");
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+            const artifacts = await adapter?.getSessionArtifacts(credentials, sessionId);
+            if (isLambdaTestAppAutomationUrl(artifacts?.dashboardUrl)) {
+                return artifacts.dashboardUrl;
+            }
+        }
+        catch {
+            // Dashboard lookup is best-effort and must not fail the test run or cleanup.
+        }
+        if (attempt < attempts) {
+            await wait(delayMs);
+        }
+    }
+    return null;
+}
 async function main() {
     const isHeadlessInstructionsRun = Boolean(instructionsFile);
     const isBrowserTarget = targetConfig.target === "web";
+    const isLambdaTestTarget = targetConfig.deviceSource === "lambdatest";
+    let lambdaTestSessionConnected = false;
+    let lambdaTestSessionUrl = null;
+    let lambdaTestCredentials = null;
     const headlessDebug = createHeadlessDebugArtifacts({
         cwd: process.cwd(),
         enabled: isHeadlessInstructionsRun && debugMode
@@ -72,8 +105,27 @@ async function main() {
     if (isBrowserTarget && !isHeadlessInstructionsRun) {
         throw new Error("--target web is only supported with --instructions headless execution.");
     }
+    if (isLambdaTestTarget && !isHeadlessInstructionsRun) {
+        throw new Error("--device-source lambdatest is only supported with --instructions headless execution.");
+    }
+    let preloadedHeadlessConfig = null;
+    let preloadedHeadlessInstructions = null;
+    let resolvedInstructionsFile = instructionsFile;
+    let preloadedAppContext = null;
+    if (isHeadlessInstructionsRun) {
+        preloadedHeadlessConfig = await resolveHeadlessExecutionConfig(args);
+        resolvedInstructionsFile = await resolveHeadlessInstructionsPath(instructionsFile);
+        preloadedHeadlessInstructions = await loadHeadlessInstructions(resolvedInstructionsFile);
+        preloadedAppContext = await resolveExecutionAppContext({
+            enabled: preloadedHeadlessConfig.appContextEnabled,
+            contextPath: preloadedHeadlessConfig.appContextPath,
+        });
+        if (preloadedAppContext.status === "failed") {
+            throw new Error(`Could not read app context file ${preloadedAppContext.contextPath}: ${preloadedAppContext.message}`);
+        }
+    }
     // If no device specified, show interactive selection menu
-    if (!isBrowserTarget && !avdName && !platform) {
+    if (!isBrowserTarget && !isLambdaTestTarget && !avdName && !platform) {
         const selection = await selectDevice();
         platform = selection.platform;
         avdName = selection.deviceName;
@@ -83,6 +135,7 @@ async function main() {
     if (isBrowserTarget) {
         targetId = await connectToBrowser({
             headless: true,
+            browserFamily: targetConfig.browserFamily,
             sessionMode: targetConfig.sessionMode
         });
         deviceInfo = normalizeBrowserInfoForSession(await getBrowserInfo(targetId));
@@ -92,6 +145,47 @@ async function main() {
             console.log(`Starting URL: ${deviceInfo.currentUrl}`);
         }
     }
+    else if (isLambdaTestTarget) {
+        lambdaTestCredentials = resolveLambdaTestCredentials(process.env);
+        const lambdaTestBuildName = createLambdaTestCliBuildName();
+        console.log(`Uploading app to LambdaTest: ${path.resolve(targetConfig.appPath)}`);
+        const upload = await uploadLambdaTestCliApp({
+            appPath: targetConfig.appPath,
+            platform: targetConfig.platform,
+            credentials: lambdaTestCredentials,
+        });
+        console.log(`Uploaded app to LambdaTest: ${upload.appRef}`);
+        try {
+            targetId = await connectToDevice({
+                source: "lambdatest",
+                providerId: "lambdatest",
+                platform: targetConfig.platform,
+                deviceName: targetConfig.deviceName,
+                osVersion: targetConfig.osVersion,
+                appRef: upload.appRef,
+                credentials: lambdaTestCredentials,
+                buildName: lambdaTestBuildName,
+            });
+            lambdaTestSessionConnected = true;
+            lambdaTestSessionUrl = await resolveLambdaTestDashboardUrl(lambdaTestCredentials, targetId, {
+                attempts: 3,
+                delayMs: 1000,
+            });
+            if (lambdaTestSessionUrl) {
+                console.log(`LambdaTest session: ${lambdaTestSessionUrl}`);
+            }
+            deviceInfo = await getDeviceInfo(targetId);
+        }
+        catch (error) {
+            if (lambdaTestSessionConnected) {
+                await disconnectDevice();
+                lambdaTestSessionConnected = false;
+            }
+            throw error;
+        }
+        console.log(`Using real resolution: ${deviceInfo.device_width}x${deviceInfo.device_height}`);
+        console.log(`Model sees resolution: ${deviceInfo.scaled_width}x${deviceInfo.scaled_height}`);
+    }
     else {
         targetId = await connectToDevice(avdName, platform);
         deviceInfo = await getDeviceInfo(targetId);
@@ -105,11 +199,12 @@ async function main() {
     // If --instructions provided, run in headless mode
     if (instructionsFile) {
         const runId = `run-${Date.now()}`;
-        const testName = path.basename(instructionsFile);
+        const testName = path.basename(resolvedInstructionsFile);
         let instructions = [];
         let executionMode = null;
+        let exitCode = null;
         try {
-            const headlessConfig = await resolveHeadlessExecutionConfig(args);
+            const headlessConfig = preloadedHeadlessConfig;
             await headlessDebug.startExecutionSession(runId, {
                 testName,
                 platform: deviceInfo.platform,
@@ -120,12 +215,9 @@ async function main() {
             if (currentLogFilePath) {
                 console.log(`Debug logging enabled: ${currentLogFilePath}`);
             }
-            console.log(`\nRunning test from: ${instructionsFile}\n`);
-            instructions = await loadHeadlessInstructions(instructionsFile);
-            const appContext = await resolveExecutionAppContext({
-                enabled: headlessConfig.appContextEnabled,
-                contextPath: headlessConfig.appContextPath,
-            });
+            console.log(`\nRunning test from: ${resolvedInstructionsFile}\n`);
+            instructions = preloadedHeadlessInstructions;
+            const appContext = preloadedAppContext;
             const appContextText = appContext.text;
             const runtimeContext = createCliRuntimeContext({
                 cuaModel: headlessConfig.cuaModel,
@@ -212,6 +304,11 @@ async function main() {
                 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.");
+                };
+            }
             const engine = new ExecutionEngine(session, engineOptions);
             executionMode = new ExecutionMode(session, engine, instructions, true);
             const result = await executionMode.execute({
@@ -234,13 +331,10 @@ async function main() {
                 assertionsFailed: stats.assertionsFailed ?? 0,
                 retries: stats.retryCount ?? 0
             });
-            if (result.success) {
-                process.exit(0);
-            }
-            else {
+            if (!result.success) {
                 console.error(`\nTest failed: ${result.error}`);
-                process.exit(1);
             }
+            exitCode = result.success ? 0 : 1;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : "Failed to start execution.";
@@ -263,6 +357,29 @@ async function main() {
             });
             throw error;
         }
+        finally {
+            if (lambdaTestSessionConnected) {
+                console.log("Ending LambdaTest session...");
+                await disconnectDevice();
+                lambdaTestSessionConnected = false;
+                console.log("LambdaTest session ended.");
+                if (!lambdaTestSessionUrl && lambdaTestCredentials && targetId) {
+                    lambdaTestSessionUrl = await resolveLambdaTestDashboardUrl(lambdaTestCredentials, targetId, {
+                        attempts: 12,
+                        delayMs: 1000,
+                    });
+                    if (lambdaTestSessionUrl) {
+                        console.log(`LambdaTest session: ${lambdaTestSessionUrl}`);
+                    }
+                }
+                if (!lambdaTestSessionUrl && targetId) {
+                    console.log(`LambdaTest session id: ${targetId}`);
+                }
+            }
+        }
+        if (exitCode !== null) {
+            process.exit(exitCode);
+        }
     }
     const runtimeContext = createCliRuntimeContext();
     const engine = new ExecutionEngine(session, {

package/build/src/browser/playwright/connection.js

@@ -174,15 +174,22 @@ function normalizeConnectOptions(targetOrOptions) {
         return {
             url: normalizeOptionalAutomationUrl(targetOrOptions),
             headless: false,
+            // Legacy string-form callers do not carry UI selection, so keep Chrome as
+            // the explicit default for that narrow path.
+            browserFamily: "chrome",
             sessionMode: "fresh",
             persistentProfileDir: null,
             freshProfileDir: null,
         };
     }
     const options = targetOrOptions && typeof targetOrOptions === "object" ? targetOrOptions : {};
+    if (options.browserFamily !== "chrome" && options.browserFamily !== "edge") {
+        throw new Error("Browser sessions require browserFamily to be \"chrome\" or \"edge\".");
+    }
     return {
         url: normalizeOptionalAutomationUrl(options.url),
         headless: options.headless === true,
+        browserFamily: options.browserFamily,
         sessionMode: options.sessionMode === "persistent" ? "persistent" : "fresh",
         onDisconnected: typeof options.onDisconnected === "function" ? options.onDisconnected : null,
         persistentProfileDir: typeof options.persistentProfileDir === "string" && options.persistentProfileDir.trim().length > 0
@@ -227,15 +234,15 @@ async function loadChromium() {
         throw new Error(`Browser automation requires the optional playwright-core dependency. Install project dependencies and try again. (${message})`);
     }
 }
-async function resolveInstalledBrowserForLaunch() {
+async function resolveInstalledBrowserForLaunch(browserFamily) {
     if (typeof browserConnectionTestHooks?.resolveInstalledBrowser === "function") {
-        return await browserConnectionTestHooks.resolveInstalledBrowser();
+        return await browserConnectionTestHooks.resolveInstalledBrowser(browserFamily);
     }
-    return await requireInstalledBrowser();
+    return await requireInstalledBrowser(browserFamily);
 }
 export async function connectToBrowser(targetOrOptions) {
     const options = normalizeConnectOptions(targetOrOptions);
-    const installedBrowser = await resolveInstalledBrowserForLaunch();
+    const installedBrowser = await resolveInstalledBrowserForLaunch(options.browserFamily);
     const chromium = await loadChromium();
     await waitForPendingBrowserSessionShutdown();
     try {

package/build/src/browser/playwright/installed-browser.js

@@ -2,8 +2,6 @@ import os from "node:os";
 import path from "node:path";
 import { access } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
-export const CHROME_INSTALL_URL = "https://www.google.com/chrome/";
-export const EDGE_INSTALL_URL = "https://www.microsoft.com/edge/download";
 function readEnvValue(env, ...keys) {
     for (const key of keys) {
         const value = env?.[key];
@@ -80,52 +78,64 @@ async function pathExistsAndIsRunnable(filePath, platform, accessFn) {
 }
 function buildMissingBrowserMessage(platform) {
     if (platform !== "darwin" && platform !== "win32") {
-        return "Installed browser detection is currently supported only on macOS and Windows. Install Google Chrome or Microsoft Edge on a supported machine.";
+        return "Installed browser detection is currently supported only on macOS and Windows. Google Chrome or Microsoft Edge is required on a supported machine.";
     }
-    return `No supported browser was found. Install Google Chrome or Microsoft Edge and try again. Chrome: ${CHROME_INSTALL_URL} Edge: ${EDGE_INSTALL_URL}`;
+    return "No supported browser was found. Google Chrome or Microsoft Edge is required.";
 }
-export async function resolveInstalledBrowser({ platform = process.platform, env = process.env, homeDir = os.homedir(), accessFn = access, } = {}) {
+function buildMissingSelectedBrowserMessage(browserFamily, platform) {
+    const browserName = browserFamily === "edge" ? "Microsoft Edge" : "Google Chrome";
+    if (platform !== "darwin" && platform !== "win32") {
+        return `${browserName} detection is currently supported only on macOS and Windows.`;
+    }
+    return `${browserName} was selected but was not found on this machine.`;
+}
+function normalizeBrowserFamily(browserFamily) {
+    if (browserFamily === "chrome" || browserFamily === "edge") {
+        return browserFamily;
+    }
+    throw new Error("A concrete browser family is required. Expected \"chrome\" or \"edge\".");
+}
+export async function listInstalledBrowsers({ platform = process.platform, env = process.env, homeDir = os.homedir(), accessFn = access, } = {}) {
     const browserGroups = listInstalledBrowserCandidates({ platform, env, homeDir });
+    const installedBrowsers = [];
     for (const browser of browserGroups) {
         for (const executablePath of browser.candidates) {
             if (await pathExistsAndIsRunnable(executablePath, platform, accessFn)) {
-                return {
+                installedBrowsers.push({
                     browserFamily: browser.browserFamily,
                     browserName: browser.browserName,
                     executablePath,
-                };
+                });
+                break;
             }
         }
     }
-    return null;
+    return installedBrowsers;
 }
-export async function getInstalledBrowserAvailability(options = {}) {
-    const resolved = await resolveInstalledBrowser(options);
+export async function resolveInstalledBrowser(browserFamily, options = {}) {
+    const selectedBrowserFamily = normalizeBrowserFamily(browserFamily);
+    const installedBrowsers = await listInstalledBrowsers(options);
+    const resolved = installedBrowsers.find((browser) => browser.browserFamily === selectedBrowserFamily);
     if (!resolved) {
+        throw new Error(buildMissingSelectedBrowserMessage(selectedBrowserFamily, options.platform ?? process.platform));
+    }
+    return resolved;
+}
+export async function getInstalledBrowserAvailability(options = {}) {
+    const installedBrowsers = await listInstalledBrowsers(options);
+    if (installedBrowsers.length === 0) {
         return {
             available: false,
-            browserFamily: null,
-            browserName: null,
-            executablePath: null,
+            installedBrowsers,
             message: buildMissingBrowserMessage(options.platform ?? process.platform),
         };
     }
     return {
         available: true,
-        browserFamily: resolved.browserFamily,
-        browserName: resolved.browserName,
-        executablePath: resolved.executablePath,
+        installedBrowsers,
         message: null,
     };
 }
-export async function requireInstalledBrowser(options = {}) {
-    const availability = await getInstalledBrowserAvailability(options);
-    if (!availability.available || !availability.browserName || !availability.executablePath) {
-        throw new Error(availability.message || buildMissingBrowserMessage(options.platform ?? process.platform));
-    }
-    return {
-        browserFamily: availability.browserFamily,
-        browserName: availability.browserName,
-        executablePath: availability.executablePath,
-    };
+export async function requireInstalledBrowser(browserFamily, options = {}) {
+    return await resolveInstalledBrowser(browserFamily, options);
 }

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

@@ -1,5 +1,34 @@
-import { readFile } from "fs/promises";
+import path from "path";
+import { access, readFile } from "fs/promises";
 import { parseTestScript } from "../test-store/test-script.js";
+async function canReadFile(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve a CLI instructions path, accepting extensionless .dcua names.
+ *
+ * @param {string} instructionsPath
+ * @returns {Promise<string>}
+ */
+export async function resolveHeadlessInstructionsPath(instructionsPath) {
+    if (await canReadFile(instructionsPath)) {
+        return instructionsPath;
+    }
+    if (path.extname(instructionsPath)) {
+        return instructionsPath;
+    }
+    const dcuaPath = `${instructionsPath}.dcua`;
+    if (await canReadFile(dcuaPath)) {
+        return dcuaPath;
+    }
+    return instructionsPath;
+}
 /**
  * Load runnable instructions from a headless .dcua script file.
  *
@@ -7,6 +36,13 @@ import { parseTestScript } from "../test-store/test-script.js";
  * @returns {Promise<string[]>}
  */
 export async function loadHeadlessInstructions(instructionsPath) {
-    const content = await readFile(instructionsPath, "utf-8");
+    let content;
+    try {
+        content = await readFile(instructionsPath, "utf-8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown file read error.";
+        throw new Error(`Could not read instructions file ${instructionsPath}: ${message}`);
+    }
     return parseTestScript(content);
 }

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

@@ -24,32 +24,155 @@ function normalizeSessionMode(value) {
     }
     throw new Error("--session-mode must be one of: persistent, fresh.");
 }
+function normalizeBrowser(value) {
+    if (value == null || value === "") {
+        return "chrome";
+    }
+    if (typeof value !== "string") {
+        throw new Error("--browser must be one of: chrome, edge.");
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "chrome" || normalized === "edge") {
+        return normalized;
+    }
+    throw new Error("--browser must be one of: chrome, edge.");
+}
+function normalizeDeviceSource(value) {
+    if (value == null || value === "") {
+        return "local";
+    }
+    if (typeof value !== "string") {
+        throw new Error("--device-source must be one of: local, lambdatest.");
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "local" || normalized === "lambdatest") {
+        return normalized;
+    }
+    throw new Error("--device-source must be one of: local, lambdatest.");
+}
+function normalizeMobilePlatform(value, label) {
+    if (!hasNonEmptyString(value)) {
+        return null;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "android" || normalized === "ios") {
+        return normalized;
+    }
+    throw new Error(`${label} must be one of: android, ios.`);
+}
 function hasNonEmptyString(value) {
     return typeof value === "string" && value.trim().length > 0;
 }
+function readNonEmptyCliValue(value) {
+    if (typeof value === "string" && value.trim().length > 0) {
+        return value.trim();
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return String(value);
+    }
+    return null;
+}
+function assertNoLambdaTestFlags(args) {
+    const lambdaTestFlags = [
+        ["device-name", "--device-name"],
+        ["os-version", "--os-version"],
+        ["app", "--app"],
+    ];
+    for (const [key, label] of lambdaTestFlags) {
+        if (args[key] != null) {
+            throw new Error(`${label} can only be used with --device-source lambdatest.`);
+        }
+    }
+}
+function normalizeLambdaTestAppPath(value) {
+    if (!hasNonEmptyString(value)) {
+        return null;
+    }
+    const appPath = value.trim();
+    const lower = appPath.toLowerCase();
+    if (lower.endsWith(".apk") || lower.endsWith(".ipa")) {
+        return appPath;
+    }
+    if (lower.endsWith(".app")) {
+        throw new Error("LambdaTest real-device sessions require an .apk for Android or an .ipa for iOS. .app bundles are not supported.");
+    }
+    throw new Error("--app must point to an .apk or .ipa file for LambdaTest runs.");
+}
 export function resolveHeadlessTarget(args = {}) {
     const target = normalizeTarget(args.target);
     const sessionMode = normalizeSessionMode(args["session-mode"]);
     const avdName = hasNonEmptyString(args.avd) ? args.avd.trim() : null;
-    const platform = hasNonEmptyString(args.platform) ? args.platform.trim() : null;
+    const platform = normalizeMobilePlatform(args.platform, "--platform");
+    const deviceSource = normalizeDeviceSource(args["device-source"]);
     if (target === "web") {
         if (avdName || platform) {
             throw new Error("--avd and --platform cannot be used with --target web.");
         }
+        if (deviceSource !== "local") {
+            throw new Error("--device-source can only be used with --target mobile.");
+        }
+        assertNoLambdaTestFlags(args);
         return {
             target,
             sessionMode,
+            browserFamily: normalizeBrowser(args.browser),
+            deviceSource: "local",
             avdName: null,
             platform: null,
+            deviceName: null,
+            osVersion: null,
+            appPath: null,
         };
     }
     if (args["session-mode"] != null) {
         throw new Error("--session-mode can only be used with --target web.");
     }
+    if (args.browser != null) {
+        throw new Error("--browser can only be used with --target web.");
+    }
+    if (deviceSource === "local") {
+        assertNoLambdaTestFlags(args);
+    }
+    if (deviceSource === "lambdatest") {
+        const deviceName = hasNonEmptyString(args["device-name"]) ? args["device-name"].trim() : null;
+        const osVersion = readNonEmptyCliValue(args["os-version"]);
+        const appPath = normalizeLambdaTestAppPath(args.app);
+        if (avdName) {
+            throw new Error("--avd cannot be used with --device-source lambdatest.");
+        }
+        if (!platform) {
+            throw new Error("--platform is required with --device-source lambdatest.");
+        }
+        if (!deviceName) {
+            throw new Error("--device-name is required with --device-source lambdatest.");
+        }
+        if (!osVersion) {
+            throw new Error("--os-version is required with --device-source lambdatest.");
+        }
+        if (!appPath) {
+            throw new Error("--app is required with --device-source lambdatest.");
+        }
+        return {
+            target,
+            sessionMode: null,
+            browserFamily: null,
+            deviceSource,
+            avdName: null,
+            platform,
+            deviceName,
+            osVersion,
+            appPath,
+        };
+    }
     return {
         target,
         sessionMode: null,
+        browserFamily: null,
+        deviceSource,
         avdName,
         platform,
+        deviceName: null,
+        osVersion: null,
+        appPath: null,
     };
 }