@loadmill/droid-cua 2.16.0 → 2.17.0

package/build/index.js

@@ -13,6 +13,7 @@ import { createOpenAiExecutor } from "./src/device/openai.js";
 import { logger } from "./src/utils/logger.js";
 import { selectDevice } from "./src/cli/device-selector.js";
 import { resolveExecutionAppContext } from "./src/core/app-context.js";
+import { resolveExecutionTestData } from "./src/core/test-data.js";
 import { createRunContext, resolveRuntimeConfigFromEnv, resolveRuntimeCredentialsFromEnv, } from "./src/core/runtime-config.js";
 import { resolveHeadlessExecutionConfig } from "./src/cli/headless-execution-config.js";
 import { resolveHeadlessTarget } from "./src/cli/headless-target.js";
@@ -20,6 +21,7 @@ import { createHeadlessDebugArtifacts } from "./src/cli/headless-debug.js";
 import { loadHeadlessInstructions } from "./src/cli/headless-instructions.js";
 import { listHeadlessInstructionFiles, resolveHeadlessInstructionsTarget } from "./src/cli/headless-instruction-target.js";
 import { runHeadlessInstructionRuns } from "./src/cli/headless-runner.js";
+import { planScenarioRuns } from "./src/cli/scenario-planner.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";
@@ -67,6 +69,41 @@ function wait(ms) {
 function isLambdaTestAppAutomationUrl(value) {
     return typeof value === "string" && value.startsWith("https://appautomation.lambdatest.com/test?");
 }
+async function loadScenarioCandidateRuns(runs) {
+    return await Promise.all(runs.map(async (run) => ({
+        ...run,
+        instructions: run.instructions ?? await loadHeadlessInstructions(run.testPath),
+    })));
+}
+function printScenarioCasePreview(cases) {
+    console.log(`\nScenario preview: ${cases.length} case${cases.length === 1 ? "" : "s"}\n`);
+    cases.forEach((entry, index) => {
+        console.log(`${index + 1}. ${entry.caseName}`);
+    });
+    console.log("");
+}
+function buildScenarioInstructionTarget(originalTarget, scenarioPrompt) {
+    return {
+        type: "scenario",
+        path: originalTarget?.path || null,
+        sourceType: originalTarget?.type || null,
+        scenarioPrompt,
+    };
+}
+function buildScenarioRuns({ candidateRuns, cases }) {
+    const runByTestName = new Map(candidateRuns.map((run) => [run.testName, run]));
+    return cases.map((entry) => {
+        const sourceRun = runByTestName.get(entry.testName);
+        return {
+            ...sourceRun,
+            testName: entry.caseName,
+            sourceTestName: entry.testName,
+            scenarioCaseName: entry.caseName,
+            testDataContext: entry.testDataContext,
+            instructions: sourceRun.instructions,
+        };
+    });
+}
 async function resolveLambdaTestDashboardUrl(credentials, sessionId, { attempts = 1, delayMs = 1000 } = {}) {
     const adapter = getCloudProviderAdapter("lambdatest");
     for (let attempt = 1; attempt <= attempts; attempt += 1) {
@@ -107,10 +144,17 @@ async function main() {
     if (isLambdaTestTarget && !isHeadlessInstructionsRun) {
         throw new Error("--device-source lambdatest is only supported with --instructions headless execution.");
     }
+    if (!isHeadlessInstructionsRun && args.scenario != null) {
+        throw new Error("--scenario can only be used with --instructions headless execution.");
+    }
+    if (!isHeadlessInstructionsRun && args["test-data"] != null) {
+        throw new Error("--test-data can only be used with --instructions headless execution.");
+    }
     let preloadedHeadlessConfig = null;
     let preloadedHeadlessTarget = null;
     let headlessInstructionRuns = [];
     let preloadedAppContext = null;
+    let preloadedTestData = null;
     if (isHeadlessInstructionsRun) {
         preloadedHeadlessConfig = await resolveHeadlessExecutionConfig(args);
         preloadedHeadlessTarget = await resolveHeadlessInstructionsTarget(instructionsFile);
@@ -139,6 +183,14 @@ async function main() {
         if (preloadedAppContext.status === "failed") {
             throw new Error(`Could not read app context file ${preloadedAppContext.contextPath}: ${preloadedAppContext.message}`);
         }
+        if (preloadedHeadlessConfig.scenarioPrompt) {
+            preloadedTestData = await resolveExecutionTestData({
+                testDataPath: preloadedHeadlessConfig.testDataPath,
+            });
+            if (preloadedTestData.status === "failed") {
+                throw new Error(`Could not read test data file ${preloadedTestData.testDataPath}: ${preloadedTestData.message}`);
+            }
+        }
     }
     // If no device specified, show interactive selection menu
     if (!isBrowserTarget && !isLambdaTestTarget && !avdName && !platform) {
@@ -236,6 +288,26 @@ async function main() {
             });
             console.log(`Using AI provider: ${runtimeContext.config.llmProviderMode}`);
             console.log(`Using CUA model: ${runtimeContext.config.cuaModel}`);
+            if (headlessConfig.scenarioPrompt) {
+                const candidateRuns = await loadScenarioCandidateRuns(headlessInstructionRuns);
+                const scenarioCases = await planScenarioRuns({
+                    client: runtimeContext.openAiClient,
+                    runtimeConfig: runtimeContext.config,
+                    scenarioPrompt: headlessConfig.scenarioPrompt,
+                    tests: candidateRuns.map((run) => ({
+                        testName: run.testName,
+                        instructions: run.instructions,
+                    })),
+                    appContextText,
+                    testDataText: preloadedTestData?.text || "",
+                });
+                printScenarioCasePreview(scenarioCases);
+                headlessInstructionRuns = buildScenarioRuns({
+                    candidateRuns,
+                    cases: scenarioCases,
+                });
+                preloadedHeadlessTarget = buildScenarioInstructionTarget(preloadedHeadlessTarget, headlessConfig.scenarioPrompt);
+            }
             const result = await runHeadlessInstructionRuns({
                 runs: headlessInstructionRuns,
                 instructionsTarget: preloadedHeadlessTarget,

package/build/src/cli/headless-execution-config.js

@@ -172,6 +172,10 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
     const cwd = typeof options.cwd === "string" ? options.cwd : process.cwd();
     const configPath = typeof args.config === "string" ? args.config : null;
     const explicitContextPath = typeof args.context === "string" ? path.resolve(cwd, args.context) : null;
+    const scenarioPrompt = typeof args.scenario === "string" ? args.scenario.trim() : null;
+    const hasScenarioFlag = args.scenario != null;
+    const testDataPath = typeof args["test-data"] === "string" ? path.resolve(cwd, args["test-data"]) : null;
+    const hasTestDataFlag = args["test-data"] != null;
     const noContext = args["no-context"] === true || args.context === false;
     const contextOptimizationEnabledByFlag = args["context-optimization"] === true;
     const noContextOptimization = args["no-context-optimization"] === true || args["context-optimization"] === false;
@@ -183,6 +187,15 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
     if (explicitContextPath && noContext) {
         throw new Error("--context and --no-context cannot be used together.");
     }
+    if (hasScenarioFlag && !scenarioPrompt) {
+        throw new Error("--scenario must be a non-empty string.");
+    }
+    if (hasTestDataFlag && !testDataPath) {
+        throw new Error("--test-data must be a non-empty path.");
+    }
+    if (testDataPath && !scenarioPrompt) {
+        throw new Error("--test-data can only be used with --scenario.");
+    }
     if (contextOptimizationEnabledByFlag) {
         throw new Error("--context-optimization is not supported; Context Optimization is enabled by default.");
     }
@@ -202,6 +215,8 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
         promptCustomizations,
         appContextEnabled: fileConfig?.appContextEnabled ?? true,
         appContextPath: fileConfig?.appContextPath || null,
+        scenarioPrompt,
+        testDataPath,
         contextOptimizationEnabled: fileConfig?.contextOptimizationEnabled ?? true,
         contextOptimizationThreshold: fileConfig?.contextOptimizationThreshold ?? DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD,
     };

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

@@ -100,11 +100,12 @@ function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, executionP
     }
     return engineOptions;
 }
-async function runHeadlessTest({ runId, testPath, testName, instructions, session, deviceInfo, headlessConfig, appContext, runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isLambdaTestTarget }) {
+async function runHeadlessTest({ runId, testPath, testName, instructions, session, deviceInfo, headlessConfig, appContext, testDataContext = "", runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isLambdaTestTarget }) {
     let executionMode = null;
     try {
         await headlessDebug.startExecutionSession(runId, {
             testName,
+            ...(testDataContext ? { testDataUsed: true } : {}),
             platform: deviceInfo.platform,
             deviceName: deviceInfo.device_name,
             aimAssistMode: headlessConfig.aimAssistMode
@@ -119,7 +120,10 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
         emitCliAppContextDebug(runId, appContext, appContextText);
         session.updateResponseId(undefined);
         session.clearMessages();
-        const executionPrompt = buildExecutionModePrompt(deviceInfo, headlessConfig.promptCustomizations, appContextText, { aimAssistMode: headlessConfig.aimAssistMode });
+        const executionPrompt = buildExecutionModePrompt(deviceInfo, headlessConfig.promptCustomizations, appContextText, {
+            aimAssistMode: headlessConfig.aimAssistMode,
+            testDataContext,
+        });
         session.setSystemPrompt(executionPrompt);
         const screenshotRecorder = headlessDebug.createExecutionScreenshotRecorder({
             runId,
@@ -188,9 +192,12 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
         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) {
+export async function runHeadlessInstructionRuns({ runs, instructionsTarget, session, deviceInfo, headlessConfig, appContext, runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isLambdaTestTarget, runHeadlessTestImpl = runHeadlessTest }) {
+    const isBatchRun = instructionsTarget?.type === "directory" || instructionsTarget?.type === "scenario";
+    if (instructionsTarget?.type === "scenario") {
+        console.log(`\nRunning ${runs.length} scenario case${runs.length === 1 ? "" : "s"}\n`);
+    }
+    else if (isBatchRun) {
         console.log(`\nRunning ${runs.length} tests from: ${instructionsTarget.path}\n`);
     }
     let failures = 0;
@@ -205,7 +212,7 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
             if (recordScreenshots && testScreenshotDir) {
                 await mkdir(testScreenshotDir, { recursive: true });
             }
-            const result = await runHeadlessTest({
+            const result = await runHeadlessTestImpl({
                 runId,
                 testPath: run.testPath,
                 testName: run.testName,
@@ -214,6 +221,7 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
                 deviceInfo,
                 headlessConfig,
                 appContext,
+                testDataContext: run.testDataContext || "",
                 runtimeContext,
                 headlessDebug,
                 recordScreenshots,
@@ -234,7 +242,11 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
             console.error(`\nTest failed: ${run.testName}: ${message}`);
         }
     }
-    if (isBatchRun) {
+    if (instructionsTarget?.type === "scenario") {
+        const passed = runs.length - failures;
+        console.log(`\nScenario run complete: ${passed}/${runs.length} passed`);
+    }
+    else if (isBatchRun) {
         const passed = runs.length - failures;
         console.log(`\nFolder run complete: ${passed}/${runs.length} passed`);
     }

package/build/src/cli/scenario-planner.js

@@ -0,0 +1 @@
+export { planScenarioRuns, validateScenarioCases, } from "../core/scenario-planner.js";

package/build/src/commands/help.js

@@ -26,6 +26,8 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  --os-version <version> LambdaTest OS version' });
     addOutput({ type: 'info', text: '  --app <path>           LambdaTest app package path (.apk or .ipa)' });
     addOutput({ type: 'info', text: '  --instructions <file>  Run test file in headless mode' });
+    addOutput({ type: 'info', text: '  --scenario <prompt>    Generate and run scenario cases for headless instructions' });
+    addOutput({ type: 'info', text: '  --test-data <file>     Optional test-data.md file for --scenario' });
     addOutput({ type: 'info', text: '  --session-mode <mode>  Browser session mode for web runs: persistent or fresh' });
     addOutput({ type: 'info', text: '  --config <file>        Headless execution JSON config for prompt parity' });
     addOutput({ type: 'info', text: '  --llm-provider <mode>  Headless AI provider: loadmill or openai' });
@@ -80,6 +82,7 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  droid-cua --avd "iPhone 16"             (iOS Simulator, auto-detected)' });
     addOutput({ type: 'info', text: '  droid-cua --platform ios --avd MySim    (Force iOS platform)' });
     addOutput({ type: 'info', text: '  droid-cua --instructions tests/login.dcua --context app/context.md' });
+    addOutput({ type: 'info', text: '  droid-cua --instructions tests --test-data tests/test-data.md --scenario "Run every checkout test with each buyer account"' });
     addOutput({ type: 'info', text: '  droid-cua --target web --instructions tests/search.dcua' });
     addOutput({ type: 'info', text: '  droid-cua --device-source lambdatest --platform android --device-name "Galaxy S24" --os-version 14 --app app.apk --instructions tests/login.dcua' });
     addOutput({ type: 'info', text: '  /create login-test                      (design a new test)' });

package/build/src/core/prompts.js

@@ -1,3 +1,3 @@
 export { buildBaseSystemPrompt } from "../prompts/base.js";
 export { buildDesignModePrompt, buildDesignRecoveryPrompt, buildDesignScriptGenerationPrompt, } from "../prompts/design.js";
-export { buildAppContextSection, buildAssertionSystemPrompt, buildExecutionModePrompt, buildExecutionNavigationRecoveryPrompt, buildExecutionRecoveryPrompt, } from "../prompts/execution.js";
+export { buildAppContextSection, buildAssertionSystemPrompt, buildExecutionModePrompt, buildExecutionNavigationRecoveryPrompt, buildExecutionRecoveryPrompt, buildTestDataContextSection, } from "../prompts/execution.js";

package/build/src/core/scenario-planner.js

@@ -0,0 +1,85 @@
+import { resolveEffectiveHelperModel } from "./runtime-config.js";
+import { buildScenarioPlannerMessages } from "../prompts/scenario-planner.js";
+function parseScenarioPlannerContent(content) {
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Invalid JSON.";
+        throw new Error(`Could not parse scenario planner response: ${message}`);
+    }
+}
+function normalizeCaseName(value, fallback) {
+    const trimmed = typeof value === "string" ? value.trim() : "";
+    return trimmed || fallback;
+}
+function dedupeCaseNames(cases) {
+    const usedNames = new Set();
+    const baseCounts = new Map();
+    return cases.map((entry) => {
+        const baseName = entry.caseName;
+        let nextIndex = baseCounts.get(baseName) || 1;
+        let caseName = baseName;
+        while (usedNames.has(caseName)) {
+            nextIndex += 1;
+            caseName = `${baseName} (${nextIndex})`;
+        }
+        baseCounts.set(baseName, nextIndex);
+        usedNames.add(caseName);
+        return {
+            ...entry,
+            caseName,
+        };
+    });
+}
+export function validateScenarioCases(rawCases, candidateTests) {
+    if (!Array.isArray(rawCases) || rawCases.length === 0) {
+        throw new Error("Scenario planner did not return any cases.");
+    }
+    const candidateNames = new Set(candidateTests.map((test) => test.testName));
+    const normalizedCases = rawCases.map((rawCase, index) => {
+        if (!rawCase || typeof rawCase !== "object" || Array.isArray(rawCase)) {
+            throw new Error(`Scenario case ${index + 1} must be an object.`);
+        }
+        const testName = typeof rawCase.testName === "string" ? rawCase.testName.trim() : "";
+        if (!candidateNames.has(testName)) {
+            throw new Error(`Scenario case ${index + 1} references unknown test "${testName || "(missing)"}".`);
+        }
+        const caseName = normalizeCaseName(rawCase.caseName, `${testName} / Case ${index + 1}`);
+        const testDataContext = typeof rawCase.testDataContext === "string" ? rawCase.testDataContext.trim() : "";
+        return {
+            testName,
+            caseName,
+            testDataContext,
+        };
+    });
+    return dedupeCaseNames(normalizedCases);
+}
+export async function planScenarioRuns({ client, runtimeConfig, scenarioPrompt, tests, appContextText = "", testDataText = "", }) {
+    if (!client?.chat?.completions?.create) {
+        throw new Error("Scenario planning requires an LLM client.");
+    }
+    const prompt = typeof scenarioPrompt === "string" ? scenarioPrompt.trim() : "";
+    if (!prompt) {
+        throw new Error("--scenario must be a non-empty string.");
+    }
+    if (!Array.isArray(tests) || tests.length === 0) {
+        throw new Error("Scenario planning requires at least one candidate test.");
+    }
+    const response = await client.chat.completions.create({
+        model: resolveEffectiveHelperModel({
+            llmProviderMode: runtimeConfig?.llmProviderMode,
+            cuaModel: runtimeConfig?.cuaModel,
+        }),
+        messages: buildScenarioPlannerMessages({
+            scenarioPrompt: prompt,
+            tests,
+            appContextText,
+            testDataText,
+        }),
+        response_format: { type: "json_object" },
+    });
+    const content = response.choices?.[0]?.message?.content || "{}";
+    const parsed = parseScenarioPlannerContent(content);
+    return validateScenarioCases(parsed.cases, tests);
+}

package/build/src/core/test-data-import.js

@@ -0,0 +1,62 @@
+import path from "path";
+import { resolveEffectiveHelperModel } from "./runtime-config.js";
+import { buildTestDataImportMessages } from "../prompts/test-data-import.js";
+export const TEST_DATA_IMPORT_EXTENSIONS = [".csv", ".txt"];
+export function isSupportedTestDataImportPath(filePath) {
+    return TEST_DATA_IMPORT_EXTENSIONS.includes(path.extname(String(filePath ?? "")).toLowerCase());
+}
+export function assertSupportedTestDataImportPath(filePath) {
+    if (!isSupportedTestDataImportPath(filePath)) {
+        throw new Error("Test data import supports CSV and TXT files only.");
+    }
+}
+function parseTestDataImportContent(content) {
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Invalid JSON.";
+        throw new Error(`Could not parse test data import response: ${message}`);
+    }
+}
+function normalizeGeneratedContent(value) {
+    const content = typeof value === "string" ? value.trim() : "";
+    if (!content) {
+        throw new Error("Test data import returned empty content.");
+    }
+    if (/^```/.test(content)) {
+        throw new Error("Test data import returned code-fenced content instead of markdown.");
+    }
+    return content.endsWith("\n") ? content : `${content}\n`;
+}
+export async function importTestDataMarkdown({ client, runtimeConfig, currentContent = "", importedFileName, importedFileText, instructions = "", }) {
+    if (!client?.chat?.completions?.create) {
+        throw new Error("Test data import requires an LLM client.");
+    }
+    const fileName = typeof importedFileName === "string" ? importedFileName.trim() : "";
+    if (!fileName) {
+        throw new Error("Imported file name is required.");
+    }
+    const fileText = typeof importedFileText === "string" ? importedFileText : "";
+    if (!fileText.trim()) {
+        throw new Error("Selected import file is empty.");
+    }
+    const response = await client.chat.completions.create({
+        model: resolveEffectiveHelperModel({
+            llmProviderMode: runtimeConfig?.llmProviderMode,
+            cuaModel: runtimeConfig?.cuaModel,
+        }),
+        messages: buildTestDataImportMessages({
+            currentContent,
+            importedFileName: fileName,
+            importedFileText: fileText,
+            instructions,
+        }),
+        response_format: { type: "json_object" },
+    });
+    const content = response.choices?.[0]?.message?.content || "{}";
+    const parsed = parseTestDataImportContent(content);
+    return {
+        content: normalizeGeneratedContent(parsed.content),
+    };
+}

package/build/src/core/test-data.js

@@ -0,0 +1,103 @@
+import path from "path";
+import { access, readFile } from "fs/promises";
+import { constants as fsConstants } from "fs";
+export const TEST_DATA_FILENAME = "test-data.md";
+export const DEFAULT_TEST_DATA_TEMPLATE = `# Test Data
+<!-- Concrete data the agent can use during Scenario Runs. Keep entries named and specific. -->
+<!-- Examples below are commented out so they are guidance, not usable test data. -->
+
+## Accounts
+<!--
+### Standard buyer
+Email:
+Password:
+Notes: When should the agent use this account?
+-->
+
+## Products
+<!--
+### In-stock product
+Name:
+SKU:
+Notes:
+-->
+
+## Payment Methods
+<!--
+### Valid card
+Number:
+Expiration:
+CVV:
+Notes:
+-->
+
+## Roles and Permissions
+
+## Regions and Locales
+
+## Other Data
+`;
+export function getDefaultProjectTestDataPath(projectPath) {
+    return path.join(projectPath, TEST_DATA_FILENAME);
+}
+export function normalizeTestDataTemplateText(text) {
+    return String(text ?? "").replace(/\r\n?/g, "\n").replace(/[ \t]+$/gm, "").trimEnd();
+}
+export function isDefaultTestDataTemplate(text) {
+    if (!String(text ?? "").trim()) {
+        return true;
+    }
+    return normalizeTestDataTemplateText(text) === normalizeTestDataTemplateText(DEFAULT_TEST_DATA_TEMPLATE);
+}
+export async function readTestDataFile(filePath) {
+    await access(filePath, fsConstants.R_OK);
+    return await readFile(filePath, "utf-8");
+}
+export async function loadTestData({ testDataPath }) {
+    if (!testDataPath) {
+        return { text: "", testDataPath: null };
+    }
+    const text = await readTestDataFile(testDataPath);
+    return { text, testDataPath };
+}
+/**
+ * @param {{
+ *   testDataPath?: string | null,
+ *   missingFileStatus?: string | null,
+ * }} [options]
+ */
+export async function resolveExecutionTestData({ testDataPath = null, missingFileStatus = null, } = {}) {
+    if (!testDataPath) {
+        return {
+            status: "omitted",
+            text: "",
+            testDataPath: null,
+            message: null,
+        };
+    }
+    try {
+        const result = await loadTestData({ testDataPath });
+        return {
+            status: result.text.trim().length > 0 ? "loaded" : "empty",
+            text: result.text,
+            testDataPath: result.testDataPath,
+            message: null,
+        };
+    }
+    catch (error) {
+        if (missingFileStatus && error && typeof error === "object" && error.code === "ENOENT") {
+            return {
+                status: missingFileStatus,
+                text: "",
+                testDataPath,
+                message: null,
+            };
+        }
+        return {
+            status: "failed",
+            text: "",
+            testDataPath,
+            message: error instanceof Error ? error.message : "Unknown test data error",
+        };
+    }
+}

package/build/src/prompts/execution.js

@@ -9,6 +9,17 @@ export function buildAppContextSection(text) {
 The following describes the app you are testing.
 Use this to understand screen layouts, terminology, navigation, and expected behavior.
 
+${trimmed}`;
+}
+export function buildTestDataContextSection(text) {
+    const trimmed = typeof text === "string" ? text.trim() : "";
+    if (!trimmed) {
+        return "";
+    }
+    return `TEST DATA FOR THIS RUN:
+The following values are test data for this execution. Use them as literal run data when performing the test.
+They do not replace or override the test instructions.
+
 ${trimmed}`;
 }
 export function buildExecutionModePrompt(deviceInfo, customInstructions = {}, appContextText = "", options = {}) {
@@ -16,6 +27,7 @@ export function buildExecutionModePrompt(deviceInfo, customInstructions = {}, ap
     const aimAssistMode = typeof options.aimAssistMode === "string" ? options.aimAssistMode : DEFAULT_AIM_ASSIST_MODE;
     const basePrompt = buildBaseSystemPrompt(deviceInfo, { aimAssistMode });
     const appContextSection = buildAppContextSection(appContextText);
+    const testDataContextSection = buildTestDataContextSection(options.testDataContext);
     const browserTarget = isBrowserTarget(deviceInfo);
     const prompt = `${basePrompt}
 
@@ -52,7 +64,7 @@ Your process:
 7. Stop immediately - no commentary, no questions
 
 Each instruction is independent. Do not reference previous instructions or ask about next steps.
-${appContextSection ? `\n\n${appContextSection}` : ""}`;
+${appContextSection ? `\n\n${appContextSection}` : ""}${testDataContextSection ? `\n\n${testDataContextSection}` : ""}`;
     return appendCustomSections(prompt, [
         { title: "Base Prompt Instructions", text: customInstructions.basePromptInstructions },
         { title: "Execution Mode Instructions", text: executionCustomText }

package/build/src/prompts/scenario-planner.js

@@ -0,0 +1,48 @@
+function formatCandidateTests(tests) {
+    return tests.map((test, index) => {
+        const content = Array.isArray(test.instructions) ? test.instructions.join("\n") : "";
+        return [
+            `TEST ${index + 1}`,
+            `Name: ${test.testName}`,
+            "Instructions:",
+            content || "(empty)",
+        ].join("\n");
+    }).join("\n\n---\n\n");
+}
+export function buildScenarioPlannerMessages({ scenarioPrompt, tests, appContextText = "", testDataText = "", }) {
+    return [
+        {
+            role: "system",
+            content: [
+                "You prepare concrete test executions for a computer-using agent.",
+                "The agent runs manual-style app tests: it receives a test brief, app context, and optional run data, then operates the app UI.",
+                "Your job is to turn the user's scenario request into the exact ordered cases the agent should run.",
+                "Return JSON only with this shape:",
+                "{\"cases\":[{\"testName\":\"exact-test-name.dcua\",\"caseName\":\"test-name.dcua / data label\",\"testDataContext\":\"raw data text for this case\"}]}",
+                "Rules:",
+                "- testName must exactly match one of the provided candidate test names.",
+                "- Create an ordered flat list of cases to run.",
+                "- caseName is an ephemeral display name for logs and reports. Keep it short and human-readable.",
+                "- testDataContext must contain only the concrete data relevant to that case.",
+                "- Do not invent data that was not provided in test data, context, or the scenario prompt.",
+                "- If no extra data is needed for a case, use an empty string for testDataContext.",
+            ].join("\n")
+        },
+        {
+            role: "user",
+            content: [
+                "Scenario prompt:",
+                scenarioPrompt,
+                "",
+                "App context:",
+                appContextText && appContextText.trim() ? appContextText.trim() : "(none)",
+                "",
+                "Project test data:",
+                testDataText && testDataText.trim() ? testDataText.trim() : "(none)",
+                "",
+                "Candidate tests:",
+                formatCandidateTests(tests),
+            ].join("\n")
+        }
+    ];
+}

package/build/src/prompts/test-data-import.js

@@ -0,0 +1,49 @@
+import { DEFAULT_TEST_DATA_TEMPLATE, isDefaultTestDataTemplate } from "../core/test-data.js";
+export function buildTestDataImportMessages({ currentContent = "", importedFileName, importedFileText, instructions = "", }) {
+    const currentIsTemplateOnly = isDefaultTestDataTemplate(currentContent);
+    const userInstructions = typeof instructions === "string" && instructions.trim()
+        ? instructions.trim()
+        : "(none)";
+    return [
+        {
+            role: "system",
+            content: [
+                "You convert imported data into durable project test data for computer-using-agent scenario runs.",
+                "The durable format is test-data.md: readable markdown that describes concrete entities and run data the agent can use.",
+                "Return JSON only with this shape:",
+                "{\"content\":\"# Test Data\\n...complete markdown...\"}",
+                "Rules:",
+                "- Return the complete replacement content for test-data.md, not a patch.",
+                "- Do not invent values that are not present in the current file, imported file, or user instructions.",
+                "- If currentContent is template-only, replace it with real imported data and do not keep commented template examples.",
+                "- If currentContent is not template-only, preserve its useful structure and add or update entities within it.",
+                "- For matrix-like CSV rows, prefer splitting repeated dimensions into separate entities when the structure is clear.",
+                "- If rows are indivisible scenarios or examples, keep them grouped as Test Data Entries or Use Case Data.",
+                "- User instructions can guide structure and naming, but content must remain concrete data, not test instructions.",
+                "- Output markdown only inside the JSON content string; do not use code fences.",
+            ].join("\n")
+        },
+        {
+            role: "user",
+            content: [
+                "Current test-data.md status:",
+                currentIsTemplateOnly ? "template-only" : "existing user content",
+                "",
+                "Default template used for template-only detection:",
+                DEFAULT_TEST_DATA_TEMPLATE.trimEnd(),
+                "",
+                "Current test-data.md content:",
+                String(currentContent ?? "").trim() ? String(currentContent) : "(empty)",
+                "",
+                "Imported file:",
+                importedFileName,
+                "",
+                "Imported file text:",
+                importedFileText,
+                "",
+                "User import instructions:",
+                userInstructions,
+            ].join("\n")
+        }
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loadmill/droid-cua",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "AI-powered Android testing agent using OpenAI's computer-use model and ADB",
   "main": "build/index.js",
   "type": "module",