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,76 @@ export default function addAppAutomationTools(server: McpServer) {
       }
     },
   );
+
+  server.tool(
+    "runAppTestsOnBrowserStack",
+    "Run AppAutomate tests on BrowserStack by uploading app and test suite. If running from Android Studio or Xcode, the tool will help export app and test files automatically. For other environments, you'll need to provide the paths to your pre-built app and test files.",
+    {
+      appPath: z
+        .string()
+        .describe(
+          "Path to your application file:\n" +
+          "If in development IDE directory:\n" +
+          "• For Android: 'gradle assembleDebug'\n" +
+          "• For iOS:\n" +
+          "  xcodebuild clean -scheme YOUR_SCHEME && \\\n" +
+          "  xcodebuild archive -scheme YOUR_SCHEME -configuration Release -archivePath build/app.xcarchive && \\\n" +
+          "  xcodebuild -exportArchive -archivePath build/app.xcarchive -exportPath build/ipa -exportOptionsPlist exportOptions.plist\n\n" +
+          "If in other directory, provide existing app path"
+        ),
+      testSuitePath: z
+        .string()
+        .describe(
+          "Path to your test suite file:\n" +
+          "If in development IDE directory:\n" +
+          "• For Android: 'gradle assembleAndroidTest'\n" +
+          "• For iOS:\n" +
+          "  xcodebuild test-without-building -scheme YOUR_SCHEME -destination 'generic/platform=iOS' && \\\n" +
+          "  cd ~/Library/Developer/Xcode/DerivedData/*/Build/Products/Debug-iphonesimulator/ && \\\n" +
+          "  zip -r Tests.zip *.xctestrun *-Runner.app\n\n" +
+          "If in other directory, provide existing test file path"
+        ),
+      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("BStack-AppAutomate-Suite")
+        .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,
+        };
+      }
+    },
+  );
 }