@browserstack/mcp-server 1.2.2-beta.1 → 1.2.3-beta.1

package/dist/tools/sdk-utils/instructions.js

@@ -0,0 +1,99 @@
+import { SUPPORTED_CONFIGURATIONS } from "./constants.js";
+const errorMessageSuffix = "Please open an issue at our Github repo: https://github.com/browserstack/browserstack-mcp-server/issues to request support for your project configuration";
+export const getInstructionsForProjectConfiguration = (detectedBrowserAutomationFramework, detectedTestingFramework, detectedLanguage, username, accessKey) => {
+    const configuration = SUPPORTED_CONFIGURATIONS[detectedLanguage];
+    if (!configuration) {
+        throw new Error(`BrowserStack MCP Server currently does not support ${detectedLanguage}, ${errorMessageSuffix}`);
+    }
+    if (!configuration[detectedBrowserAutomationFramework]) {
+        throw new Error(`BrowserStack MCP Server currently does not support ${detectedBrowserAutomationFramework} for ${detectedLanguage}, ${errorMessageSuffix}`);
+    }
+    if (!configuration[detectedBrowserAutomationFramework][detectedTestingFramework]) {
+        throw new Error(`BrowserStack MCP Server currently does not support ${detectedTestingFramework} for ${detectedBrowserAutomationFramework} on ${detectedLanguage}, ${errorMessageSuffix}`);
+    }
+    const instructionFunction = configuration[detectedBrowserAutomationFramework][detectedTestingFramework]
+        .instructions;
+    return instructionFunction(username, accessKey);
+};
+export function generateBrowserStackYMLInstructions(desiredPlatforms, enablePercy = false) {
+    let ymlContent = `
+# ======================
+# BrowserStack Reporting
+# ======================
+# Project and build names help organize your test runs in BrowserStack dashboard and Percy.
+# TODO: Replace these sample values with your actual project details
+projectName: Sample Project
+buildName: Sample Build
+
+# =======================================
+# Platforms (Browsers / Devices to test)
+# =======================================
+# 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
+  
+# =======================
+# 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
+parallelsPerPlatform: 1
+
+# =================
+# Local Testing
+# =================
+# Set to true to test local
+browserstackLocal: true
+
+# ===================
+# Debugging features
+# ===================
+debug: true # Visual logs, text logs, etc.
+testObservability: true # For Test Observability`;
+    if (enablePercy) {
+        ymlContent += `
+
+# =====================
+# Percy Visual Testing
+# =====================
+# Set percy to true to enable visual testing.
+# Set percyCaptureMode to 'manual' to control when screenshots are taken.
+percy: true
+percyCaptureMode: manual`;
+    }
+    return `
+      Create a browserstack.yml file in the project root. The file should be in the following format:
+
+      \`\`\`yaml${ymlContent}
+      \`\`\`
+      \n`;
+}
+export function formatInstructionsWithNumbers(instructionText, separator = "---STEP---") {
+    // Split the instructions by the separator
+    const steps = instructionText
+        .split(separator)
+        .map((step) => step.trim())
+        .filter((step) => step.length > 0);
+    // If no separators found, treat the entire text as one step
+    if (steps.length === 1 && !instructionText.includes(separator)) {
+        return `**Step 1:**\n${instructionText.trim()}\n\n**✅ Verification:**\nPlease verify that you have completed all the steps above to ensure proper setup.`;
+    }
+    // Format each step with numbering
+    const formattedSteps = steps
+        .map((step, index) => {
+        return `**Step ${index + 1}:**\n${step.trim()}`;
+    })
+        .join("\n\n");
+    // Add verification statement at the end
+    const verificationText = `\n\n**✅ Verification:**\nPlease verify that you have completed all ${steps.length} steps above to ensure proper setup. If you encounter any issues, double-check each step and ensure all commands executed successfully.`;
+    return formattedSteps + verificationText;
+}

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

@@ -0,0 +1,3 @@
+import { PercyConfigMapping } from "./types.js";
+export declare const nodejsSeleniumInstructions = "\nImport the BrowserStack Percy SDK in your test script:\nAdd the Percy import to your test file.\n\n---STEP---\n\nAdd screenshot capture method at required points:\nUse the `percy.snapshot(driver, name)` method at points in your test script where you want to capture screenshots.\n\n```javascript\nconst { percy } = require('browserstack-node-sdk');\ndescribe(\"sample Test\", () => {\n  // ... other imports and setup\n  \n  test(\"my test\", async () => {\n    // ....\n    await percy.snapshot(driver, \"My Snapshot\")\n    // ....\n  });\n})\n```\n";
+export declare const PERCY_INSTRUCTIONS: PercyConfigMapping;

