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

package/dist/tools/bstack-sdk.js

@@ -1,128 +1,11 @@
-import { z } from "zod";
-import { trackMCP } from "../lib/instrumentation.js";
-import { getSDKPrefixCommand } from "./sdk-utils/commands.js";
-import { SDKSupportedLanguageEnum, SDKSupportedBrowserAutomationFrameworkEnum, SDKSupportedTestingFrameworkEnum, } from "./sdk-utils/types.js";
-import { generateBrowserStackYMLInstructions, getInstructionsForProjectConfiguration, formatInstructionsWithNumbers, } from "./sdk-utils/instructions.js";
-import { formatPercyInstructions, getPercyInstructions, } from "./sdk-utils/percy/instructions.js";
-import { getBrowserStackAuth } from "../lib/get-auth.js";
-/**
- * BrowserStack SDK hooks into your test framework to seamlessly run tests on BrowserStack.
- * This tool gives instructions to setup a browserstack.yml file in the project root and installs the necessary dependencies.
- */
-export async function bootstrapProjectWithSDK({ detectedBrowserAutomationFramework, detectedTestingFramework, detectedLanguage, desiredPlatforms, enablePercy, config, }) {
-    // Get credentials from config
-    const authString = getBrowserStackAuth(config);
-    const [username, accessKey] = authString.split(":");
-    // Handle frameworks with unique setup instructions that don't use browserstack.yml
-    if (detectedBrowserAutomationFramework === "cypress" ||
-        detectedTestingFramework === "webdriverio") {
-        let combinedInstructions = getInstructionsForProjectConfiguration(detectedBrowserAutomationFramework, detectedTestingFramework, detectedLanguage, username, accessKey);
-        if (enablePercy) {
-            const percyInstructions = getPercyInstructions(detectedLanguage, detectedBrowserAutomationFramework, detectedTestingFramework);
-            if (percyInstructions) {
-                combinedInstructions +=
-                    "\n\n" + formatPercyInstructions(percyInstructions);
-            }
-            else {
-                throw new Error(`Percy is currently not supported through MCP for ${detectedLanguage} with ${detectedTestingFramework}. If you want to run the test cases without Percy, disable Percy and run it again.`);
-            }
-        }
-        // Apply consistent formatting for all configurations
-        return formatFinalInstructions(combinedInstructions);
-    }
-    // Handle default flow using browserstack.yml
-    const sdkSetupCommand = getSDKPrefixCommand(detectedLanguage, detectedTestingFramework, username, accessKey);
-    const ymlInstructions = generateBrowserStackYMLInstructions(desiredPlatforms, enablePercy);
-    const instructionsForProjectConfiguration = getInstructionsForProjectConfiguration(detectedBrowserAutomationFramework, detectedTestingFramework, detectedLanguage, username, accessKey);
-    let combinedInstructions = "";
-    // Step 1: Add SDK setup command
-    if (sdkSetupCommand) {
-        combinedInstructions += sdkSetupCommand;
-    }
-    // Step 2: Add browserstack.yml setup
-    if (ymlInstructions) {
-        combinedInstructions += "\n\n---STEP---\n" + ymlInstructions;
-    }
-    // Step 3: Add language/framework-specific setup
-    if (instructionsForProjectConfiguration) {
-        combinedInstructions += "\n\n" + instructionsForProjectConfiguration;
-    }
-    // Step 4: Add Percy setup if applicable
-    if (enablePercy) {
-        const percyInstructions = getPercyInstructions(detectedLanguage, detectedBrowserAutomationFramework, detectedTestingFramework);
-        if (percyInstructions) {
-            combinedInstructions +=
-                "\n\n" + formatPercyInstructions(percyInstructions);
-        }
-        else {
-            throw new Error(`Percy is currently not supported through MCP for ${detectedLanguage} with ${detectedTestingFramework}. If you want to run the test cases without Percy, disable Percy and run it again.`);
-        }
-    }
-    // Apply consistent formatting for all configurations
-    return formatFinalInstructions(combinedInstructions);
-}
-// Helper function to apply consistent formatting to all instruction types
-function formatFinalInstructions(combinedInstructions) {
-    const fullInstructions = `⚠️ IMPORTANT: DO NOT SKIP ANY STEP
-  All the setup steps described in this file MUST be executed regardless of any existing configuration or setup.
-  This ensures proper BrowserStack SDK setup.
-
-  ${formatInstructionsWithNumbers(combinedInstructions)}`;
-    return {
-        content: [
-            {
-                type: "text",
-                text: fullInstructions,
-                isError: false,
-            },
-        ],
-    };
-}
-export default function addSDKTools(server, config) {
+import { RunTestsOnBrowserStackParamsShape } from "./sdk-utils/common/schema.js";
+import { runTestsOnBrowserStackHandler } from "./sdk-utils/handler.js";
+import { RUN_ON_BROWSERSTACK_DESCRIPTION } from "./sdk-utils/common/constants.js";
+export function registerRunBrowserStackTestsTool(server, config) {
     const tools = {};
-    tools.setupBrowserStackAutomateTests = server.tool("setupBrowserStackAutomateTests", "Set up and run automated web-based tests on BrowserStack using the BrowserStack SDK. Use for functional or integration tests on BrowserStack, with optional Percy visual testing for supported frameworks. Example prompts: run this test on browserstack; run this test on browserstack with Percy; set up this project for browserstack with Percy. Integrate BrowserStack SDK into your project", {
-        detectedBrowserAutomationFramework: z
-            .nativeEnum(SDKSupportedBrowserAutomationFrameworkEnum)
-            .describe("The automation framework configured in the project. Example: 'playwright', 'selenium'"),
-        detectedTestingFramework: z
-            .nativeEnum(SDKSupportedTestingFrameworkEnum)
-            .describe("The testing framework used in the project. Be precise with framework selection Example: 'webdriverio', 'jest', 'pytest', 'junit4', 'junit5', 'mocha'"),
-        detectedLanguage: z
-            .nativeEnum(SDKSupportedLanguageEnum)
-            .describe("The programming language used in the project. Example: 'nodejs', 'python', 'java', 'csharp'"),
-        desiredPlatforms: z
-            .array(z.enum(["windows", "macos", "android", "ios"]))
-            .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 {
-            trackMCP("runTestsOnBrowserStack", server.server.getClientVersion(), undefined, config);
-            return await bootstrapProjectWithSDK({
-                detectedBrowserAutomationFramework: args.detectedBrowserAutomationFramework,
-                detectedTestingFramework: args.detectedTestingFramework,
-                detectedLanguage: args.detectedLanguage,
-                desiredPlatforms: args.desiredPlatforms,
-                enablePercy: args.enablePercy,
-                config,
-            });
-        }
-        catch (error) {
-            trackMCP("runTestsOnBrowserStack", server.server.getClientVersion(), error, config);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Failed to bootstrap project with BrowserStack SDK. Error: ${error}. Please open an issue on GitHub if the problem persists`,
-                        isError: true,
-                    },
-                ],
-                isError: true,
-            };
-        }
+    tools.setupBrowserStackAutomateTests = server.tool("setupBrowserStackAutomateTests", RUN_ON_BROWSERSTACK_DESCRIPTION, RunTestsOnBrowserStackParamsShape, async (args) => {
+        return runTestsOnBrowserStackHandler(args, config);
     });
     return tools;
 }
+export default registerRunBrowserStackTestsTool;

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

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

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

@@ -0,0 +1,33 @@
+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

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,88 @@
+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

@@ -0,0 +1,16 @@
+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[];