openuispec 0.2.9 → 0.2.11

package/mcp-server/screenshot-android.ts

@@ -17,6 +17,7 @@ import {
 } from "./screenshot-shared.js";
 
 const exec = promisify(execCb);
+const androidScreenshotQueues = new Map<string, Promise<void>>();
 
 // ── types ───────────────────────────────────────────────────────────
 
@@ -31,6 +32,21 @@ export interface AndroidScreenshotOptions {
   module?: string;
 }
 
+export interface AndroidBatchCapture {
+  screen: string;
+  route?: string;
+  nav?: string[];
+  wait_for?: number;
+}
+
+export interface AndroidScreenshotBatchOptions {
+  captures: AndroidBatchCapture[];
+  theme?: "light" | "dark";
+  output_dir?: string;
+  project_dir?: string;
+  module?: string;
+}
+
 // ── constants ───────────────────────────────────────────────────────
 
 const ADB_SCREENSHOT_PATH = "/sdcard/openuispec_screenshot.png";
@@ -282,6 +298,27 @@ export async function installAndLaunch(
   }
 }
 
+export async function launchInstalledApp(
+  adb: string,
+  serial: string,
+  appInfo: AppInfo,
+  route?: string,
+): Promise<void> {
+  await adbShell(adb, serial, `am force-stop ${appInfo.applicationId}`);
+  // Clear saved nav state so deep links route correctly
+  try { await adbShell(adb, serial, `pm clear ${appInfo.applicationId}`); } catch { /* ignore */ }
+  if (route) {
+    await adbShell(
+      adb,
+      serial,
+      `am start -W -a android.intent.action.VIEW -d '${route}' ` +
+        `${appInfo.applicationId}/${appInfo.launchActivity}`,
+    );
+  } else {
+    await adbShell(adb, serial, `am start -W -n ${appInfo.applicationId}/${appInfo.launchActivity}`);
+  }
+}
+
 // ── theme control ───────────────────────────────────────────────────
 
 export async function setTheme(adb: string, serial: string, theme: "light" | "dark"): Promise<void> {
@@ -358,9 +395,12 @@ export async function captureScreenshot(
   serial: string,
   localPath: string,
 ): Promise<void> {
-  await adbShell(adb, serial, `screencap -p ${ADB_SCREENSHOT_PATH}`);
-  await adbExec(adb, serial, `pull ${ADB_SCREENSHOT_PATH} "${localPath}"`);
-  await adbShell(adb, serial, `rm ${ADB_SCREENSHOT_PATH}`);
+  try {
+    await exec(`${adb} -s ${serial} exec-out screencap -p > "${localPath}"`, { timeout: 60_000, shell: "/bin/bash" });
+  } catch (err: any) {
+    const output = ((err.stderr ?? "") + "\n" + (err.stdout ?? "")).trim();
+    throw new Error(`Android screenshot capture failed${output ? `:\n${output}` : "."}`);
+  }
 }
 
 // ── wait for app ready ──────────────────────────────────────────────
@@ -395,6 +435,47 @@ async function waitForAppReady(
   await new Promise(r => setTimeout(r, waitMs));
 }
 
+async function takeSingleAndroidCapture(
+  adb: string,
+  serial: string,
+  androidDir: string,
+  appInfo: AppInfo,
+  capture: AndroidBatchCapture,
+  theme: "light" | "dark" | undefined,
+  defaultOutputDir: string | undefined,
+): Promise<{ screen: string; path: string; data: string }> {
+  await launchInstalledApp(adb, serial, appInfo, capture.route);
+  await waitForAppReady(adb, serial, appInfo.applicationId, capture.wait_for ?? 3000);
+
+  if (capture.nav && capture.nav.length > 0) {
+    await navigateByTaps(adb, serial, capture.nav);
+  }
+
+  const themeLabel = theme ?? "default";
+  const filename = `${capture.screen}_${themeLabel}.png`;
+  const tmpPath = join(androidDir, `.openuispec-screenshot-${capture.screen}.png`);
+  await captureScreenshot(adb, serial, tmpPath);
+
+  let savedPath = filename;
+  if (defaultOutputDir) {
+    const outDir = resolve(androidDir, defaultOutputDir);
+    mkdirSync(outDir, { recursive: true });
+    savedPath = join(outDir, filename);
+    copyFileSync(tmpPath, savedPath);
+  }
+
+  try {
+    const data = readFileSync(tmpPath).toString("base64");
+    return {
+      screen: capture.screen,
+      path: savedPath,
+      data,
+    };
+  } finally {
+    try { unlinkSync(tmpPath); } catch { /* ignore */ }
+  }
+}
+
 // ── main entry point ────────────────────────────────────────────────
 
 export async function takeAndroidScreenshot(
@@ -420,61 +501,121 @@ export async function takeAndroidScreenshot(
   const adb = findAdb();
   const serial = await getConnectedEmulator(adb);
 
-  // 3. Free emulator storage before build/install
-  await cleanEmulatorStorage(adb, serial);
+  const previousRun = androidScreenshotQueues.get(serial) ?? Promise.resolve();
+  let releaseQueue: (() => void) | undefined;
+  const currentRun = new Promise<void>((resolve) => {
+    releaseQueue = resolve;
+  });
+  androidScreenshotQueues.set(serial, previousRun.then(() => currentRun));
 
-  // 4. Build APK
-  const apkPath = await buildApk(androidDir, appInfo.moduleName);
+  await previousRun;
 
-  // 5. Set theme if requested
-  if (theme) {
-    await setTheme(adb, serial, theme);
-  }
+  try {
+    // 3. Free emulator storage before build/install
+    await cleanEmulatorStorage(adb, serial);
 
-  // 6. Install and launch
-  await installAndLaunch(adb, serial, apkPath, appInfo, route);
+    // 4. Build APK
+    const apkPath = await buildApk(androidDir, appInfo.moduleName);
 
-  // 7. Wait for app to be ready and content to load
-  await waitForAppReady(adb, serial, appInfo.applicationId, wait_for);
+    // 5. Set theme if requested
+    if (theme) {
+      await setTheme(adb, serial, theme);
+    }
 
-  // 8. Navigate via UI taps if specified
-  if (nav && nav.length > 0) {
-    await navigateByTaps(adb, serial, nav);
-  }
+    // 6. Install fresh once, then capture
+    await installAndLaunch(adb, serial, apkPath, appInfo, route);
+
+    const snapshot = await takeSingleAndroidCapture(
+      adb,
+      serial,
+      androidDir,
+      appInfo,
+      { screen: screen ?? "main", route, nav, wait_for },
+      theme,
+      output_dir,
+    );
 
-  // 9. Capture screenshot
-  const screenLabel = screen ?? "main";
-  const themeLabel = theme ?? "default";
-  const filename = `${screenLabel}_${themeLabel}.png`;
-  const tmpPath = join(androidDir, ".openuispec-screenshot.png");
-  await captureScreenshot(adb, serial, tmpPath);
+    return buildScreenshotResponse([snapshot], (s) => ({
+      screen: s.screen,
+      path: snapshot.path ?? null,
+      emulator: serial,
+      theme: theme ?? "default",
+      applicationId: appInfo.applicationId,
+    }));
+  } finally {
+    releaseQueue?.();
+    if (androidScreenshotQueues.get(serial) === currentRun) {
+      androidScreenshotQueues.delete(serial);
+    }
+  }
+}
 
-  // 9. Save to output_dir if specified
-  let savedPath: string | undefined;
-  if (output_dir) {
-    const outDir = resolve(androidDir, output_dir);
-    mkdirSync(outDir, { recursive: true });
-    savedPath = join(outDir, filename);
-    copyFileSync(tmpPath, savedPath);
+export async function takeAndroidScreenshotBatch(
+  projectCwd: string,
+  options: AndroidScreenshotBatchOptions,
+): Promise<ScreenshotResult> {
+  const { captures, theme, output_dir, project_dir, module } = options;
+  if (captures.length === 0) {
+    return {
+      content: [{ type: "text", text: "No Android captures specified." }],
+      isError: true,
+    };
   }
 
-  // 10. Read and return
+  const androidDir = findAndroidAppDir(projectCwd, project_dir);
+  const appInfo = extractAppInfo(androidDir, module);
+  const adb = findAdb();
+  const serial = await getConnectedEmulator(adb);
+
+  const previousRun = androidScreenshotQueues.get(serial) ?? Promise.resolve();
+  let releaseQueue: (() => void) | undefined;
+  const currentRun = new Promise<void>((resolve) => {
+    releaseQueue = resolve;
+  });
+  androidScreenshotQueues.set(serial, previousRun.then(() => currentRun));
+
+  await previousRun;
+
   try {
-    const data = readFileSync(tmpPath).toString("base64");
-    const snapshots = [{
-      screen: screenLabel,
-      path: savedPath ?? filename,
-      data,
-    }];
+    await cleanEmulatorStorage(adb, serial);
+    const apkPath = await buildApk(androidDir, appInfo.moduleName);
 
-    return buildScreenshotResponse(snapshots, (s) => ({
-      screen: s.screen,
-      path: savedPath ?? null,
+    if (theme) {
+      await setTheme(adb, serial, theme);
+    }
+
+    await installAndLaunch(adb, serial, apkPath, appInfo);
+
+    // Pre-create output dir once
+    if (output_dir) mkdirSync(resolve(androidDir, output_dir), { recursive: true });
+
+    const snapshots = [];
+    for (let index = 0; index < captures.length; index += 1) {
+      const capture = captures[index];
+      snapshots.push(
+        await takeSingleAndroidCapture(
+          adb,
+          serial,
+          androidDir,
+          appInfo,
+          capture,
+          theme,
+          output_dir,
+        ),
+      );
+    }
+
+    return buildScreenshotResponse(snapshots, (snapshot) => ({
+      screen: snapshot.screen,
+      path: snapshot.path,
       emulator: serial,
-      theme: themeLabel,
+      theme: theme ?? "default",
       applicationId: appInfo.applicationId,
     }));
   } finally {
-    try { unlinkSync(tmpPath); } catch { /* ignore */ }
+    releaseQueue?.();
+    if (androidScreenshotQueues.get(serial) === currentRun) {
+      androidScreenshotQueues.delete(serial);
+    }
   }
 }

package/mcp-server/screenshot-ios.ts

@@ -233,6 +233,45 @@ async function setAppearance(udid: string, theme: "light" | "dark"): Promise<voi
 const UITEST_TARGET = "ScreenshotUITests";
 const UITEST_DIR = ".screenshot-uitest";
 
+export function generateUITestTargetYml(
+  appInfo: IOSAppInfo,
+  sourcePath: string,
+  includeProductName = false,
+): string {
+  const productLines = includeProductName
+    ? `\n        PRODUCT_NAME: ${UITEST_TARGET}\n        PRODUCT_MODULE_NAME: ${UITEST_TARGET}`
+    : "";
+  return `  ${UITEST_TARGET}:
+    type: bundle.ui-testing
+    platform: iOS
+    deploymentTarget: "${appInfo.deploymentTarget}"
+    sources:
+      - path: ${sourcePath}
+    dependencies:
+      - target: ${appInfo.schemeName}
+        embed: false
+    settings:
+      base:${productLines}
+        TEST_TARGET_NAME: ${appInfo.schemeName}
+        PRODUCT_BUNDLE_IDENTIFIER: ${appInfo.bundleId}.uitests
+        GENERATE_INFOPLIST_FILE: YES`;
+}
+
+export function insertUITestTarget(yml: string, targetYml: string): string {
+  if (yml.includes("\nschemes:")) {
+    return yml.replace("\nschemes:", `\n${targetYml}\nschemes:`);
+  }
+  return yml + "\n" + targetYml + "\n";
+}
+
+export function ensureInfoPlistFlag(yml: string): string {
+  if (yml.includes("GENERATE_INFOPLIST_FILE")) return yml;
+  return yml.replace(
+    /(PRODUCT_BUNDLE_IDENTIFIER:[^\n]+\n)/,
+    "$1        GENERATE_INFOPLIST_FILE: YES\n",
+  );
+}
+
 function generateUITestSwift(
   bundleId: string,
   navSteps: string[],
@@ -322,40 +361,13 @@ async function runXCUITest(
 
   if (appInfo.hasXcodegen) {
     originalProjectYml = readFileSync(projectYmlPath, "utf-8");
+    let modifiedYml = ensureInfoPlistFlag(originalProjectYml);
+    modifiedYml = insertUITestTarget(modifiedYml, generateUITestTargetYml(appInfo, `${UITEST_DIR}/Sources`));
+    writeFileSync(projectYmlPath, modifiedYml);
 
-    // Ensure main target has GENERATE_INFOPLIST_FILE and append UI test target
-    let modifiedYml = originalProjectYml;
-    if (!modifiedYml.includes("GENERATE_INFOPLIST_FILE")) {
-      // Add after the first PRODUCT_BUNDLE_IDENTIFIER line
-      modifiedYml = modifiedYml.replace(
-        /(PRODUCT_BUNDLE_IDENTIFIER:[^\n]+\n)/,
-        "$1        GENERATE_INFOPLIST_FILE: YES\n",
-      );
-    }
-
-    const uitestConfig = `
-  ${UITEST_TARGET}:
-    type: bundle.ui-testing
-    platform: iOS
-    deploymentTarget: "${appInfo.deploymentTarget}"
-    sources:
-      - path: ${UITEST_DIR}/Sources
-    dependencies:
-      - target: ${appInfo.schemeName}
-        embed: false
-    settings:
-      base:
-        TEST_TARGET_NAME: ${appInfo.schemeName}
-        PRODUCT_BUNDLE_IDENTIFIER: ${appInfo.bundleId}.uitests
-        GENERATE_INFOPLIST_FILE: YES
-`;
-    writeFileSync(projectYmlPath, modifiedYml + uitestConfig);
-
-    // Regenerate Xcode project
     try {
       await exec(`xcodegen generate`, { cwd: iosDir, timeout: 30_000 });
     } catch (err: any) {
-      // Restore original project.yml
       writeFileSync(projectYmlPath, originalProjectYml);
       throw new Error(`xcodegen failed: ${((err.stderr ?? "") + (err.stdout ?? "")).slice(-300)}`);
     }
@@ -539,3 +551,203 @@ export async function takeIOSScreenshot(
     try { unlinkSync(tmpPath); } catch { /* ignore */ }
   }
 }
+
+// ── batch types ──────────────────────────────────────────────────────
+
+export interface IOSBatchCapture {
+  screen: string;
+  nav?: string[];
+  wait_for?: number;
+}
+
+export interface IOSScreenshotBatchOptions {
+  captures: IOSBatchCapture[];
+  device?: string;
+  theme?: "light" | "dark";
+  output_dir?: string;
+  project_dir?: string;
+  scheme?: string;
+  bundle_id?: string;
+}
+
+// ── batch screenshot ─────────────────────────────────────────────────
+
+export async function takeIOSScreenshotBatch(
+  projectCwd: string,
+  options: IOSScreenshotBatchOptions,
+): Promise<ScreenshotResult> {
+  const { captures, device, theme, output_dir, project_dir, scheme, bundle_id } = options;
+
+  if (captures.length === 0) {
+    return { content: [{ type: "text", text: "No iOS captures specified." }], isError: true };
+  }
+
+  const iosDir = findIOSAppDir(projectCwd, project_dir);
+  const appInfo = extractAppInfo(iosDir, { scheme, bundle_id });
+  const sim = findSimulator(device);
+  await ensureSimulatorBooted(sim.udid);
+
+  if (theme) {
+    await setAppearance(sim.udid, theme);
+  }
+
+  const themeLabel = theme ?? "default";
+  const snapshots: Array<{ screen: string; path: string; data: string }> = [];
+
+  // Separate captures: no-nav (simctl screenshot) vs nav (XCUITest batch)
+  const noNavCaptures = captures.filter((c) => !c.nav || c.nav.length === 0);
+  const navCaptures = captures.filter((c) => c.nav && c.nav.length > 0);
+
+  // Build + install once for all captures
+  const appBundlePath = await buildApp(iosDir, appInfo, sim.udid);
+  await installAndLaunch(sim.udid, appBundlePath, appInfo.bundleId);
+
+  // Pre-create output dir once
+  if (output_dir) mkdirSync(resolve(iosDir, output_dir), { recursive: true });
+
+  // No-nav captures: relaunch, wait, simctl screenshot
+  for (const capture of noNavCaptures) {
+    // Relaunch without reinstalling
+    try { await exec(`xcrun simctl terminate ${sim.udid} ${appInfo.bundleId}`); } catch { /* not running */ }
+    await exec(`xcrun simctl launch ${sim.udid} ${appInfo.bundleId}`, { timeout: 30_000 });
+    await waitForAppReady(sim.udid, appInfo.bundleId, capture.wait_for ?? 3000);
+
+    const filename = `${capture.screen}_${themeLabel}.png`;
+    const tmpPath = join(iosDir, `.openuispec-screenshot-${capture.screen}.png`);
+    await captureScreenshot(sim.udid, tmpPath);
+
+    if (!existsSync(tmpPath)) continue;
+
+    let savedPath = filename;
+    if (output_dir) {
+      savedPath = join(resolve(iosDir, output_dir), filename);
+      copyFileSync(tmpPath, savedPath);
+    }
+
+    snapshots.push({ screen: capture.screen, path: savedPath, data: readFileSync(tmpPath).toString("base64") });
+    try { unlinkSync(tmpPath); } catch { /* ignore */ }
+  }
+
+  // Nav captures: batch into a single XCUITest run
+  if (navCaptures.length > 0) {
+    const uitestDir = join(iosDir, ".screenshot-uitest");
+    const sourcesDir = join(uitestDir, "Sources");
+    mkdirSync(sourcesDir, { recursive: true });
+
+    // Build output paths map
+    const outputPaths: Record<string, string> = {};
+    for (const capture of navCaptures) {
+      const filename = `${capture.screen}_${themeLabel}.png`;
+      if (output_dir) {
+        const outDir = resolve(iosDir, output_dir);
+        mkdirSync(outDir, { recursive: true });
+        outputPaths[capture.screen] = join(outDir, filename);
+      } else {
+        outputPaths[capture.screen] = join(iosDir, `.openuispec-screenshot-${capture.screen}.png`);
+      }
+    }
+
+    // Generate multi-test Swift file
+    const testCases = navCaptures.map((capture, i) => {
+      const taps = (capture.nav ?? []).map((step, j) => {
+        const escaped = step.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        return `
+        let target_${i}_${j} = app.descendants(matching: .any).matching(NSPredicate(format: "label ==[c] %@ OR title ==[c] %@", "${escaped}", "${escaped}")).firstMatch
+        if target_${i}_${j}.waitForExistence(timeout: 5) {
+            target_${i}_${j}.tap()
+            Thread.sleep(forTimeInterval: 0.8)
+        }`;
+      }).join("\n");
+
+      const outPath = outputPaths[capture.screen].replace(/"/g, '\\"');
+      return `
+    func test_${String(i + 1).padStart(2, "0")}_${capture.screen}() {
+        let app = XCUIApplication()
+        app.launchArguments = ["-AppleLanguages", "(en)"]
+        app.launch()
+        Thread.sleep(forTimeInterval: ${((capture.wait_for ?? 3000) / 1000).toFixed(1)})
+${taps}
+        Thread.sleep(forTimeInterval: 0.5)
+        let screenshot = XCUIScreen.main.screenshot()
+        try! screenshot.pngRepresentation.write(to: URL(fileURLWithPath: "${outPath}"))
+    }`;
+    }).join("\n");
+
+    writeFileSync(join(sourcesDir, "ScreenshotUITest.swift"),
+      `import XCTest\n\nfinal class ScreenshotUITest: XCTestCase {\n${testCases}\n}\n`);
+
+    // Set up xcodegen
+    const UITEST_TARGET = "ScreenshotUITests";
+    const hasXcodegen = existsSync(join(iosDir, "project.yml"));
+    const projectYmlPath = join(iosDir, "project.yml");
+    let originalProjectYml: string | null = null;
+    const buildDir = join(iosDir, ".build", "screenshot");
+
+    if (hasXcodegen) {
+      originalProjectYml = readFileSync(projectYmlPath, "utf-8");
+      let modifiedYml = ensureInfoPlistFlag(originalProjectYml);
+      modifiedYml = insertUITestTarget(modifiedYml, generateUITestTargetYml(appInfo, ".screenshot-uitest/Sources", true));
+      writeFileSync(projectYmlPath, modifiedYml);
+      await exec(`xcodegen generate`, { cwd: iosDir, timeout: 30_000 });
+    } else {
+      writeFileSync(join(uitestDir, "project.yml"), `name: ${UITEST_TARGET}
+targets:
+  ${UITEST_TARGET}:
+    type: bundle.ui-testing
+    platform: iOS
+    deploymentTarget: "${appInfo.deploymentTarget}"
+    sources:
+      - path: Sources
+    settings:
+      base:
+        TEST_TARGET_NAME: ${appInfo.schemeName}
+        PRODUCT_BUNDLE_IDENTIFIER: ${appInfo.bundleId}.uitests
+        GENERATE_INFOPLIST_FILE: YES
+`);
+      await exec(`xcodegen generate`, { cwd: uitestDir, timeout: 30_000 });
+    }
+
+    const testProjectFlag = hasXcodegen
+      ? (appInfo.xcodeproj ? `-project "${join(iosDir, appInfo.xcodeproj)}"` : "")
+      : `-project "${join(uitestDir, `${UITEST_TARGET}.xcodeproj`)}"`;
+    const testCwd = hasXcodegen ? iosDir : uitestDir;
+
+    try {
+      await exec(
+        `xcodebuild test ${testProjectFlag} -scheme "${UITEST_TARGET}" -destination "id=${sim.udid}" -derivedDataPath "${buildDir}" -only-testing:${UITEST_TARGET}/ScreenshotUITest 2>&1`,
+        { cwd: testCwd, timeout: 300_000 },
+      );
+    } catch {
+      // Tests may "fail" but still produce screenshots
+    } finally {
+      if (originalProjectYml) {
+        writeFileSync(projectYmlPath, originalProjectYml);
+        try { await exec(`xcodegen generate`, { cwd: iosDir, timeout: 30_000 }); } catch { /* best effort */ }
+      }
+    }
+
+    // Collect results
+    for (const capture of navCaptures) {
+      const outPath = outputPaths[capture.screen];
+      if (existsSync(outPath)) {
+        snapshots.push({
+          screen: capture.screen,
+          path: output_dir ? outPath : `${capture.screen}_${themeLabel}.png`,
+          data: readFileSync(outPath).toString("base64"),
+        });
+        if (!output_dir) { try { unlinkSync(outPath); } catch { /* ignore */ } }
+      }
+    }
+  }
+
+  if (snapshots.length === 0) {
+    return { content: [{ type: "text", text: "No screenshots were captured. Check Xcode and Simulator output." }], isError: true };
+  }
+
+  const content: ScreenshotResult["content"] = [];
+  for (const s of snapshots) {
+    content.push({ type: "image" as const, data: s.data, mimeType: "image/png" });
+    content.push({ type: "text" as const, text: JSON.stringify({ screen: s.screen, path: s.path, simulator: sim.name, theme: themeLabel, bundleId: appInfo.bundleId }, null, 2) });
+  }
+  return { content };
+}