feat: add support for running AppAutomate tests on BrowserStack

src/tools/appautomate-utils/appautomate.ts

@@ -4,6 +4,11 @@ import config from "../../config.js";
 import FormData from "form-data";
 import { customFuzzySearch } from "../../lib/fuzzy.js";
 
+const auth = {
+  username: config.browserstackUsername,
+  password: config.browserstackAccessKey,
+};
+
 interface Device {
   device: string;
   display_name: string;
@@ -138,13 +143,8 @@ export async function uploadApp(appPath: string): Promise<string> {
     "https://api-cloud.browserstack.com/app-automate/upload",
     formData,
     {
-      headers: {
-        ...formData.getHeaders(),
-      },
-      auth: {
-        username: config.browserstackUsername,
-        password: config.browserstackAccessKey,
-      },
+      headers: formData.getHeaders(),
+      auth,
     },
   );
 
@@ -154,3 +154,126 @@ export async function uploadApp(appPath: string): Promise<string> {
     throw new Error(`Failed to upload app: ${response.data}`);
   }
 }
+
+// Helper to upload a file to a given BrowserStack endpoint and return a specific property from the response.
+async function uploadFileToBrowserStack(
+  filePath: string,
+  endpoint: string,
+  responseKey: string,
+): Promise<string> {
+  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(endpoint, formData, {
+    headers: formData.getHeaders(),
+    auth,
+  });
+
+  if (response.data[responseKey]) {
+    return response.data[responseKey];
+  }
+
+  throw new Error(`Failed to upload file: ${JSON.stringify(response.data)}`);
+}
+
+//Uploads an Android app (.apk or .aab) to BrowserStack Espresso endpoint and returns the app_url
+export async function uploadEspressoApp(appPath: string): Promise<string> {
+  return uploadFileToBrowserStack(
+    appPath,
+    "https://api-cloud.browserstack.com/app-automate/espresso/v2/app",
+    "app_url",
+  );
+}
+
+//Uploads an Espresso test suite (.apk) to BrowserStack and returns the test_suite_url
+export async function uploadEspressoTestSuite(
+  testSuitePath: string,
+): Promise<string> {
+  return uploadFileToBrowserStack(
+    testSuitePath,
+    "https://api-cloud.browserstack.com/app-automate/espresso/v2/test-suite",
+    "test_suite_url",
+  );
+}
+
+//Uploads an iOS app (.ipa) to BrowserStack XCUITest endpoint and returns the app_url
+export async function uploadXcuiApp(appPath: string): Promise<string> {
+  return uploadFileToBrowserStack(
+    appPath,
+    "https://api-cloud.browserstack.com/app-automate/xcuitest/v2/app",
+    "app_url",
+  );
+}
+
+//Uploads an XCUITest test suite (.zip) to BrowserStack and returns the test_suite_url
+export async function uploadXcuiTestSuite(
+  testSuitePath: string,
+): Promise<string> {
+  return uploadFileToBrowserStack(
+    testSuitePath,
+    "https://api-cloud.browserstack.com/app-automate/xcuitest/v2/test-suite",
+    "test_suite_url",
+  );
+}
+
+// Triggers an Espresso test run on BrowserStack and returns the build_id
+export async function triggerEspressoBuild(
+  app_url: string,
+  test_suite_url: string,
+  devices: string[],
+  project: string,
+): Promise<string> {
+  const response = await axios.post(
+    "https://api-cloud.browserstack.com/app-automate/espresso/v2/build",
+    {
+      app: app_url,
+      testSuite: test_suite_url,
+      devices,
+      project,
+    },
+    {
+      auth,
+    },
+  );
+
+  if (response.data.build_id) {
+    return response.data.build_id;
+  }
+
+  throw new Error(
+    `Failed to trigger Espresso build: ${JSON.stringify(response.data)}`,
+  );
+}
+
+// Triggers an XCUITest run on BrowserStack and returns the build_id
+export async function triggerXcuiBuild(
+  app_url: string,
+  test_suite_url: string,
+  devices: string[],
+  project: string,
+): Promise<string> {
+  const response = await axios.post(
+    "https://api-cloud.browserstack.com/app-automate/xcuitest/v2/build",
+    {
+      app: app_url,
+      testSuite: test_suite_url,
+      devices,
+      project,
+    },
+    {
+      auth,
+    },
+  );
+
+  if (response.data.build_id) {
+    return response.data.build_id;
+  }
+
+  throw new Error(
+    `Failed to trigger XCUITest build: ${JSON.stringify(response.data)}`,
+  );
+}

src/tools/appautomate-utils/types.ts

@@ -0,0 +1,5 @@
+export enum AppTestPlatform {
+  ESPRESSO = "espresso",
+  APPIUM = "appium",
+  XCUITEST = "xcuitest",
+}