package/dist/tools/sdk-utils/{percy-bstack → percy}/constants.js

@@ -1,9 +1,8 @@
-import { PERCY_SNAPSHOT_INSTRUCTION } from "../common/constants.js";
-export const javaSeleniumInstructions = `
+const javaSeleniumInstructions = `
 Import the BrowserStack Percy SDK in your test script:
 Add the Percy import to your test file.
 
-${PERCY_SNAPSHOT_INSTRUCTION}
+---STEP---
 
 Add screenshot capture method at required points:
 Use the \`PercySDK.screenshot(driver, name)\` method at points in your test script where you want to capture screenshots.
@@ -33,8 +32,6 @@ export const nodejsSeleniumInstructions = `
 Import the BrowserStack Percy SDK in your test script:
 Add the Percy import to your test file.
 
-${PERCY_SNAPSHOT_INSTRUCTION}
-
 ---STEP---
 
 Add screenshot capture method at required points:
@@ -47,19 +44,19 @@ describe("sample Test", () => {
   
   test("my test", async () => {
     // ....
-    await percy.screenshot(driver, "My Snapshot")
+    await percy.snapshot(driver, "My Snapshot")
     // ....
   });
 })
 \`\`\`
 `;
-export const webdriverioPercyInstructions = `
+const webdriverioPercyInstructions = `
 Enable Percy in \`wdio.conf.js\`:
 In your WebdriverIO configuration file, modify the 'browserstack' service options to enable Percy.
 
 - Set \`percy: true\`.
 - Set a \`projectName\`. This is required and will be used for both your Automate and Percy projects.
-- Set \`percyCaptureMode\`. The default \`manual\` as we are adding screenshot commands manually.
+- Set \`percyCaptureMode\`. The default \`auto\` mode is recommended, which captures screenshots on events like clicks. Other modes are \`testcase\`, \`click\`, \`screenshot\`, and \`manual\`.
 
 Here's how to modify the service configuration:
 \`\`\`javascript
@@ -73,7 +70,7 @@ exports.config = {
       { 
         // ... other service options
         percy: true,
-        percyCaptureMode: 'manual' // or 'auto', etc.
+        percyCaptureMode: 'auto' // or 'manual', 'testcase', etc.
       },
     ],
   ],
@@ -88,8 +85,6 @@ exports.config = {
 };
 \`\`\`
 
-${PERCY_SNAPSHOT_INSTRUCTION}
-
 ---STEP---
 
 Manually Capturing Screenshots (Optional):
@@ -117,11 +112,11 @@ describe("My WebdriverIO Test", () => {
 });
 \`\`\`
 `;
-export const csharpSeleniumInstructions = `
+const csharpSeleniumInstructions = `
 Import the BrowserStack Percy SDK in your test script:
 Add the Percy import to your test file.
 
-${PERCY_SNAPSHOT_INSTRUCTION}
+---STEP---
 
 Add screenshot capture method at required points:
 Use the \`PercySDK.Screenshot(driver, name)\` method at points in your test script where you want to capture screenshots.
@@ -130,6 +125,8 @@ Here's an example:
 
 \`\`\`csharp
 using BrowserStackSDK.Percy;
+using NUnit.Framework;
+
 namespace Tests;
 
 public class MyTest
@@ -149,3 +146,32 @@ public class MyTest
 }
 \`\`\`
 `;
+export const PERCY_INSTRUCTIONS = {
+    java: {
+        selenium: {
+            testng: { script_updates: javaSeleniumInstructions },
+            cucumber: { script_updates: javaSeleniumInstructions },
+            junit4: { script_updates: javaSeleniumInstructions },
+            junit5: { script_updates: javaSeleniumInstructions },
+            serenity: { script_updates: javaSeleniumInstructions },
+        },
+    },
+    csharp: {
+        selenium: {
+            nunit: { script_updates: csharpSeleniumInstructions },
+        },
+    },
+    nodejs: {
+        selenium: {
+            mocha: {
+                script_updates: nodejsSeleniumInstructions,
+            },
+            jest: {
+                script_updates: nodejsSeleniumInstructions,
+            },
+            webdriverio: {
+                script_updates: webdriverioPercyInstructions,
+            },
+        },
+    },
+};

package/dist/tools/sdk-utils/percy/instructions.d.ts

@@ -0,0 +1,10 @@
+import { SDKSupportedBrowserAutomationFramework, SDKSupportedLanguage, SDKSupportedTestingFramework } from "../types.js";
+import { PercyInstructions } from "./types.js";
+/**
+ * Retrieves Percy-specific instructions for a given language and framework.
+ */
+export declare function getPercyInstructions(language: SDKSupportedLanguage, automationFramework: SDKSupportedBrowserAutomationFramework, testingFramework: SDKSupportedTestingFramework): PercyInstructions | null;
+/**
+ * Formats the retrieved Percy instructions into a user-friendly string.
+ */
+export declare function formatPercyInstructions(instructions: PercyInstructions): string;

