runTestsOnBrowserStack
Generate setup instructions to run tests on BrowserStack based on the automation framework, testing framework, programming language, and desired platforms in your project.
Instructions
Use this tool to get instructions for running tests on BrowserStack.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| desiredPlatforms | Yes | The platforms the user wants to test on. Always ask this to the user, do not try to infer this. | |
| detectedBrowserAutomationFramework | Yes | The automation framework configured in the project. Example: 'playwright', 'selenium' | |
| detectedLanguage | Yes | The programming language used in the project. Example: 'nodejs', 'python' | |
| detectedTestingFramework | Yes | The testing framework used in the project. Example: 'jest', 'pytest' |
Implementation Reference
- src/tools/bstack-sdk.ts:9-34 (registration)Registers the BrowserStack tool 'setupBrowserStackAutomateTests' which internally tracks and calls 'runTestsOnBrowserStackHandler' as the tool logic.export function registerRunBrowserStackTestsTool( server: McpServer, config: BrowserStackConfig, ) { const tools: Record<string, any> = {}; tools.setupBrowserStackAutomateTests = server.tool( "setupBrowserStackAutomateTests", RUN_ON_BROWSERSTACK_DESCRIPTION, RunTestsOnBrowserStackParamsShape, async (args) => { try { trackMCP( "runTestsOnBrowserStack", server.server.getClientVersion()!, config, ); return await runTestsOnBrowserStackHandler(args, config); } catch (error) { return handleMCPError("runTestsOnBrowserStack", server, config, error); } }, ); return tools; }
- src/tools/sdk-utils/handler.ts:31-38 (handler)The primary handler function named runTestsOnBrowserStackHandler. It parses the raw input using the schema and delegates to the core BrowserStack SDK implementation.export async function runTestsOnBrowserStackHandler( rawInput: unknown, config: BrowserStackConfig, ): Promise<CallToolResult> { const input = RunTestsOnBrowserStackSchema.parse(rawInput); const result = await runBstackSDKOnly(input, config); return await formatToolResult(result); }
- Core handler logic (runBstackSDKOnly) that implements the tool by generating step-by-step instructions for BrowserStack SDK setup, device validation, framework-specific configs, and browserstack.yml generation.export async function runBstackSDKOnly( input: RunTestsOnBrowserStackInput, config: BrowserStackConfig, isPercyAutomate = false, ): Promise<RunTestsInstructionResult> { const steps: RunTestsStep[] = []; const authString = getBrowserStackAuth(config); const [username, accessKey] = authString.split(":"); const tupleTargets: Array<Array<string>> = input.devices?.map((device) => { const platform = device.platform.toLowerCase(); if (platform === "windows" || platform === "macos") { // Desktop: ["platform", "osVersion", "browser", "browserVersion"] return [ platform, device.osVersion || "latest", device.browser || "", device.browserVersion || "latest", ]; } else { // Mobile: ["platform", "deviceName", "osVersion", "browser"] return [ platform, device.deviceName || "", device.osVersion || "latest", device.browser || "", ]; } }) || []; 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" ) { const frameworkInstructions = getInstructionsForProjectConfiguration( input.detectedBrowserAutomationFramework as SDKSupportedBrowserAutomationFramework, input.detectedTestingFramework as SDKSupportedTestingFramework, input.detectedLanguage as SDKSupportedLanguage, username, accessKey, ); if (frameworkInstructions) { if (frameworkInstructions.setup) { steps.push({ type: "instruction", title: "Framework-Specific Setup", content: frameworkInstructions.setup, }); } if (frameworkInstructions.run && !isPercyAutomate) { steps.push({ type: "instruction", title: "Run the tests", content: frameworkInstructions.run, }); } } return { steps, requiresPercy: false, missingDependencies: [], }; } // Default flow using browserstack.yml const sdkSetupCommand = getSDKPrefixCommand( input.detectedLanguage as SDKSupportedLanguage, input.detectedTestingFramework as SDKSupportedTestingFramework, username, accessKey, ); if (sdkSetupCommand) { steps.push({ type: "instruction", title: "Install BrowserStack SDK", content: sdkSetupCommand, }); } const frameworkInstructions = getInstructionsForProjectConfiguration( input.detectedBrowserAutomationFramework as SDKSupportedBrowserAutomationFramework, input.detectedTestingFramework as SDKSupportedTestingFramework, input.detectedLanguage as SDKSupportedLanguage, username, accessKey, ); if (frameworkInstructions) { if (frameworkInstructions.setup) { steps.push({ type: "instruction", title: "Framework-Specific Setup", content: frameworkInstructions.setup, }); } } const ymlInstructions = generateBrowserStackYMLInstructions( { validatedEnvironments, enablePercy: false, projectName: input.projectName, }, config, ); if (ymlInstructions) { steps.push({ type: "instruction", title: "Configure browserstack.yml", content: ymlInstructions, }); } if (frameworkInstructions) { if (frameworkInstructions.run && !isPercyAutomate) { steps.push({ type: "instruction", title: "Run the tests", content: frameworkInstructions.run, }); } } return { steps, requiresPercy: false, missingDependencies: [], }; }
- Zod schema definitions for RunTestsOnBrowserStackParamsShape, RunTestsOnBrowserStackSchema, and related types used for input validation in the tool.export const RunTestsOnBrowserStackParamsShape = { projectName: z .string() .describe("A single name for your project to organize all your tests."), detectedLanguage: z.nativeEnum(SDKSupportedLanguageEnum), detectedBrowserAutomationFramework: z.nativeEnum( SDKSupportedBrowserAutomationFrameworkEnum, ), detectedTestingFramework: z.nativeEnum(SDKSupportedTestingFrameworkEnum), devices: z .array(DeviceSchema) .max(3) .default([]) .describe( "Device objects array. Use the object format directly - no transformation needed. Add only when user explicitly requests devices. Examples: [{ platform: 'windows', osVersion: '11', browser: 'chrome', browserVersion: 'latest' }] or [{ platform: 'android', deviceName: 'Samsung Galaxy S24', osVersion: '14', browser: 'chrome' }].", ), }; export const SetUpPercySchema = z.object(SetUpPercyParamsShape); export const RunTestsOnBrowserStackSchema = z.object( RunTestsOnBrowserStackParamsShape, ); export type SetUpPercyInput = z.infer<typeof SetUpPercySchema>; export type RunTestsOnBrowserStackInput = z.infer< typeof RunTestsOnBrowserStackSchema >;