src/tools/appautomate.ts

@@ -6,6 +6,7 @@ import config from "../config.js";
 import { trackMCP } from "../lib/instrumentation.js";
 import { maybeCompressBase64 } from "../lib/utils.js";
 import { remote } from "webdriverio";
+import { AppTestPlatform } from "./appautomate-utils/types.js";
 
 import {
   getDevicesAndBrowsers,
@@ -18,6 +19,12 @@ import {
   resolveVersion,
   validateArgs,
   uploadApp,
+  uploadEspressoApp,
+  uploadEspressoTestSuite,
+  triggerEspressoBuild,
+  uploadXcuiApp,
+  uploadXcuiTestSuite,
+  triggerXcuiBuild,
 } from "./appautomate-utils/appautomate.js";
 
 // Types
@@ -136,9 +143,72 @@ async function takeAppScreenshot(args: {
   }
 }
 
-/**
- * Registers the `takeAppScreenshot` tool with the MCP server.
- */
+//Runs AppAutomate tests on BrowserStack by uploading app and test suite, then triggering a test run.
+async function runAppTestsOnBrowserStack(args: {
+  appPath: string;
+  testSuitePath: string;
+  devices: string[];
+  project: string;
+  detectedAutomationFramework: string;
+}): Promise<CallToolResult> {
+  switch (args.detectedAutomationFramework) {
+    case AppTestPlatform.ESPRESSO: {
+      try {
+        const app_url = await uploadEspressoApp(args.appPath);
+        const test_suite_url = await uploadEspressoTestSuite(
+          args.testSuitePath,
+        );
+        const build_id = await triggerEspressoBuild(
+          app_url,
+          test_suite_url,
+          args.devices,
+          args.project,
+        );
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `✅ Espresso run started successfully!\n\n🔧 Build ID: ${build_id}\n🔗 View your build: https://app-automate.browserstack.com/builds/${build_id}`,
+            },
+          ],
+        };
+      } catch (err) {
+        logger.error("Error running App Automate test", err);
+        throw err;
+      }
+    }
+    case AppTestPlatform.XCUITEST: {
+      try {
+        const app_url = await uploadXcuiApp(args.appPath);
+        const test_suite_url = await uploadXcuiTestSuite(args.testSuitePath);
+        const build_id = await triggerXcuiBuild(
+          app_url,
+          test_suite_url,
+          args.devices,
+          args.project,
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: `✅ XCUITest run started successfully!\n\n🔧 Build ID: ${build_id}\n🔗 View your build: https://app-automate.browserstack.com/builds/${build_id}`,
+            },
+          ],
+        };
+      } catch (err) {
+        logger.error("Error running XCUITest App Automate test", err);
+        throw err;
+      }
+    }
+    default:
+      throw new Error(
+        `Unsupported automation framework: ${args.detectedAutomationFramework}. If you need support for this framework, please open an issue at Github`,
+      );
+  }
+}
+
+// Registers automation tools with the MCP server.
 export default function addAppAutomationTools(server: McpServer) {
   server.tool(
     "takeAppScreenshot",
@@ -182,4 +252,62 @@ export default function addAppAutomationTools(server: McpServer) {
       }
     },
   );
+
+  server.tool(
+    "runAppTestsOnBrowserStack",
+    "Run AppAutomate tests on BrowserStack by uploading app and test suite, then triggering a test run. Supports both Espresso (Android) and XCUITest (iOS).",
+    {
+      appPath: z
+        .string()
+        .describe(
+          "Path to the .apk/.aab (Espresso) or .ipa (XCUITest) file for your app. Export on your own in local IDEs.",
+        ),
+      testSuitePath: z
+        .string()
+        .describe(
+          "Path to the Espresso test suite .apk or XCUITest .zip file. Export on your own in local IDEs.",
+        ),
+      devices: z
+        .array(z.string())
+        .describe(
+          "List of devices to run the test on, e.g., ['Samsung Galaxy S20-10.0', 'iPhone 12 Pro-16.0'].",
+        ),
+      project: z
+        .string()
+        .optional()
+        .default("Espresso Test")
+        .describe("Project name for organizing test runs on BrowserStack."),
+      detectedAutomationFramework: z
+        .string()
+        .describe(
+          "The automation framework used in the project, such as 'espresso' (Android) or 'xcuitest' (iOS).",
+        ),
+    },
+    async (args) => {
+      try {
+        trackMCP(
+          "runAppTestsOnBrowserStack",
+          server.server.getClientVersion()!,
+        );
+        return await runAppTestsOnBrowserStack(args);
+      } catch (error) {
+        trackMCP(
+          "runAppTestsOnBrowserStack",
+          server.server.getClientVersion()!,
+          error,
+        );
+        const errorMessage =
+          error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error running App Automate test: ${errorMessage}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    },
+  );
 }