@browserstack/mcp-server 1.2.4 → 1.2.5

package/dist/tools/appautomate-utils/appium-sdk/languages/java.js

@@ -4,15 +4,31 @@ import { createStep, combineInstructions, createEnvStep, PLATFORM_UTILS, } from
 export const MAVEN_ARCHETYPE_GROUP_ID = "com.browserstack";
 export const MAVEN_ARCHETYPE_ARTIFACT_ID = "junit-archetype-integrate";
 export const MAVEN_ARCHETYPE_VERSION = "1.0";
+// Version mapping for different frameworks
+export const JAVA_APP_FRAMEWORK_VERSION_MAP = {
+    testng: "1.4",
+    selenide: "1.4",
+    junit5: "1.0",
+    junit4: "1.0",
+    jbehave: "1.0",
+    cucumberTestng: "1.0",
+    cucumberJunit4: "1.0",
+    cucumberJunit5: "1.0",
+    cucumber: "1.0",
+    serenity: "1.0",
+};
 // Framework mapping for Java Maven archetype generation for App Automate
 export const JAVA_APP_FRAMEWORK_MAP = {
-    testng: "browserstack-sdk-archetype-integrate",
+    testng: "testng-archetype-integrate",
     junit5: "browserstack-sdk-archetype-integrate",
     selenide: "selenide-archetype-integrate",
     jbehave: "browserstack-sdk-archetype-integrate",
+    junit4: "browserstack-sdk-archetype-integrate",
     cucumberTestng: "browserstack-sdk-archetype-integrate",
     cucumberJunit4: "browserstack-sdk-archetype-integrate",
     cucumberJunit5: "browserstack-sdk-archetype-integrate",
+    cucumber: "browserstack-sdk-archetype-integrate",
+    serenity: "browserstack-sdk-archetype-integrate",
 };
 // Common Gradle setup instructions for App Automate (platform-independent)
 export const GRADLE_APP_SETUP_INSTRUCTIONS = `
@@ -35,53 +51,71 @@ mvn test
 export function getJavaAppFrameworkForMaven(framework) {
     return JAVA_APP_FRAMEWORK_MAP[framework] || framework;
 }
-function getMavenCommandForWindows(framework, mavenFramework, username, accessKey) {
-    return (`mvn archetype:generate -B ` +
+export function getJavaAppFrameworkVersion(framework) {
+    return JAVA_APP_FRAMEWORK_VERSION_MAP[framework] || MAVEN_ARCHETYPE_VERSION;
+}
+function getMavenCommandForWindows(framework, mavenFramework, version, username, accessKey, appPath) {
+    let command = `mvn archetype:generate -B ` +
         `-DarchetypeGroupId="${MAVEN_ARCHETYPE_GROUP_ID}" ` +
         `-DarchetypeArtifactId="${mavenFramework}" ` +
-        `-DarchetypeVersion="${MAVEN_ARCHETYPE_VERSION}" ` +
+        `-DarchetypeVersion="${version}" ` +
         `-DgroupId="${MAVEN_ARCHETYPE_GROUP_ID}" ` +
-        `-DartifactId="${MAVEN_ARCHETYPE_ARTIFACT_ID}" ` +
-        `-Dversion="${MAVEN_ARCHETYPE_VERSION}" ` +
+        `-DartifactId="${mavenFramework}" ` +
+        `-Dversion="${version}" ` +
         `-DBROWSERSTACK_USERNAME="${username}" ` +
-        `-DBROWSERSTACK_ACCESS_KEY="${accessKey}" ` +
-        `-DBROWSERSTACK_FRAMEWORK="${framework}"`);
+        `-DBROWSERSTACK_ACCESS_KEY="${accessKey}"`;
+    // Add framework parameter for browserstack-sdk-archetype-integrate
+    if (mavenFramework === "browserstack-sdk-archetype-integrate") {
+        command += ` -DBROWSERSTACK_FRAMEWORK="${framework}"`;
+    }
+    // Add app path if provided
+    if (appPath) {
+        command += ` -DBROWSERSTACK_APP="${appPath}"`;
+    }
+    return command;
 }
-function getMavenCommandForUnix(framework, mavenFramework, username, accessKey) {
-    return (`mvn archetype:generate -B ` +
+function getMavenCommandForUnix(framework, mavenFramework, version, username, accessKey, appPath) {
+    let command = `mvn archetype:generate -B ` +
         `-DarchetypeGroupId="${MAVEN_ARCHETYPE_GROUP_ID}" ` +
         `-DarchetypeArtifactId="${mavenFramework}" ` +
-        `-DarchetypeVersion="${MAVEN_ARCHETYPE_VERSION}" ` +
+        `-DarchetypeVersion="${version}" ` +
         `-DgroupId="${MAVEN_ARCHETYPE_GROUP_ID}" ` +
-        `-DartifactId="${MAVEN_ARCHETYPE_ARTIFACT_ID}" ` +
-        `-Dversion="${MAVEN_ARCHETYPE_VERSION}" ` +
+        `-DartifactId="${mavenFramework}" ` +
+        `-Dversion="${version}" ` +
         `-DBROWSERSTACK_USERNAME="${username}" ` +
-        `-DBROWSERSTACK_ACCESS_KEY="${accessKey}" ` +
-        `-DBROWSERSTACK_FRAMEWORK="${framework}"`);
+        `-DBROWSERSTACK_ACCESS_KEY="${accessKey}"`;
+    // Add framework parameter for browserstack-sdk-archetype-integrate
+    if (mavenFramework === "browserstack-sdk-archetype-integrate") {
+        command += ` -DBROWSERSTACK_FRAMEWORK="${framework}"`;
+    }
+    // Add app path if provided
+    if (appPath) {
+        command += ` -DBROWSERSTACK_APP="${appPath}"`;
+    }
+    return command;
 }
 export function getJavaSDKCommand(framework, username, accessKey, appPath) {
     const { isWindows = false, getPlatformLabel } = PLATFORM_UTILS || {};
     const mavenFramework = getJavaAppFrameworkForMaven(framework);
+    const version = getJavaAppFrameworkVersion(framework);
     let mavenCommand;
     if (isWindows) {
-        mavenCommand = getMavenCommandForWindows(framework, mavenFramework, username, accessKey);
-        if (appPath) {
-            mavenCommand += ` -DBROWSERSTACK_APP="${appPath}"`;
-        }
+        mavenCommand = getMavenCommandForWindows(framework, mavenFramework, version, username, accessKey, appPath);
     }
     else {
-        mavenCommand = getMavenCommandForUnix(framework, mavenFramework, username, accessKey);
-        if (appPath) {
-            mavenCommand += ` -DBROWSERSTACK_APP="${appPath}"`;
-        }
+        mavenCommand = getMavenCommandForUnix(framework, mavenFramework, version, username, accessKey, appPath);
     }
     const envStep = createEnvStep(username, accessKey, isWindows, getPlatformLabel());
     const mavenStep = createStep("Install BrowserStack SDK using Maven Archetype for App Automate", `Maven command for ${framework} (${getPlatformLabel()}):
