Feat: App Screenshot on Real Device (#31)

* Feat: Add App Automate + Appium tool for BrowserStack integration

* Add unit tests for appautomate utilities

* Update src/tools/appautomate-utils/appautomate.ts

Co-authored-by: Pulkit Sharma <[email protected]>

* Remove automationName assignment

* Fix: Ensure cache retrieval only returns valid device data

* Fix : Add image compression utility for base64 screenshots

* Refactor: Initialize WebDriverIO directly to streamline app automation

* Update package version

* Adding sharp to package version

---------

Co-authored-by: Pulkit Sharma <[email protected]>

Author: tech-sushant

package-lock.json

@@ -41,6 +41,8 @@
     "form-data": "^4.0.2",
     "pino": "^9.6.0",
     "pino-pretty": "^13.0.0",
+    "sharp": "^0.34.1",
+    "webdriverio": "^9.13.0",
     "zod": "^3.24.3"
   },
   "devDependencies": {

package.json

@@ -12,6 +12,7 @@ import addBrowserLiveTools from "./tools/live";
 import addAccessibilityTools from "./tools/accessibility";
 import addAutomateTools from "./tools/automate";
 import addTestManagementTools from "./tools/testmanagement";
+import addAppAutomationTools from "./tools/appautomate";
 import { trackMCP } from "./lib/instrumentation";
 
 function registerTools(server: McpServer) {
@@ -22,6 +23,7 @@ function registerTools(server: McpServer) {
   addAccessibilityTools(server);
   addAutomateTools(server);
   addTestManagementTools(server);
+  addAppAutomationTools(server);
 }
 
 // Create an MCP server

src/index.ts

@@ -6,17 +6,26 @@ const CACHE_DIR = path.join(os.homedir(), ".browserstack", "combined_cache");
 const CACHE_FILE = path.join(CACHE_DIR, "data.json");
 const TTL_MS = 24 * 60 * 60 * 1000; // 1 day
 
-const URLS = {
-  live: "https://www.browserstack.com/list-of-browsers-and-platforms/live.json",
-  app_live:
+export enum BrowserStackProducts {
+  LIVE = "live",
+  APP_LIVE = "app_live",
+  APP_AUTOMATE = "app_automate",
+}
+
+const URLS: Record<BrowserStackProducts, string> = {
+  [BrowserStackProducts.LIVE]:
+    "https://www.browserstack.com/list-of-browsers-and-platforms/live.json",
+  [BrowserStackProducts.APP_LIVE]:
     "https://www.browserstack.com/list-of-browsers-and-platforms/app_live.json",
+  [BrowserStackProducts.APP_AUTOMATE]:
+    "https://www.browserstack.com/list-of-browsers-and-platforms/app_automate.json",
 };
 
 /**
- * Fetches and caches both BrowserStack datasets (live + app_live) with a shared TTL.
+ * Fetches and caches BrowserStack datasets (live + app_live + app_automate) with a shared TTL.
  */
 export async function getDevicesAndBrowsers(
-  type: "live" | "app_live",
+  type: BrowserStackProducts,
 ): Promise<any> {
   if (!fs.existsSync(CACHE_DIR)) {
     fs.mkdirSync(CACHE_DIR, { recursive: true });
@@ -29,31 +38,29 @@ export async function getDevicesAndBrowsers(
     if (Date.now() - stats.mtimeMs < TTL_MS) {
       try {
         cache = JSON.parse(fs.readFileSync(CACHE_FILE, "utf8"));
-        return cache[type];
+        if (cache[type]) {
+          return cache[type];
+        }
       } catch (error) {
         console.error("Error parsing cache file:", error);
         // Continue with fetching fresh data
       }
     }
   }
 
-  const [liveRes, appLiveRes] = await Promise.all([
-    fetch(URLS.live),
-    fetch(URLS.app_live),
-  ]);
+  const liveRes = await fetch(URLS[type]);
 
-  if (!liveRes.ok || !appLiveRes.ok) {
+  if (!liveRes.ok) {
     throw new Error(
-      `Failed to fetch configuration from BrowserStack : live=${liveRes.statusText}, app_live=${appLiveRes.statusText}`,
+      `Failed to fetch configuration from BrowserStack : ${type}=${liveRes.statusText}`,
     );
   }
 
-  const [liveData, appLiveData] = await Promise.all([
-    liveRes.json(),
-    appLiveRes.json(),
-  ]);
+  const data = await liveRes.json();
 
-  cache = { live: liveData, app_live: appLiveData };
+  cache = {
+    [type]: data,
+  };
   fs.writeFileSync(CACHE_FILE, JSON.stringify(cache), "utf8");
 
   return cache[type];

src/lib/device-cache.ts

@@ -1,3 +1,5 @@
+import sharp from "sharp";
+
 export function sanitizeUrlParam(param: string): string {
   // Remove any characters that could be used for command injection
   return param.replace(/[;&|`$(){}[\]<>]/g, "");
@@ -24,3 +26,24 @@ export interface HarEntry {
   serverIPAddress?: string;
   time?: number;
 }
+
+/**
+ * Compresses a base64 image intelligently to keep it under 1 MB if needed.
+ */
+export async function maybeCompressBase64(base64: string): Promise<string> {
+  const buffer = Buffer.from(base64, "base64");
+
+  if (buffer.length <= 1048576) {
+    return base64;
+  }
+
+  const sizeRatio = 1048576 / buffer.length;
+  const estimatedQuality = Math.floor(sizeRatio * 100);
+  const quality = Math.min(95, Math.max(30, estimatedQuality)); 
+
+  const compressedBuffer = await sharp(buffer)
+    .png({ quality })
+    .toBuffer();
+
+  return compressedBuffer.toString("base64");
+}

src/lib/utils.ts

@@ -0,0 +1,156 @@
+import fs from "fs";
+import axios from "axios";
+import config from "../../config";
+import FormData from "form-data";
+import { customFuzzySearch } from "../../lib/fuzzy";
+
+interface Device {
+  device: string;
+  display_name: string;
+  os_version: string;
+  real_mobile: boolean;
+}
+
+interface UploadResponse {
+  app_url: string;
+  custom_id?: string;
+  shareable_id?: string;
+}
+
+/**
+ * Finds devices that exactly match the provided display name.
+ * Uses fuzzy search first, and then filters for exact case-insensitive match.
+ */
+export function findMatchingDevice(
+  devices: Device[],
+  deviceName: string,
+): Device[] {
+  const matches = customFuzzySearch(devices, ["display_name"], deviceName, 5);
+
+  if (matches.length === 0) {
+    const availableDevices = [
+      ...new Set(devices.map((d) => d.display_name)),
+    ].join(", ");
+    throw new Error(
+      `No devices found matching "${deviceName}". Available devices: ${availableDevices}`,
+    );
+  }
+
+  const exactMatches = matches.filter(
+    (m) => m.display_name.toLowerCase() === deviceName.toLowerCase(),
+  );
+
+  if (exactMatches.length === 0) {
+    const suggestions = [...new Set(matches.map((d) => d.display_name))].join(
+      ", ",
+    );
+    throw new Error(
+      `Alternative devices found: ${suggestions}. Please select one of these exact device names.`,
+    );
+  }
+  return exactMatches;
+}
+
+/**
+ * Extracts all unique OS versions from a device list and sorts them.
+ */
+export function getDeviceVersions(devices: Device[]): string[] {
+  return [...new Set(devices.map((d) => d.os_version))].sort();
+}
+
+/**
+ * Resolves the requested platform version against available versions.
+ * Supports 'latest' and 'oldest' as dynamic selectors.
+ */
+export function resolveVersion(
+  versions: string[],
+  requestedVersion: string,
+): string {
+  if (requestedVersion === "latest") {
+    return versions[versions.length - 1];
+  }
+
+  if (requestedVersion === "oldest") {
+    return versions[0];
+  }
+
+  const match = versions.find((v) => v === requestedVersion);
+  if (!match) {
+    throw new Error(
+      `Version "${requestedVersion}" not found. Available versions: ${versions.join(", ")}`,
+    );
+  }
+  return match;
+}
+
+/**
+ * Validates the input arguments for taking app screenshots.
+ * Checks for presence and correctness of platform, device, and file types.
+ */
+export function validateArgs(args: {
+  desiredPlatform: string;
+  desiredPlatformVersion: string;
+  appPath: string;
+  desiredPhone: string;
+}): void {
+  const { desiredPlatform, desiredPlatformVersion, appPath, desiredPhone } =
+    args;
+
+  if (!desiredPlatform || !desiredPhone) {
+    throw new Error(
+      "Missing required arguments: desiredPlatform and desiredPhone are required",
+    );
+  }
+
+  if (!desiredPlatformVersion) {
+    throw new Error(
+      "Missing required arguments: desiredPlatformVersion is required",
+    );
+  }
+
+  if (!appPath) {
+    throw new Error("You must provide an appPath.");
+  }
+
+  if (desiredPlatform === "android" && !appPath.endsWith(".apk")) {
+    throw new Error("You must provide a valid Android app path (.apk).");
+  }
+
+  if (desiredPlatform === "ios" && !appPath.endsWith(".ipa")) {
+    throw new Error("You must provide a valid iOS app path (.ipa).");
+  }
+}
+
+/**
+ * Uploads an application file to AppAutomate and returns the app URL
+ */
+export async function uploadApp(appPath: string): Promise<string> {
+  const filePath = appPath;
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File not found at path: ${filePath}`);
+  }
+
+  const formData = new FormData();
+  formData.append("file", fs.createReadStream(filePath));
+
+  const response = await axios.post<UploadResponse>(
+    "https://api-cloud.browserstack.com/app-automate/upload",
+    formData,
+    {
+      headers: {
+        ...formData.getHeaders(),
+      },
+      auth: {
+        username: config.browserstackUsername,
+        password: config.browserstackAccessKey,
+      },
+    },
+  );
+
+  if (response.data.app_url) {
+    return response.data.app_url;
+  } else {
+    throw new Error(`Failed to upload app: ${response.data}`);
+  }
+}