refactor: update device validation and configuration generation for BrowserStack

Author: tech-sushant

src/lib/device-cache.ts

@@ -13,8 +13,8 @@ export enum BrowserStackProducts {
   LIVE = "live",
   APP_LIVE = "app_live",
   APP_AUTOMATE = "app_automate",
-  SELENIUM_APP_AUTOMATE = "selenium_app_automate",
-  PLAYWRIGHT_APP_AUTOMATE = "playwright_app_automate",
+  SELENIUM_AUTOMATE = "selenium_automate",
+  PLAYWRIGHT_AUTOMATE = "playwright_automate",
 }
 
 const URLS: Record<BrowserStackProducts, string> = {
@@ -24,9 +24,9 @@ const URLS: Record<BrowserStackProducts, string> = {
     "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",
-  [BrowserStackProducts.SELENIUM_APP_AUTOMATE]:
+  [BrowserStackProducts.SELENIUM_AUTOMATE]:
     "https://www.browserstack.com/list-of-browsers-and-platforms/selenium_app_automate.json",
-  [BrowserStackProducts.PLAYWRIGHT_APP_AUTOMATE]:
+  [BrowserStackProducts.PLAYWRIGHT_AUTOMATE]:
     "https://www.browserstack.com/list-of-browsers-and-platforms/playwright.json",
 };
 

src/tools/appautomate-utils/appium-sdk/config-generator.ts

@@ -1,4 +1,3 @@
-// Configuration utilities for BrowserStack App SDK
 import {
   APP_DEVICE_CONFIGS,
   AppSDKSupportedTestingFrameworkEnum,
@@ -8,39 +7,33 @@ import {
 import { ValidatedEnvironment } from "../../sdk-utils/common/device-validator.js";
 
 export function generateAppBrowserStackYMLInstructions(
-  platforms: string[],
+  config: {
+    validatedEnvironments?: ValidatedEnvironment[];
+    platforms?: string[];
+    testingFramework?: string;
+    projectName?: string;
+  },
   username: string,
   accessKey: string,
   appPath: string = DEFAULT_APP_PATH,
-  testingFramework: string,
 ): string {
   if (
-    testingFramework === AppSDKSupportedTestingFrameworkEnum.nightwatch ||
-    testingFramework === AppSDKSupportedTestingFrameworkEnum.webdriverio ||
-    testingFramework === AppSDKSupportedTestingFrameworkEnum.cucumberRuby
+    config.testingFramework ===
+      AppSDKSupportedTestingFrameworkEnum.nightwatch ||
+    config.testingFramework ===
+      AppSDKSupportedTestingFrameworkEnum.webdriverio ||
+    config.testingFramework === AppSDKSupportedTestingFrameworkEnum.cucumberRuby
   ) {
     return "";
   }
 
-  // Generate platform and device configurations
-  const platformConfigs = platforms
-    .map((platform) => {
-      const devices =
-        APP_DEVICE_CONFIGS[platform as keyof typeof APP_DEVICE_CONFIGS];
-      if (!devices) return "";
+  const platformConfigs = generatePlatformConfigs(config);
 
-      return devices
-        .map(
-          (device) => `  - platformName: ${platform}
-    deviceName: ${device.deviceName}
-    platformVersion: "${device.platformVersion}"`,
-        )
-        .join("\n");
-    })
-    .filter(Boolean)
-    .join("\n");
+  const projectName = config.projectName || "BrowserStack Sample";
+  const buildName = config.projectName
+    ? `${config.projectName}-AppAutomate-Build`
+    : "bstack-demo";
 
-  // Construct YAML content
   const configContent = `\`\`\`yaml
 userName: ${username}
 accessKey: ${accessKey}
@@ -49,8 +42,8 @@ platforms:
 ${platformConfigs}
 parallelsPerPlatform: 1
 browserstackLocal: true
-buildName: bstack-demo
-projectName: BrowserStack Sample
+buildName: ${buildName}
+projectName: ${projectName}
 debug: true
 networkLogs: true
 percy: false
@@ -64,64 +57,46 @@ accessibility: false
 - Set \`browserstackLocal: true\` if you need to test with local/staging servers
 - Adjust \`parallelsPerPlatform\` based on your subscription limits`;
 
-  // Return formatted step for instructions
-  return createStep(
-    "Update browserstack.yml file with App Automate configuration:",
-    `Create or update the browserstack.yml file in your project root with the following content:
+  const stepTitle =
+    "Update browserstack.yml file with App Automate configuration:";
 
-${configContent}`,
-  );
+  const stepDescription = `Create or update the browserstack.yml file in your project root with the following content:
+  ${configContent}`;
+
+  return createStep(stepTitle, stepDescription);
 }
 
-/**
- * Generate App Automate browserstack.yml from validated device configurations
- */
-export function generateAppAutomateYML(
-  validatedEnvironments: ValidatedEnvironment[],
-  username: string,
-  accessKey: string,
-  appPath: string = DEFAULT_APP_PATH,
-  projectName: string,
-): string {
-  // Generate platform configurations from validated environments
-  const platformConfigs = validatedEnvironments
-    .filter((env) => env.platform === "android" || env.platform === "ios")
-    .map((env) => {
-      return `  - platformName: ${env.platform}
+function generatePlatformConfigs(config: {
+  validatedEnvironments?: ValidatedEnvironment[];
+  platforms?: string[];
+}): string {
+  if (config.validatedEnvironments && config.validatedEnvironments.length > 0) {
+    return config.validatedEnvironments
+      .filter((env) => env.platform === "android" || env.platform === "ios")
+      .map((env) => {
+        return `  - platformName: ${env.platform}
     deviceName: "${env.deviceName}"
     platformVersion: "${env.osVersion}"`;
-    })
-    .join("\n");
+      })
+      .join("\n");
+  } else if (config.platforms && config.platforms.length > 0) {
+    return config.platforms
+      .map((platform) => {
+        const devices =
+          APP_DEVICE_CONFIGS[platform as keyof typeof APP_DEVICE_CONFIGS];
+        if (!devices) return "";
 
-  // Construct YAML content with validated data
-  const configContent = `\`\`\`yaml
-userName: ${username}
-accessKey: ${accessKey}
-app: ${appPath}
-platforms:
-${platformConfigs}
-parallelsPerPlatform: 1
-browserstackLocal: true
-buildName: ${projectName}-AppAutomate-Build
-projectName: ${projectName}
-debug: true
-networkLogs: true
-percy: false
-percyCaptureMode: auto
-accessibility: false
-\`\`\`
-
-**Important notes:**
-- Replace \`app: ${appPath}\` with the path to your actual app file (e.g., \`./SampleApp.apk\` for Android or \`./SampleApp.ipa\` for iOS)
-- You can upload your app using BrowserStack's App Upload API or manually through the dashboard
-- Set \`browserstackLocal: true\` if you need to test with local/staging servers
-- Adjust \`parallelsPerPlatform\` based on your subscription limits`;
-
-  // Return formatted step for instructions
-  return createStep(
-    "Update browserstack.yml file with validated App Automate configuration:",
-    `Create or update the browserstack.yml file in your project root with your validated device configurations:
+        return devices
+          .map(
+            (device) => `  - platformName: ${platform}
+    deviceName: ${device.deviceName}
+    platformVersion: "${device.platformVersion}"`,
+          )
+          .join("\n");
+      })
+      .filter(Boolean)
+      .join("\n");
+  }
 
-${configContent}`,
-  );
+  return "";
 }

src/tools/appautomate-utils/appium-sdk/constants.ts

@@ -49,6 +49,69 @@ export const SETUP_APP_AUTOMATE_SCHEMA = {
       "The programming language used in the project. Supports Java and C#. Example: 'java', 'csharp'",
     ),
 
+  devices: z
+    .array(
+      z.union([
+        // Android: [android, deviceName, osVersion]
+        z.tuple([
+          z
+            .literal(AppSDKSupportedPlatformEnum.android)
+            .describe("Platform identifier: 'android'"),
+          z
+            .string()
+            .describe(
+              "Device name, e.g. 'Samsung Galaxy S24', 'Google Pixel 8'",
+            ),
+          z.string().describe("Android version, e.g. '14', '16', 'latest'"),
+        ]),
+        // iOS: [ios, deviceName, osVersion]
+        z.tuple([
+          z
+            .literal(AppSDKSupportedPlatformEnum.ios)
+            .describe("Platform identifier: 'ios'"),
+          z.string().describe("Device name, e.g. 'iPhone 15', 'iPhone 14 Pro'"),
+          z.string().describe("iOS version, e.g. '17', '16', 'latest'"),
+        ]),
+      ]),
+    )
+    .max(3)
+    .default([[AppSDKSupportedPlatformEnum.android, 'Samsung Galaxy S24', 'latest']])
+    .describe(
+      "Preferred input: 1-3 tuples describing target mobile devices. Example: [['android', 'Samsung Galaxy S24', '14'], ['ios', 'iPhone 15', '17']]",
+    ),
+
+  appPath: z
+    .string()
+    .describe(
+      "Path to the mobile app file (.apk for Android, .ipa for iOS). Can be a local file path or a BrowserStack app URL (bs://)",
+    ),
+  project: z
+    .string()
+    .optional()
+    .default("BStack-AppAutomate-Suite")
+    .describe("Project name for organizing test runs on BrowserStack."),
+};
+
+// Legacy schema for backward compatibility
+export const SETUP_APP_AUTOMATE_SCHEMA_LEGACY = {
+  detectedFramework: z
+    .nativeEnum(AppSDKSupportedFrameworkEnum)
+    .describe(
+      "The mobile automation framework configured in the project. Example: 'appium'",
+    ),
+
+  detectedTestingFramework: z
+    .nativeEnum(AppSDKSupportedTestingFrameworkEnum)
+    .describe(
+      "The testing framework used in the project. Be precise with framework selection Example: 'testng', 'behave', 'pytest', 'robot'",
+    ),
+
+  detectedLanguage: z
+    .nativeEnum(AppSDKSupportedLanguageEnum)
+    .describe(
+      "The programming language used in the project. Supports Java and C#. Example: 'java', 'csharp'",
+    ),
+
   desiredPlatforms: z
     .array(z.nativeEnum(AppSDKSupportedPlatformEnum))
     .describe(

src/tools/appautomate-utils/appium-sdk/handler.ts

@@ -2,8 +2,6 @@ import { z } from "zod";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { BrowserStackConfig } from "../../../lib/types.js";
 import { getBrowserStackAuth } from "../../../lib/get-auth.js";
-import { generateAppAutomateYML } from "./config-generator.js";
-
 import {
   getAppUploadInstruction,
   validateSupportforAppAutomate,
@@ -15,6 +13,8 @@ import {
   generateAppBrowserStackYMLInstructions,
 } from "./index.js";
 
+import { validateDevices } from "../../sdk-utils/common/device-validator.js";
+
 import {
   AppSDKSupportedLanguage,
   AppSDKSupportedTestingFramework,
@@ -38,16 +38,23 @@ export async function setupAppAutomateHandler(
   const testingFramework =
     input.detectedTestingFramework as AppSDKSupportedTestingFramework;
   const language = input.detectedLanguage as AppSDKSupportedLanguage;
-  const platforms = (input.desiredPlatforms as string[]) ?? ["android"];
+  const inputDevices = (input.devices as Array<Array<string>>) ?? [];
   const appPath = input.appPath as string;
   const framework = input.detectedFramework as SupportedFramework;
 
   //Validating if supported framework or not
   validateSupportforAppAutomate(framework, language, testingFramework);
 
-  // For app automate, we don't have individual device validation like in automate
-  // The platforms array already contains the desired platforms
-  const validatedEnvironments: any[] = [];
+  // Use default mobile devices when array is empty
+  const devices = inputDevices.length === 0 
+    ? [['android', 'Samsung Galaxy S24', 'latest']] // Default mobile device for App Automate
+    : inputDevices;
+
+  // Validate devices against real BrowserStack device data
+  const validatedEnvironments = await validateDevices(devices, framework);
+
+  // Extract platforms for backward compatibility (if needed)
+  const platforms = validatedEnvironments.map((env) => env.platform);
 
   // Step 1: Generate SDK setup command
   const sdkCommand = getAppSDKPrefixCommand(
@@ -63,26 +70,17 @@ export async function setupAppAutomateHandler(
   }
 
   // Step 2: Generate browserstack.yml configuration
-  let configInstructions;
-  if (validatedEnvironments.length > 0) {
-    // Use validated environments for YML generation
-    configInstructions = generateAppAutomateYML(
+  const configInstructions = generateAppBrowserStackYMLInstructions(
+    {
       validatedEnvironments,
-      username,
-      accessKey,
-      appPath,
-      input.project as string,
-    );
-  } else {
-    // Fallback to original method
-    configInstructions = generateAppBrowserStackYMLInstructions(
       platforms,
-      username,
-      accessKey,
-      appPath,
       testingFramework,
-    );
-  }
+      projectName: input.project as string,
+    },
+    username,
+    accessKey,
+    appPath,
+  );
 
   if (configInstructions) {
     instructions.push({ content: configInstructions, type: "config" });

src/tools/appautomate.ts

@@ -9,6 +9,7 @@ import { maybeCompressBase64 } from "../lib/utils.js";
 import { remote } from "webdriverio";
 import { AppTestPlatform } from "./appautomate-utils/native-execution/types.js";
 import { setupAppAutomateHandler } from "./appautomate-utils/appium-sdk/handler.js";
+import { validateAppAutomateDevices } from "./sdk-utils/common/device-validator.js";
 
 import {
   SETUP_APP_AUTOMATE_DESCRIPTION,
@@ -25,8 +26,6 @@ import {
   BrowserStackProducts,
 } from "../lib/device-cache.js";
 
-import { validateAppAutomateDevices } from "./sdk-utils/common/device-validator.js";
-
 import {
   findMatchingDevice,
   getDeviceVersions,