Merge branch 'SDK_PERCY_1' into cont-regression

Author: tech-sushant

src/tools/bstack-sdk.ts

@@ -5,12 +5,20 @@ import {
   SDKSupportedBrowserAutomationFramework,
   SDKSupportedLanguage,
   SDKSupportedTestingFramework,
+  SDKSupportedLanguageEnum,
+  SDKSupportedBrowserAutomationFrameworkEnum,
+  SDKSupportedTestingFrameworkEnum,
 } from "./sdk-utils/types.js";
 import {
   generateBrowserStackYMLInstructions,
   getInstructionsForProjectConfiguration,
 } from "./sdk-utils/instructions.js";
 import { trackMCP } from "../lib/instrumentation.js";
+import {
+  formatPercyInstructions,
+  getPercyInstructions,
+} from "./sdk-utils/percy/instructions.js";
+import { getSDKPrefixCommand } from "./sdk-utils/commands.js";
 
 /**
  * BrowserStack SDK hooks into your test framework to seamlessly run tests on BrowserStack.
@@ -21,25 +29,79 @@ export async function bootstrapProjectWithSDK({
   detectedTestingFramework,
   detectedLanguage,
   desiredPlatforms,
+  enablePercy,
 }: {
   detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFramework;
   detectedTestingFramework: SDKSupportedTestingFramework;
   detectedLanguage: SDKSupportedLanguage;
   desiredPlatforms: string[];
+  enablePercy: boolean;
 }): Promise<CallToolResult> {
-  const instructions = generateBrowserStackYMLInstructions(desiredPlatforms);
+  // Handle frameworks with unique setup instructions that don't use browserstack.yml
+  if (
+    detectedBrowserAutomationFramework === "cypress" ||
+    detectedTestingFramework === "webdriverio"
+  ) {
+    let instructions = getInstructionsForProjectConfiguration(
+      detectedBrowserAutomationFramework,
+      detectedTestingFramework,
+      detectedLanguage,
+    );
+    if (enablePercy) {
+      const percyInstructions = getPercyInstructions(
+        detectedLanguage,
+        detectedBrowserAutomationFramework,
+        detectedTestingFramework,
+      );
+      if (percyInstructions) {
+        instructions += formatPercyInstructions(percyInstructions);
+      }
+    }
+    return {
+      content: [{ type: "text", text: instructions, isError: false }],
+    };
+  }
+
+  let fullInstructions = "";
+  // Add language-dependent prefix command
+  fullInstructions += getSDKPrefixCommand(
+    detectedLanguage,
+    detectedTestingFramework,
+  );
+
+  const ymlInstructions = generateBrowserStackYMLInstructions(
+    desiredPlatforms,
+    enablePercy,
+  );
+  fullInstructions += `${ymlInstructions}`;
+
   const instructionsForProjectConfiguration =
     getInstructionsForProjectConfiguration(
       detectedBrowserAutomationFramework,
       detectedTestingFramework,
       detectedLanguage,
     );
 
+  if (enablePercy) {
+    const percyInstructions = getPercyInstructions(
+      detectedLanguage,
+      detectedBrowserAutomationFramework,
+      detectedTestingFramework,
+    );
+    if (percyInstructions) {
+      fullInstructions += formatPercyInstructions(percyInstructions);
+    } else {
+      fullInstructions += `\n\nNote: Percy SDK instructions for ${detectedLanguage} with ${detectedTestingFramework} are not yet available through this tool. Please refer to the official BrowserStack Percy documentation.`;
+    }
+  }
+
+  fullInstructions += `\n\nAfter setting up the files above, follow these final steps:\n${instructionsForProjectConfiguration}`;
+
   return {
     content: [
       {
         type: "text",
-        text: `${instructions}\n\n After creating the browserstack.yml file above, do the following: ${instructionsForProjectConfiguration}`,
+        text: fullInstructions,
         isError: false,
       },
     ],
@@ -49,20 +111,20 @@ export async function bootstrapProjectWithSDK({
 export default function addSDKTools(server: McpServer) {
   server.tool(
     "runTestsOnBrowserStack",
-    "Use this tool to get instructions for running tests on BrowserStack.",
+    "Use this tool to get instructions for running tests on BrowserStack and browserstack percy",
     {
       detectedBrowserAutomationFramework: z
-        .string()
+        .nativeEnum(SDKSupportedBrowserAutomationFrameworkEnum)
         .describe(
           "The automation framework configured in the project. Example: 'playwright', 'selenium'",
         ),
       detectedTestingFramework: z
-        .string()
+        .nativeEnum(SDKSupportedTestingFrameworkEnum)
         .describe(
-          "The testing framework used in the project. Be precise with framework selection Example: 'jest', 'pytest', 'junit4', 'junit5', 'mocha'",
+          "The testing framework used in the project. Be precise with framework selection Example: 'webdriverio', 'jest', 'pytest', 'junit4', 'junit5', 'mocha'",
         ),
       detectedLanguage: z
-        .string()
+        .nativeEnum(SDKSupportedLanguageEnum)
         .describe(
           "The programming language used in the project. Example: 'nodejs', 'python', 'java', 'csharp'",
         ),
@@ -71,6 +133,13 @@ export default function addSDKTools(server: McpServer) {
         .describe(
           "The platforms the user wants to test on. Always ask this to the user, do not try to infer this.",
         ),
+      enablePercy: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe(
+          "Set to true if the user wants to enable Percy for visual testing. Defaults to false.",
+        ),
     },
     async (args) => {
       try {
@@ -83,6 +152,7 @@ export default function addSDKTools(server: McpServer) {
             args.detectedTestingFramework as SDKSupportedTestingFramework,
           detectedLanguage: args.detectedLanguage as SDKSupportedLanguage,
           desiredPlatforms: args.desiredPlatforms,
+          enablePercy: args.enablePercy,
         });
       } catch (error) {
         trackMCP(

src/tools/sdk-utils/commands.ts

@@ -0,0 +1,51 @@
+// Utility to get the language-dependent prefix command for BrowserStack SDK setup
+import { SDKSupportedLanguage } from "./types.js";
+
+// Framework mapping for Java Maven archetype generation
+const JAVA_FRAMEWORK_MAP: Record<string, string> = {
+  testng: "testng",
+  junit: "junit5", // Map generic junit to junit5 as default
+  cucumber: "cucumber-testng", // Map generic cucumber to cucumber-testng as default
+};
+
+export function getSDKPrefixCommand(
+  language: SDKSupportedLanguage,
+  framework: string,
+): string {
+  switch (language) {
+    case "nodejs":
+      return `Install BrowserStack Node SDK\nusing command | npm i -D browserstack-node-sdk@latest\n| and then run following command to setup browserstack sdk:\n npx setup --username ${process.env.BROWSERSTACK_USERNAME} --key ${process.env.BROWSERSTACK_ACCESS_KEY}\n\n. This will create browserstack.yml file in the project root. Edit the file to add your desired platforms and browsers. If the file is not created :\n`;
+
+    case "java": {
+      const mavenFramework = getJavaFrameworkForMaven(framework);
+      return `Install BrowserStack Java SDK
+
+**Maven command for ${framework}:**
+Run the command, it is required to generate the browserstack-sdk-archetype-integrate project:
+mvn archetype:generate -B -DarchetypeGroupId=com.browserstack \\
+-DarchetypeArtifactId=browserstack-sdk-archetype-integrate -DarchetypeVersion=1.0 \\
+-DgroupId=com.browserstack -DartifactId=browserstack-sdk-archetype-integrate -Dversion=1.0 \\
+-DBROWSERSTACK_USERNAME=${process.env.BROWSERSTACK_USERNAME} -DBROWSERSTACK_ACCESS_KEY=${process.env.BROWSERSTACK_ACCESS_KEY} \\
+-DBROWSERSTACK_FRAMEWORK=${mavenFramework}
+
+**For Gradle setup:**
+1. Add browserstack-java-sdk to dependencies:
+   compileOnly 'com.browserstack:browserstack-java-sdk:latest.release'
+
+2. Add browserstackSDK path variable:
+   def browserstackSDKArtifact = configurations.compileClasspath.resolvedConfiguration.resolvedArtifacts.find { it.name == 'browserstack-java-sdk' }
+
+3. Add javaagent to gradle tasks:
+   jvmArgs "-javaagent:\${browserstackSDKArtifact.file}"
+`;
+    }
+
+    // Add more languages as needed
+    default:
+      return "";
+  }
+}
+
+export function getJavaFrameworkForMaven(framework: string): string {
+  return JAVA_FRAMEWORK_MAP[framework] || framework;
+}