package/dist/tools/sdk-utils/{percy-bstack → percy}/instructions.js

@@ -1,5 +1,7 @@
-import { PERCY_INSTRUCTIONS } from "./frameworks.js";
-// Retrieves Percy-specific instructions for a given language and framework
+import { PERCY_INSTRUCTIONS } from "./constants.js";
+/**
+ * Retrieves Percy-specific instructions for a given language and framework.
+ */
 export function getPercyInstructions(language, automationFramework, testingFramework) {
     const langConfig = PERCY_INSTRUCTIONS[language];
     if (!langConfig) {
@@ -15,10 +17,12 @@ export function getPercyInstructions(language, automationFramework, testingFrame
     }
     return percyInstructions;
 }
-// Formats the retrieved Percy instructions into a user-friendly string
+/**
+ * Formats the retrieved Percy instructions into a user-friendly string.
+ */
 export function formatPercyInstructions(instructions) {
-    return `---STEP--- Percy Visual Testing Setup
+    return `\n\n## Percy Visual Testing Setup
 To enable visual testing with Percy, you need to make the following changes to your project configuration and test scripts.
-${instructions.instructions}
+${instructions.script_updates}
 `;
 }

package/dist/tools/sdk-utils/percy/types.d.ts

@@ -0,0 +1,5 @@
+import { SDKSupportedBrowserAutomationFramework, SDKSupportedLanguage, SDKSupportedTestingFramework } from "../types.js";
+export interface PercyInstructions {
+    script_updates: string;
+}
+export type PercyConfigMapping = Partial<Record<SDKSupportedLanguage, Partial<Record<SDKSupportedBrowserAutomationFramework, Partial<Record<SDKSupportedTestingFramework, PercyInstructions>>>>>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "1.2.2-beta.1",
+  "version": "1.2.3-beta.1",
   "description": "BrowserStack's Official MCP Server",
   "main": "dist/index.js",
   "repository": {

package/dist/tools/add-percy-snapshots.d.ts

@@ -1,5 +0,0 @@
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-export declare function updateTestsWithPercyCommands(args: {
-    uuid: string;
-    index: number;
-}): Promise<CallToolResult>;

package/dist/tools/add-percy-snapshots.js

@@ -1,17 +0,0 @@
-import { testFilePathsMap } from "../lib/inmemory-store.js";
-import { updateFileAndStep } from "./percy-snapshot-utils/utils.js";
-import { percyWebSetupInstructions } from "../tools/sdk-utils/percy-web/handler.js";
-export async function updateTestsWithPercyCommands(args) {
-    const { uuid, index } = args;
-    const filePaths = testFilePathsMap.get(uuid);
-    if (!filePaths) {
-        throw new Error(`No test files found in memory for UUID: ${uuid}`);
-    }
-    if (index < 0 || index >= filePaths.length) {
-        throw new Error(`Invalid index: ${index}. There are ${filePaths.length} files for UUID: ${uuid}`);
-    }
-    const result = await updateFileAndStep(filePaths[index], index, filePaths.length, percyWebSetupInstructions);
-    return {
-        content: result,
-    };
-}

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

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

package/dist/tools/list-test-files.d.ts

@@ -1,2 +0,0 @@
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-export declare function addListTestFiles(args: any): Promise<CallToolResult>;

package/dist/tools/list-test-files.js

@@ -1,33 +0,0 @@
-import { listTestFiles } from "./percy-snapshot-utils/detect-test-files.js";
-import { testFilePathsMap } from "../lib/inmemory-store.js";
-import crypto from "crypto";
-export async function addListTestFiles(args) {
-    const { dirs, language, framework } = args;
-    let testFiles = [];
-    for (const dir of dirs) {
-        const files = await listTestFiles({
-            language,
-            framework,
-            baseDir: dir,
-        });
-        testFiles = testFiles.concat(files);
-    }
-    if (testFiles.length === 0) {
-        throw new Error("No test files found");
-    }
-    // Generate a UUID and store the test files in memory
-    const uuid = crypto.randomUUID();
-    testFilePathsMap.set(uuid, testFiles);
-    return {
-        content: [
-            {
-                type: "text",
-                text: `The Test files are stored in memory with id ${uuid} and the total number of tests files found is ${testFiles.length}. You can use this UUID to retrieve the tests file paths later.`,
-            },
-            {
-                type: "text",
-                text: `You can now use the tool addPercySnapshotCommands to update the test file with Percy commands for visual testing with the UUID ${uuid}`,
-            },
-        ],
-    };
-}

package/dist/tools/percy-sdk.d.ts

@@ -1,4 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { BrowserStackConfig } from "../lib/types.js";
-export declare function registerPercyTools(server: McpServer, config: BrowserStackConfig): Record<string, any>;
-export default registerPercyTools;

package/dist/tools/percy-sdk.js

@@ -1,88 +0,0 @@
-import { SetUpPercyParamsShape } from "./sdk-utils/common/schema.js";
-import { updateTestsWithPercyCommands } from "./add-percy-snapshots.js";
-import { addListTestFiles } from "./list-test-files.js";
-import { trackMCP } from "../index.js";
-import { setUpPercyHandler, setUpSimulatePercyChangeHandler, } from "./sdk-utils/handler.js";
-import { SETUP_PERCY_DESCRIPTION, SIMULATE_PERCY_CHANGE_DESCRIPTION, LIST_TEST_FILES_DESCRIPTION, PERCY_SNAPSHOT_COMMANDS_DESCRIPTION, } from "./sdk-utils/common/constants.js";
-import { ListTestFilesParamsShape, UpdateTestFileWithInstructionsParams, } from "./percy-snapshot-utils/constants.js";
-export function registerPercyTools(server, config) {
-    const tools = {};
-    // Register setupPercyVisualTesting
-    tools.setupPercyVisualTesting = server.tool("setupPercyVisualTesting", SETUP_PERCY_DESCRIPTION, SetUpPercyParamsShape, async (args) => {
-        try {
-            trackMCP("setupPercyVisualTesting", server.server.getClientVersion(), config);
-            return setUpPercyHandler(args, config);
-        }
-        catch (error) {
-            trackMCP("setupPercyVisualTesting", server.server.getClientVersion(), error, config);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: error instanceof Error ? error.message : String(error),
-                    },
-                ],
-                isError: true,
-            };
-        }
-    });
-    // Register simulatePercyChange
-    tools.simulatePercyChange = server.tool("simulatePercyChange", SIMULATE_PERCY_CHANGE_DESCRIPTION, SetUpPercyParamsShape, async (args) => {
-        try {
-            trackMCP("simulatePercyChange", server.server.getClientVersion(), config);
-            return setUpSimulatePercyChangeHandler(args, config);
-        }
-        catch (error) {
-            trackMCP("simulatePercyChange", server.server.getClientVersion(), error, config);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: error instanceof Error ? error.message : String(error),
-                    },
-                ],
-                isError: true,
-            };
-        }
-    });
-    // Register addPercySnapshotCommands
-    tools.addPercySnapshotCommands = server.tool("addPercySnapshotCommands", PERCY_SNAPSHOT_COMMANDS_DESCRIPTION, UpdateTestFileWithInstructionsParams, async (args) => {
-        try {
-            trackMCP("addPercySnapshotCommands", server.server.getClientVersion(), config);
-            return await updateTestsWithPercyCommands(args);
-        }
-        catch (error) {
-            trackMCP("addPercySnapshotCommands", server.server.getClientVersion(), error, config);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: error instanceof Error ? error.message : String(error),
-                    },
-                ],
-                isError: true,
-            };
-        }
-    });
-    // Register listTestFiles
-    tools.listTestFiles = server.tool("listTestFiles", LIST_TEST_FILES_DESCRIPTION, ListTestFilesParamsShape, async (args) => {
-        try {
-            trackMCP("listTestFiles", server.server.getClientVersion(), config);
-            return addListTestFiles(args);
-        }
-        catch (error) {
-            trackMCP("listTestFiles", server.server.getClientVersion(), error, config);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: error instanceof Error ? error.message : String(error),
-                    },
-                ],
-                isError: true,
-            };
-        }
-    });
-    return tools;
-}
-export default registerPercyTools;

package/dist/tools/percy-snapshot-utils/constants.d.ts

@@ -1,16 +0,0 @@
-import { z } from "zod";
-import { SDKSupportedLanguage } from "../sdk-utils/common/types.js";
-import { DetectionConfig } from "./types.js";
-export declare const UpdateTestFileWithInstructionsParams: {
-    uuid: z.ZodString;
-    index: z.ZodNumber;
-};
-export declare const ListTestFilesParamsShape: {
-    dirs: z.ZodArray<z.ZodString, "many">;
-    language: z.ZodEnum<[string, ...string[]]>;
-    framework: z.ZodEnum<[string, ...string[]]>;
-};
-export declare const TEST_FILE_DETECTION: Record<SDKSupportedLanguage, DetectionConfig>;
-export declare const EXCLUDED_DIRS: Set<string>;
-export declare const backendIndicators: RegExp[];
-export declare const strongUIIndicators: RegExp[];