-\`\`\`bash
-${mavenCommand}
-\`\`\`
+    \`\`\`bash
+    ${mavenCommand}
+    \`\`\`
 
-Alternative setup for Gradle users:
-${GRADLE_APP_SETUP_INSTRUCTIONS}`);
-    return combineInstructions(envStep, mavenStep);
+    Alternative setup for Gradle users:
+    ${GRADLE_APP_SETUP_INSTRUCTIONS}`);
+    const argsLineStep = createStep("Verifying dependency and argsLine", `Verify browserstack-java-sdk with LATEST is added as dependency and add this line in pom.xml if not added:
+    \`\`\`xml
+    <argLine>-javaagent:"\${com.browserstack:browserstack-java-sdk:jar}"</argLine>
+    \`\`\``);
+    return combineInstructions(envStep, mavenStep, argsLineStep);
 }

package/dist/tools/appautomate-utils/appium-sdk/types.d.ts

@@ -16,6 +16,7 @@ export declare enum AppSDKSupportedTestingFrameworkEnum {
     junit4 = "junit4",
     selenide = "selenide",
     jbehave = "jbehave",
+    serenity = "serenity",
     cucumberTestng = "cucumberTestng",
     cucumberJunit4 = "cucumberJunit4",
     cucumberJunit5 = "cucumberJunit5",
@@ -49,7 +50,7 @@ export interface AppSDKInstruction {
 export declare const SUPPORTED_CONFIGURATIONS: {
     appium: {
         ruby: string[];
-        java: never[];
+        java: string[];
         csharp: never[];
         python: string[];
         nodejs: string[];

package/dist/tools/appautomate-utils/appium-sdk/types.js

@@ -18,6 +18,7 @@ export var AppSDKSupportedTestingFrameworkEnum;
     AppSDKSupportedTestingFrameworkEnum["junit4"] = "junit4";
     AppSDKSupportedTestingFrameworkEnum["selenide"] = "selenide";
     AppSDKSupportedTestingFrameworkEnum["jbehave"] = "jbehave";
+    AppSDKSupportedTestingFrameworkEnum["serenity"] = "serenity";
     AppSDKSupportedTestingFrameworkEnum["cucumberTestng"] = "cucumberTestng";
     AppSDKSupportedTestingFrameworkEnum["cucumberJunit4"] = "cucumberJunit4";
     AppSDKSupportedTestingFrameworkEnum["cucumberJunit5"] = "cucumberJunit5";
@@ -46,7 +47,15 @@ export var AppSDKSupportedPlatformEnum;
 export const SUPPORTED_CONFIGURATIONS = {
     appium: {
         ruby: ["cucumberRuby"],
-        java: [],
+        java: [
+            "testng",
+            "cucumber",
+            "junit4",
+            "junit5",
+            "jbehave",
+            "selenide",
+            "serenity",
+        ],
         csharp: [],
         python: ["pytest", "robot", "behave", "lettuce"],
         nodejs: ["jest", "mocha", "cucumberJs", "webdriverio", "nightwatch"],

package/dist/tools/appautomate-utils/native-execution/constants.d.ts

@@ -1,10 +1,11 @@
 import { z } from "zod";
 import { AppTestPlatform } from "./types.js";
+import { AppSDKSupportedPlatformEnum } from "../appium-sdk/types.js";
 export declare const RUN_APP_AUTOMATE_DESCRIPTION = "Execute pre-built native mobile test suites (Espresso for Android, XCUITest for iOS) by direct upload to BrowserStack. ONLY for compiled .apk/.ipa test files. This is NOT for SDK integration or Appium tests. For Appium-based testing with SDK setup, use 'setupBrowserStackAppAutomateTests' instead.";
 export declare const RUN_APP_AUTOMATE_SCHEMA: {
     appPath: z.ZodString;
     testSuitePath: z.ZodString;
-    devices: z.ZodArray<z.ZodString, "many">;
+    devices: z.ZodDefault<z.ZodArray<z.ZodUnion<[z.ZodTuple<[z.ZodLiteral<AppSDKSupportedPlatformEnum.android>, z.ZodString, z.ZodString], null>, z.ZodTuple<[z.ZodLiteral<AppSDKSupportedPlatformEnum.ios>, z.ZodString, z.ZodString], null>]>, "many">>;
     project: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     detectedAutomationFramework: z.ZodNativeEnum<typeof AppTestPlatform>;
 };

package/dist/tools/appautomate-utils/native-execution/constants.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { AppTestPlatform } from "./types.js";
+import { AppSDKSupportedPlatformEnum } from "../appium-sdk/types.js";
 export const RUN_APP_AUTOMATE_DESCRIPTION = `Execute pre-built native mobile test suites (Espresso for Android, XCUITest for iOS) by direct upload to BrowserStack. ONLY for compiled .apk/.ipa test files. This is NOT for SDK integration or Appium tests. For Appium-based testing with SDK setup, use 'setupBrowserStackAppAutomateTests' instead.`;
 export const RUN_APP_AUTOMATE_SCHEMA = {
     appPath: z
@@ -23,8 +24,29 @@ export const RUN_APP_AUTOMATE_SCHEMA = {
         "  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']."),
+        .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([])
+        .describe("Tuples describing target mobile devices. Add device only when user asks explicitly for it. Defaults to [] . Example: [['android', 'Samsung Galaxy S24', '14'], ['ios', 'iPhone 15', '17']]"),
     project: z
         .string()
         .optional()

package/dist/tools/appautomate.js

@@ -6,6 +6,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, SETUP_APP_AUTOMATE_SCHEMA, } from "./appautomate-utils/appium-sdk/constants.js";
 import { Platform, } from "./appautomate-utils/native-execution/types.js";
 import { getDevicesAndBrowsers, BrowserStackProducts, } from "../lib/device-cache.js";
@@ -105,6 +106,8 @@ async function runAppTestsOnBrowserStack(args, config) {
     if (!args.browserstackTestSuiteUrl && !args.testSuitePath) {
         throw new Error("testSuitePath is required when browserstackTestSuiteUrl is not provided");
     }
+    // Validate devices against real BrowserStack device data
+    await validateAppAutomateDevices(args.devices);
     switch (args.detectedAutomationFramework) {
         case AppTestPlatform.ESPRESSO: {
             try {
@@ -126,7 +129,12 @@ async function runAppTestsOnBrowserStack(args, config) {
                     test_suite_url = await uploadEspressoTestSuite(args.testSuitePath, config);
                     logger.info(`Test suite uploaded. URL: ${test_suite_url}`);
                 }
-                const build_id = await triggerEspressoBuild(app_url, test_suite_url, args.devices, args.project);
+                // Convert array format to string format for Espresso
+                const deviceStrings = args.devices.map((device) => {
+                    const [, deviceName, osVersion] = device;
+                    return `${deviceName}-${osVersion}`;
+                });
+                const build_id = await triggerEspressoBuild(app_url, test_suite_url, deviceStrings, args.project);
                 return {
                     content: [
                         {
@@ -161,7 +169,12 @@ async function runAppTestsOnBrowserStack(args, config) {
                     test_suite_url = await uploadXcuiTestSuite(args.testSuitePath, config);
                     logger.info(`Test suite uploaded. URL: ${test_suite_url}`);
                 }
-                const build_id = await triggerXcuiBuild(app_url, test_suite_url, args.devices, args.project, config);
+                // Convert array format to string format for XCUITest
+                const deviceStrings = args.devices.map((device) => {
+                    const [, deviceName, osVersion] = device;
+                    return `${deviceName}-${osVersion}`;
+                });
+                const build_id = await triggerXcuiBuild(app_url, test_suite_url, deviceStrings, args.project, config);
                 return {
                     content: [
                         {

package/dist/tools/percy-sdk.js

@@ -5,14 +5,41 @@ import { runPercyScan } from "./run-percy-scan.js";
 import { SetUpPercyParamsShape } from "./sdk-utils/common/schema.js";
 import { updateTestsWithPercyCommands } from "./add-percy-snapshots.js";
 import { approveOrDeclinePercyBuild } from "./review-agent-utils/percy-approve-reject.js";
-import { setUpPercyHandler } from "./sdk-utils/handler.js";
-import { SETUP_PERCY_DESCRIPTION, LIST_TEST_FILES_DESCRIPTION, PERCY_SNAPSHOT_COMMANDS_DESCRIPTION, } from "./sdk-utils/common/constants.js";
+import { setUpPercyHandler, simulatePercyChangeHandler, } from "./sdk-utils/handler.js";
+import { z } from "zod";
+import { SETUP_PERCY_DESCRIPTION, LIST_TEST_FILES_DESCRIPTION, PERCY_SNAPSHOT_COMMANDS_DESCRIPTION, SIMULATE_PERCY_CHANGE_DESCRIPTION, } from "./sdk-utils/common/constants.js";
 import { ListTestFilesParamsShape, UpdateTestFileWithInstructionsParams, } from "./percy-snapshot-utils/constants.js";
 import { RunPercyScanParamsShape, FetchPercyChangesParamsShape, ManagePercyBuildApprovalParamsShape, } from "./sdk-utils/common/schema.js";
 import { handleMCPError } from "../lib/utils.js";
 export function registerPercyTools(server, config) {
     const tools = {};
-    tools.setupPercyVisualTesting = server.tool("setupPercyVisualTesting", SETUP_PERCY_DESCRIPTION, SetUpPercyParamsShape, async (args) => {
+    server.prompt("integrate-percy", {
+        project_name: z
+            .string()
+            .describe("The name of the project to integrate with Percy"),
+    }, async ({ project_name }) => {
+        return {
+            messages: [
+                {
+                    role: "assistant",
+                    content: {
+                        type: "text",
+                        text: `Integrate percy in this project ${project_name} using tool percyVisualTestIntegrationAgent.`,
+                    },
+                },
+            ],
+        };
+    });
+    tools.percyVisualTestIntegrationAgent = server.tool("percyVisualTestIntegrationAgent", SIMULATE_PERCY_CHANGE_DESCRIPTION, SetUpPercyParamsShape, async (args) => {
+        try {
+            trackMCP("VisualTestIntegrationAgent", server.server.getClientVersion(), config);
+            return simulatePercyChangeHandler(args, config);
+        }
+        catch (error) {
+            return handleMCPError("VisualTestIntegrationAgent", server, config, error);
+        }
+    });
+    tools.setupPercyVisualTesting = server.tool("expandPercyVisualTesting", SETUP_PERCY_DESCRIPTION, SetUpPercyParamsShape, async (args) => {
         try {
             trackMCP("setupPercyVisualTesting", server.server.getClientVersion(), config);
             return setUpPercyHandler(args, config);

package/dist/tools/run-percy-scan.js

@@ -15,7 +15,7 @@ export async function runPercyScan(args, config) {
     - Python → pytest
     - Node.js → npm test or yarn test
     - Cypress → cypress run
-    or from package.json scripts`, `Wrap the inferred command with Percy:\nnpx percy exec -- <test command>`, `If the test command cannot be inferred confidently, ask the user directly for the correct test command.`);
+    or from package.json scripts`, `Wrap the inferred command with Percy along with label: \nnpx percy exec --labels=mcp -- <test command>`, `If the test command cannot be inferred confidently, ask the user directly for the correct test command.`);
     const instructionContext = steps
         .map((step, index) => `${index + 1}. ${step}`)
         .join("\n\n");

package/dist/tools/sdk-utils/bstack/configUtils.d.ts

@@ -1,4 +1,7 @@
-/**
- * Utilities for generating BrowserStack configuration files.
- */
-export declare function generateBrowserStackYMLInstructions(desiredPlatforms: string[], enablePercy: boolean | undefined, projectName: string): string;
+import { ValidatedEnvironment } from "../common/device-validator.js";
+export declare function generateBrowserStackYMLInstructions(config: {
+    validatedEnvironments?: ValidatedEnvironment[];
+    platforms?: string[];
+    enablePercy?: boolean;
+    projectName: string;
+}): string;

package/dist/tools/sdk-utils/bstack/configUtils.js

@@ -1,37 +1,34 @@
-/**
- * Utilities for generating BrowserStack configuration files.
- */
-export function generateBrowserStackYMLInstructions(desiredPlatforms, enablePercy = false, projectName) {
+export function generateBrowserStackYMLInstructions(config) {
+    const enablePercy = config.enablePercy || false;
+    const projectName = config.projectName || "BrowserStack Automate Build";
+    // Generate platform configurations using the utility function
+    const platformConfigs = generatePlatformConfigs(config);
+    const stepTitle = "Create a browserstack.yml file in the project root with your validated device configurations:";
+    const buildName = `${projectName}-Build`;
     let ymlContent = `
 # ======================
 # BrowserStack Reporting
 # ======================
-# A single name for your project to organize all your tests. This is required for Percy.
-projectName: ${projectName}
+
 # TODO: Replace these sample values with your actual project details
-buildName: Sample-Build
+projectName: ${projectName}
+buildName: ${buildName}
 
 # =======================================
 # Platforms (Browsers / Devices to test)
-# =======================================
+# =======================================`;
+    ymlContent += `
 # Platforms object contains all the browser / device combinations you want to test on.
-# Generate this on the basis of the following platforms requested by the user:
-# Requested platforms: ${desiredPlatforms}
 platforms:
-  - os: Windows
-    osVersion: 11
-    browserName: chrome
-    browserVersion: latest
-  
+${platformConfigs}`;
+    ymlContent += `
+
 # =======================
 # Parallels per Platform
 # =======================
 # The number of parallel threads to be used for each platform set.
 # BrowserStack's SDK runner will select the best strategy based on the configured value
-#
-# Example 1 - If you have configured 3 platforms and set \`parallelsPerPlatform\` as 2, a total of 6 (2 * 3) parallel threads will be used on BrowserStack
-#
-# Example 2 - If you have configured 1 platform and set \`parallelsPerPlatform\` as 5, a total of 5 (1 * 5) parallel threads will be used on BrowserStack
+# The number of parallel threads to be used for each platform set.
 parallelsPerPlatform: 1
 
 # =================
@@ -58,9 +55,59 @@ percyCaptureMode: manual`;
     }
     return `
 ---STEP---
-Create a browserstack.yml file in the project root. The file should be in the following format:
+${stepTitle}
 
 \`\`\`yaml${ymlContent}
 \`\`\`
 \n`;
 }
+function generatePlatformConfigs(config) {
+    if (config.validatedEnvironments && config.validatedEnvironments.length > 0) {
+        // Generate platforms array from validated environments
+        const platforms = config.validatedEnvironments.map((env) => {
+            if (env.platform === "windows" || env.platform === "macos") {
+                // Desktop configuration
+                return {
+                    os: env.platform === "windows" ? "Windows" : "OS X",
+                    osVersion: env.osVersion,
+                    browserName: env.browser,
+                    browserVersion: env.browserVersion || "latest",
+                };
+            }
+            else {
+                // Mobile configuration (android/ios)
+                return {
+                    deviceName: env.deviceName,
+                    osVersion: env.osVersion,
+                    browserName: env.browser,
+                };
+            }
+        });
+        // Convert platforms to YAML format
+        return platforms
+            .map((platform) => {
+            if (platform.deviceName) {
+                // Mobile platform
+                return `  - deviceName: "${platform.deviceName}"
+    osVersion: "${platform.osVersion}"
+    browserName: ${platform.browserName}`;
+            }
+            else {
+                // Desktop platform
+                return `  - os: ${platform.os}
+    osVersion: "${platform.osVersion}"
+    browserName: ${platform.browserName}
+    browserVersion: ${platform.browserVersion}`;
+            }
+        })
+            .join("\n");
+    }
+    else if (config.platforms && config.platforms.length > 0) {
+        // Fallback to default platforms configuration
+        return `  - os: Windows
+    osVersion: 11
+    browserName: chrome
+    browserVersion: latest`;
+    }
+    return "";
+}

package/dist/tools/sdk-utils/bstack/sdkHandler.d.ts

@@ -1,4 +1,4 @@
 import { RunTestsInstructionResult } from "../common/types.js";
 import { RunTestsOnBrowserStackInput } from "../common/schema.js";
 import { BrowserStackConfig } from "../../../lib/types.js";
-export declare function runBstackSDKOnly(input: RunTestsOnBrowserStackInput, config: BrowserStackConfig, isPercyAutomate?: boolean): RunTestsInstructionResult;
+export declare function runBstackSDKOnly(input: RunTestsOnBrowserStackInput, config: BrowserStackConfig, isPercyAutomate?: boolean): Promise<RunTestsInstructionResult>;

package/dist/tools/sdk-utils/bstack/sdkHandler.js

@@ -2,10 +2,14 @@ import { getBrowserStackAuth } from "../../../lib/get-auth.js";
 import { getSDKPrefixCommand } from "./commands.js";
 import { generateBrowserStackYMLInstructions } from "./configUtils.js";
 import { getInstructionsForProjectConfiguration } from "../common/instructionUtils.js";
-export function runBstackSDKOnly(input, config, isPercyAutomate = false) {
+import { validateDevices } from "../common/device-validator.js";
+export async function runBstackSDKOnly(input, config, isPercyAutomate = false) {
     const steps = [];
     const authString = getBrowserStackAuth(config);
     const [username, accessKey] = authString.split(":");
+    // Validate devices against real BrowserStack device data
+    const tupleTargets = input.devices;
+    const validatedEnvironments = await validateDevices(tupleTargets || [], input.detectedBrowserAutomationFramework);
     // Handle frameworks with unique setup instructions that don't use browserstack.yml
     if (input.detectedBrowserAutomationFramework === "cypress" ||
         input.detectedTestingFramework === "webdriverio") {
@@ -41,7 +45,11 @@ export function runBstackSDKOnly(input, config, isPercyAutomate = false) {
             content: sdkSetupCommand,
         });
     }
-    const ymlInstructions = generateBrowserStackYMLInstructions(input.desiredPlatforms, false, input.projectName);
+    const ymlInstructions = generateBrowserStackYMLInstructions({
+        validatedEnvironments,
+        enablePercy: false,
+        projectName: input.projectName,
+    });
     if (ymlInstructions) {
         steps.push({
             type: "instruction",

package/dist/tools/sdk-utils/common/constants.d.ts

@@ -1,10 +1,11 @@
 export declare const IMPORTANT_SETUP_WARNING = "IMPORTANT: DO NOT SKIP ANY STEP. All the setup steps described below MUST be executed regardless of any existing configuration or setup. This ensures proper BrowserStack SDK setup.";
-export declare const SETUP_PERCY_DESCRIPTION = "Set up Percy visual testing for your project. This supports both Percy Web Standalone and Percy Automate.";
+export declare const SETUP_PERCY_DESCRIPTION = "Set up or expand Percy visual testing configuration with comprehensive coverage for existing projects that might have Percy integrated. This supports both Percy Web Standalone and Percy Automate. Example prompts: Expand percy coverage for this project {project_name}";
 export declare const LIST_TEST_FILES_DESCRIPTION = "Lists all test files for a given set of directories.";
 export declare const PERCY_SNAPSHOT_COMMANDS_DESCRIPTION = "Adds Percy snapshot commands to the specified test files.";
 export declare const RUN_ON_BROWSERSTACK_DESCRIPTION = "Set up and run automated web-based tests on BrowserStack using the BrowserStack SDK. Use this tool for functional or integration test setup on BrowserStack only. For any visual testing or Percy integration, use the dedicated Percy setup tool. Example prompts: run this test on browserstack; set up this project for browserstack.";
-export declare const SIMULATE_PERCY_CHANGE_DESCRIPTION = "This tool helps new users simulate a Percy visual change by guiding them to make a visible UI modification, rerun Percy, and verify that the change is detected. Only Percy web is supported";
+export declare const SIMULATE_PERCY_CHANGE_DESCRIPTION = "Integrate Percy visual testing into new projects and demonstrate visual change detection through a step-by-step simulation. This tool handles initial Percy integration, setup, and creates a working demonstration for new users. Primary tool for prompts like: \"Integrate percy for this project\", \"Integrate percy in this project {project_name}\"";
 export declare const PERCY_REPLACE_REGEX: RegExp;
 export declare const PERCY_SNAPSHOT_INSTRUCTION = "\nInvoke listTestFiles() with the provided directories from user to gather all test files in memory and obtain the generated UUID ---STEP---\nProcess files in STRICT sequential order using tool addPercySnapshotCommands() with below instructions:\n- Start with index 0\n- Then index 1  \n- Then index 2\n- Continue sequentially until the last index\n- DO NOT skip any index numbers\n- DO NOT jump to random indices like 10, 20, 30\n- DO NOT worry about time consuming and any constraints.\n- DO NOT STOP until you add commands in all the files or you reach end of the files.\n";
-export declare const PERCY_SIMULATE_INSTRUCTION = "\nMANDATORY: Aggressive, Accurate Percy Snapshots Integration\n\nPrerequisite: Before making any code changes in the user's repo, switch to a branch named temp-percy (run git init first if the repo is not yet initialized).\n\nYou MUST follow these steps with NO EXCEPTIONS:\n1. Identify 4-5 key test files in the project that are critical for visual testing.\n2. For EACH identified test file, analyze the code to find EVERY location where a Percy snapshot should be called (e.g., after each navigation, UI change, or significant state in tests).\n3. Insert snapshot calls at ALL such points, not just the first or most obvious one.\n\nIteratively update every selected test file with percy snapshot calls at all identified points, ensuring comprehensive coverage of visual changes.";
-export declare const PERCY_SIMULATION_DRIVER_INSTRUCTION = "\nMANDATORY: Step-by-Step Percy Visual Change Simulation\nYou MUST follow these steps with NO EXCEPTIONS:\n\nSTEP 1: At this case we have added Percy snapshot commands to the test files at the appropriate locations (e.g., after navigation, UI change, or significant state). \n- Use ONLY existing snapshot names.\n- Do NOT add any popup injection or visual changes yet.\n- Do NOT run any Percy builds at this stage.\n\nSTEP 2: Run ONE comprehensive baseline Percy build that executes ALL tests containing Percy snapshots in a SINGLE build. This creates one baseline build with all snapshots for comparison. Use a command like: npx percy exec -- python -m pytest tests/ -k 'test_name1 or test_name2 or test_name3' -v to run multiple specific tests in one build.\"\n\nSTEP 3: Modify your test to inject a visible UI change (such as a popup) IMMEDIATELY BEFORE an EXISTING snapshot command (e.g., before percy_snapshot(self.driver, \"screenshot name\")).\n- Do NOT add a new snapshot name for the popup.\n- The popup must appear in an existing snapshot, not a new one.\n- Add this popup code in some test files before the percy_snapshot command you've added, to display the visual changes.\n\n```Javascript\npopup_script = `\nvar popup = document.createElement('div');\npopup.id = 'percy-test-popup';\npopup.style.cssText = popup.style.cssText = `\n  /* TODO: Add styles to make the popup large, centered, and visually noticeable.\n     Suggested properties: position: fixed; top/left; transform; background; color; font-size; padding; z-index; animation, etc. */\n`;\npopup.innerHTML = 'PERCY TEST<br>VISUAL CHANGE<br>DETECTED!';\ndocument.body.appendChild(popup);\n`;\n\n# Insert this just before the EXISTING snapshot command:\ndriver.execute_script(popup_script)\npercy_snapshot(self.driver, \"Before Adding to Cart\")  # (Do NOT change the snapshot name, keep existing one)\n```\n\nSTEP 4: Run a second Percy build.\n- The snapshot names must remain the same as in the baseline.\n- The visual change should now appear in the same snapshot as before.\n- Use the same build command you ran for the baseline.\n\nSTEP 5: Compare the two Percy builds to see the detected visual difference.\n\nSTEP 6: Now ask user if they want to setup percy for full project coverage? If yes, call the \"setupPercyVisualTesting\" tool to enable complete coverage for the entire project.\n\nCONSTRAINTS:\n- Do NOT run any builds until explicitly instructed in the steps.\n- Do NOT add new snapshot names\u2014only use existing ones.\n- Do NOT add popup injection until the baseline is established.\n- Visual changes must appear in EXISTING snapshots, not new ones.\n\nVALIDATION CHECKPOINTS (before proceeding to the next step):\n- Are you adding only snapshot commands (not running builds)?\n- Are you reusing existing snapshot names (not creating new ones)?\n- Have you established the baseline first (before adding visual changes)\n\nCRITICAL: \nDo NOT run tests separately or create multiple builds during baseline establishment. The goal is to have exactly TWO builds total: (1) baseline build with all original snapshots, (2) modified build with the same tests but visual changes injected.\n";
+export declare const PERCY_SIMULATE_INSTRUCTION = "\nMANDATORY: Aggressive, Accurate Percy Snapshots Integration\n\nPrerequisite: Before making any code changes in the user's repository, create and switch to a new branch named browserstack-simulation. Stage all changes but do not commit them. If the repository has not been initialized yet, run git init first.\n\nYou MUST follow these steps with NO EXCEPTIONS:\n1. Identify 4-5 key test files in the project that are critical for visual testing.\n2. For EACH identified test file, analyze the code to find EVERY location where a Percy snapshot should be called (e.g., after each navigation, UI change, or significant state in tests).\n3. Insert snapshot calls at ALL such points, not just the first or most obvious one.\n\nIteratively update every selected test file with percy snapshot calls at all identified points, ensuring comprehensive coverage of visual changes.";
+export declare const PERCY_SIMULATION_DRIVER_INSTRUCTION = "\nMANDATORY: Step-by-Step Percy Visual Change Simulation\nYou MUST follow these steps with NO EXCEPTIONS:\n\nSTEP 1: At this case we have added Percy snapshot commands to the test files at the appropriate locations (e.g., after navigation, UI change, or significant state). \n- Use ONLY existing snapshot names.\n- Do NOT add any popup injection or visual changes yet.\n- Do NOT run any Percy builds at this stage.\n\nSTEP 2: Run ONE comprehensive baseline Percy build that executes ALL tests containing Percy snapshots in a SINGLE build. This creates one baseline build with all snapshots for comparison. Use a command like: npx percy exec --label=mcp -- python -m pytest tests/ -k 'test_name1 or test_name2 or test_name3' -v to run multiple specific tests in one build.\"\n\nSTEP 3: Modify your test to inject a visible UI change (such as a popup) IMMEDIATELY BEFORE an EXISTING snapshot command (e.g., before percy_snapshot(self.driver, \"screenshot name\")).\n- Do NOT add a new snapshot name for the popup.\n- The popup must appear in an existing snapshot, not a new one.\n- Add this popup code in some test files before the percy_snapshot command you've added, to display the visual changes.\n\n```Javascript\npopup_script = `\nvar popup = document.createElement('div');\npopup.id = 'percy-test-popup';\npopup.style.cssText = popup.style.cssText = `\n  /* TODO: Add styles to make the popup large, centered, and visually noticeable.\n     Suggested properties: position: fixed; top/left; transform; background; color; font-size; padding; z-index; animation, etc. */\n`;\npopup.innerHTML = 'PERCY TEST<br>VISUAL CHANGE<br>DETECTED!';\ndocument.body.appendChild(popup);\n`;\n\n# Insert this just before the EXISTING snapshot command:\ndriver.execute_script(popup_script)\npercy_snapshot(self.driver, \"Before Adding to Cart\")  # (Do NOT change the snapshot name, keep existing one)\n```\n\nSTEP 4: Run a second Percy build with same label and same test command as the baseline.\n- The snapshot names must remain the same as in the baseline.\n- The visual change should now appear in the same snapshot as before.\n- Use the same build command you ran for the baseline.\n\nSTEP 5: Compare the two Percy builds to see the detected visual difference.\n\nSTEP 6: Now ask user if they want to expand percy for other testcases? If yes, call the \"expandPercyVisualTesting\" tool to enable complete coverage for the entire project.\n\nCONSTRAINTS:\n- Do NOT run any builds until explicitly instructed in the steps.\n- Do NOT add new snapshot names\u2014only use existing ones.\n- Do NOT add popup injection until the baseline is established.\n- Visual changes must appear in EXISTING snapshots, not new ones.\n\nVALIDATION CHECKPOINTS (before proceeding to the next step):\n- Are you adding only snapshot commands (not running builds)?\n- Are you reusing existing snapshot names (not creating new ones)?\n- Have you established the baseline first (before adding visual changes)\n\nCRITICAL: \nDo NOT run tests separately or create multiple builds during baseline establishment. The goal is to have exactly TWO builds total: (1) baseline build with all original snapshots, (2) modified build with the same tests but visual changes injected.\n";
+export declare const PERCY_VERIFICATION_REGEX: RegExp;

package/dist/tools/sdk-utils/common/constants.js

@@ -1,9 +1,9 @@
 export const IMPORTANT_SETUP_WARNING = "IMPORTANT: DO NOT SKIP ANY STEP. All the setup steps described below MUST be executed regardless of any existing configuration or setup. This ensures proper BrowserStack SDK setup.";
-export const SETUP_PERCY_DESCRIPTION = "Set up Percy visual testing for your project. This supports both Percy Web Standalone and Percy Automate.";
+export const SETUP_PERCY_DESCRIPTION = "Set up or expand Percy visual testing configuration with comprehensive coverage for existing projects that might have Percy integrated. This supports both Percy Web Standalone and Percy Automate. Example prompts: Expand percy coverage for this project {project_name}";
 export const LIST_TEST_FILES_DESCRIPTION = "Lists all test files for a given set of directories.";
 export const PERCY_SNAPSHOT_COMMANDS_DESCRIPTION = "Adds Percy snapshot commands to the specified test files.";
 export const RUN_ON_BROWSERSTACK_DESCRIPTION = "Set up and run automated web-based tests on BrowserStack using the BrowserStack SDK. Use this tool for functional or integration test setup on BrowserStack only. For any visual testing or Percy integration, use the dedicated Percy setup tool. Example prompts: run this test on browserstack; set up this project for browserstack.";
-export const SIMULATE_PERCY_CHANGE_DESCRIPTION = "This tool helps new users simulate a Percy visual change by guiding them to make a visible UI modification, rerun Percy, and verify that the change is detected. Only Percy web is supported";
+export const SIMULATE_PERCY_CHANGE_DESCRIPTION = `Integrate Percy visual testing into new projects and demonstrate visual change detection through a step-by-step simulation. This tool handles initial Percy integration, setup, and creates a working demonstration for new users. Primary tool for prompts like: "Integrate percy for this project", "Integrate percy in this project {project_name}"`;
 export const PERCY_REPLACE_REGEX = /Invoke listTestFiles\(\) with the provided directories[\s\S]*?- DO NOT STOP until you add commands in all the files or you reach end of the files\./;
 export const PERCY_SNAPSHOT_INSTRUCTION = `
 Invoke listTestFiles() with the provided directories from user to gather all test files in memory and obtain the generated UUID ---STEP---
@@ -20,7 +20,7 @@ Process files in STRICT sequential order using tool addPercySnapshotCommands() w
 export const PERCY_SIMULATE_INSTRUCTION = `
 MANDATORY: Aggressive, Accurate Percy Snapshots Integration
 
-Prerequisite: Before making any code changes in the user's repo, switch to a branch named temp-percy (run git init first if the repo is not yet initialized).
+Prerequisite: Before making any code changes in the user's repository, create and switch to a new branch named browserstack-simulation. Stage all changes but do not commit them. If the repository has not been initialized yet, run git init first.
 
 You MUST follow these steps with NO EXCEPTIONS:
 1. Identify 4-5 key test files in the project that are critical for visual testing.
@@ -37,7 +37,7 @@ STEP 1: At this case we have added Percy snapshot commands to the test files at
 - Do NOT add any popup injection or visual changes yet.
 - Do NOT run any Percy builds at this stage.
 
-STEP 2: Run ONE comprehensive baseline Percy build that executes ALL tests containing Percy snapshots in a SINGLE build. This creates one baseline build with all snapshots for comparison. Use a command like: npx percy exec -- python -m pytest tests/ -k 'test_name1 or test_name2 or test_name3' -v to run multiple specific tests in one build."
+STEP 2: Run ONE comprehensive baseline Percy build that executes ALL tests containing Percy snapshots in a SINGLE build. This creates one baseline build with all snapshots for comparison. Use a command like: npx percy exec --label=mcp -- python -m pytest tests/ -k 'test_name1 or test_name2 or test_name3' -v to run multiple specific tests in one build."
 
 STEP 3: Modify your test to inject a visible UI change (such as a popup) IMMEDIATELY BEFORE an EXISTING snapshot command (e.g., before percy_snapshot(self.driver, "screenshot name")).
 - Do NOT add a new snapshot name for the popup.
@@ -61,14 +61,14 @@ driver.execute_script(popup_script)
 percy_snapshot(self.driver, "Before Adding to Cart")  # (Do NOT change the snapshot name, keep existing one)
 \`\`\`
 
-STEP 4: Run a second Percy build.
+STEP 4: Run a second Percy build with same label and same test command as the baseline.
 - The snapshot names must remain the same as in the baseline.
 - The visual change should now appear in the same snapshot as before.
 - Use the same build command you ran for the baseline.
 
 STEP 5: Compare the two Percy builds to see the detected visual difference.
 
-STEP 6: Now ask user if they want to setup percy for full project coverage? If yes, call the "setupPercyVisualTesting" tool to enable complete coverage for the entire project.
+STEP 6: Now ask user if they want to expand percy for other testcases? If yes, call the "expandPercyVisualTesting" tool to enable complete coverage for the entire project.
 
 CONSTRAINTS:
 - Do NOT run any builds until explicitly instructed in the steps.
@@ -84,3 +84,4 @@ VALIDATION CHECKPOINTS (before proceeding to the next step):
 CRITICAL: 
 Do NOT run tests separately or create multiple builds during baseline establishment. The goal is to have exactly TWO builds total: (1) baseline build with all original snapshots, (2) modified build with the same tests but visual changes injected.
 `;
+export const PERCY_VERIFICATION_REGEX = /\*\*✅ Verification:\*\*\nPlease verify that you have completed all[\s\S]*?double-check each step and ensure all commands executed successfully\./s;

package/dist/tools/sdk-utils/common/device-validator.d.ts

@@ -0,0 +1,25 @@
+export interface DesktopBrowserEntry {
+    os: string;
+    os_version: string;
+    browser: string;
+    browser_version: string;
+}
+export interface MobileDeviceEntry {
+    os: "android" | "ios";
+    os_version: string;
+    display_name: string;
+    browsers?: Array<{
+        browser: string;
+        display_name?: string;
+    }>;
+}
+export interface ValidatedEnvironment {
+    platform: string;
+    osVersion: string;
+    browser?: string;
+    browserVersion?: string;
+    deviceName?: string;
+    notes?: string;
+}
+export declare function validateDevices(devices: Array<Array<string>>, framework?: string): Promise<ValidatedEnvironment[]>;
+export declare function validateAppAutomateDevices(devices: Array<Array<string>>): Promise<ValidatedEnvironment[]>;