@browserstack/mcp-server 1.1.9 → 1.2.1

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

@@ -1,8 +1,7 @@
-import config from "../../config.js";
 /**
  * ---------- PYTHON INSTRUCTIONS ----------
  */
-const pythonInstructions = `
+const pythonInstructions = (username, accessKey) => `
 ---STEP---
 
 Install the BrowserStack SDK:
@@ -14,7 +13,7 @@ python3 -m pip install browserstack-sdk
 
 Setup the BrowserStack SDK with your credentials:
 \`\`\`bash
-browserstack-sdk setup --username "${config.browserstackUsername}" --key "${config.browserstackAccessKey}"
+browserstack-sdk setup --username "${username}" --key "${accessKey}"
 \`\`\`
 
 ---STEP---
@@ -24,10 +23,11 @@ Run your tests on BrowserStack:
 browserstack-sdk python <path-to-test-file>
 \`\`\`
 `;
-const generatePythonFrameworkInstructions = (framework) => `
+const generatePythonFrameworkInstructions = (framework) => (username, accessKey) => `
 ---STEP---
 
 Install the BrowserStack SDK:
+
 \`\`\`bash
 python3 -m pip install browserstack-sdk
 \`\`\`
@@ -36,7 +36,7 @@ python3 -m pip install browserstack-sdk
 
 Setup the BrowserStack SDK with framework-specific configuration:
 \`\`\`bash
-browserstack-sdk setup --framework "${framework}" --username "${config.browserstackUsername}" --key "${config.browserstackAccessKey}"
+browserstack-sdk setup --framework "${framework}" --username "${username}" --key "${accessKey}"
 \`\`\`
 
 ---STEP---
@@ -53,7 +53,7 @@ const pytestInstructions = generatePythonFrameworkInstructions("pytest");
  * ---------- JAVA INSTRUCTIONS ----------
  */
 const argsInstruction = '<argLine>-javaagent:"${com.browserstack:browserstack-java-sdk:jar}"</argLine>';
-const javaInstructions = `
+const javaInstructions = (username, accessKey) => `
 ---STEP---
 
 Add the BrowserStack Java SDK dependency to your \`pom.xml\`:
@@ -79,8 +79,8 @@ dependencies {
 
 Export your BrowserStack credentials as environment variables:
 \`\`\`bash
-export BROWSERSTACK_USERNAME=${config.browserstackUsername}
-export BROWSERSTACK_ACCESS_KEY=${config.browserstackAccessKey}
+export BROWSERSTACK_USERNAME=${username}
+export BROWSERSTACK_ACCESS_KEY=${accessKey}
 \`\`\`
 
 ---STEP---
@@ -95,10 +95,66 @@ Or for Gradle:
 gradle clean test
 \`\`\`
 `;
+const serenityInstructions = (username, accessKey) => `
+---STEP---
+
+Set BrowserStack credentials as environment variables:
+For macOS/Linux:
+\`\`\`bash
+export BROWSERSTACK_USERNAME=${username}
+export BROWSERSTACK_ACCESS_KEY=${accessKey}
+\`\`\`
+
+For Windows Command Prompt:
+\`\`\`cmd
+set BROWSERSTACK_USERNAME=${username}
+set BROWSERSTACK_ACCESS_KEY=${accessKey}
+\`\`\`
+
+---STEP---
+
+Add serenity-browserstack dependency in pom.xml:
+Add the following dependency to your pom.xml file and save it:
+\`\`\`xml
+<dependency>
+  <groupId>net.serenity-bdd</groupId>
+  <artifactId>serenity-browserstack</artifactId>
+  <version>3.3.4</version>
+</dependency>
+\`\`\`
+
+---STEP---
+
+Set up serenity.conf file:
+Create or update your serenity.conf file in the project root with the following configuration:
+\`\`\`
+webdriver {
+  driver = remote
+  remote.url = "https://hub.browserstack.com/wd/hub"
+}
+browserstack.user="${username}"
+browserstack.key="${accessKey}"
+\`\`\`
+
+---STEP---
+
+Run your Serenity tests:
+You can continue running your tests as you normally would. For example:
+
+Using Maven:
+\`\`\`bash
+mvn clean verify
+\`\`\`
+
+Using Gradle:
+\`\`\`bash
+gradle clean test
+\`\`\`
+`;
 /**
  * ---------- CSharp INSTRUCTIONS ----------
  */
-const csharpCommonInstructions = `
+const csharpCommonInstructions = (username, accessKey) => `
 ---STEP---
 
 Install BrowserStack TestAdapter NuGet package:
@@ -117,7 +173,7 @@ dotnet build
 
 Set up BrowserStack SDK with your credentials:
 \`\`\`bash
-dotnet browserstack-sdk setup --userName ${config.browserstackUsername} --accessKey ${config.browserstackAccessKey}
+dotnet browserstack-sdk setup --userName ${username} --accessKey ${accessKey}
 \`\`\`
 
 ---STEP---
@@ -160,7 +216,7 @@ Run the tests:
   dotnet test
   \`\`\`
 `;
-const csharpPlaywrightCommonInstructions = `
+const csharpPlaywrightCommonInstructions = (username, accessKey) => `
 ---STEP---
 
 Install BrowserStack TestAdapter NuGet package:
@@ -179,7 +235,7 @@ dotnet build
 
 Set up BrowserStack SDK with your credentials:
 \`\`\`bash
-dotnet browserstack-sdk setup --userName ${config.browserstackUsername} --accessKey ${config.browserstackAccessKey}
+dotnet browserstack-sdk setup --userName ${username} --accessKey ${accessKey}
 \`\`\`
 
 ---STEP---
@@ -238,7 +294,7 @@ Run the tests:
 /**
  * ---------- NODEJS INSTRUCTIONS ----------
  */
-const nodejsInstructions = `
+const nodejsInstructions = (username, accessKey) => `
 ---STEP---
 
 Ensure \`browserstack-node-sdk\` is present in package.json with the latest version:
@@ -259,11 +315,15 @@ Add new scripts to package.json for running tests on BrowserStack:
 
 Export BrowserStack credentials as environment variables:
 Set the following environment variables before running tests.
+\`\`\`bash
+export BROWSERSTACK_USERNAME=${username}
+export BROWSERSTACK_ACCESS_KEY=${accessKey}
+\`\`\`
 `;
 /**
  * ---------- EXPORT CONFIG ----------
  */
-const webdriverioInstructions = `
+const webdriverioInstructions = (username, accessKey) => `
 ---STEP---
 
 Set BrowserStack Credentials:
@@ -271,14 +331,14 @@ Export your BrowserStack username and access key as environment variables.
 
 For macOS/Linux:
 \`\`\`bash
-export BROWSERSTACK_USERNAME= ${config.browserstackUsername}
-export BROWSERSTACK_ACCESS_KEY= ${config.browserstackAccessKey}
+export BROWSERSTACK_USERNAME=${username}
+export BROWSERSTACK_ACCESS_KEY=${accessKey}
 \`\`\`
 
 For Windows PowerShell:
 \`\`\`powershell
-$env:BROWSERSTACK_USERNAME=${config.browserstackUsername}
-$env:BROWSERSTACK_ACCESS_KEY=${config.browserstackAccessKey}
+$env:BROWSERSTACK_USERNAME=${username}
+$env:BROWSERSTACK_ACCESS_KEY=${accessKey}
 \`\`\`
 
 ---STEP---
@@ -368,7 +428,7 @@ exports.config.capabilities.forEach(function (caps) {
 Run your tests:
 You can now run your tests on BrowserStack using your standard WebdriverIO command.
 `;
-const cypressInstructions = `
+const cypressInstructions = (username, accessKey) => `
 ---STEP---
 
 Install the BrowserStack Cypress CLI:
@@ -397,8 +457,8 @@ Open the generated \`browserstack.json\` file and update it with your BrowserSta
 \`\`\`json
 {
   "auth": {
-    "username": "${config.browserstackUsername}",
-    "access_key": "${config.browserstackAccessKey}"
+    "username": "${username}",
+    "access_key": "${accessKey}"
   },
   "browsers": [
     {
@@ -462,6 +522,7 @@ export const SUPPORTED_CONFIGURATIONS = {
             cucumber: { instructions: javaInstructions },
             junit4: { instructions: javaInstructions },
             junit5: { instructions: javaInstructions },
+            serenity: { instructions: serenityInstructions },
         },
     },
     csharp: {

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

@@ -0,0 +1,6 @@
+import { SDKSupportedLanguage } from "./types.js";
+import { SDKSupportedBrowserAutomationFramework } from "./types.js";
+import { SDKSupportedTestingFramework } from "./types.js";
+export declare const getInstructionsForProjectConfiguration: (detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFramework, detectedTestingFramework: SDKSupportedTestingFramework, detectedLanguage: SDKSupportedLanguage, username: string, accessKey: string) => string;
+export declare function generateBrowserStackYMLInstructions(desiredPlatforms: string[], enablePercy?: boolean): string;
+export declare function formatInstructionsWithNumbers(instructionText: string, separator?: string): string;

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

@@ -1,6 +1,6 @@
 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) => {
+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}`);
@@ -11,17 +11,19 @@ export const getInstructionsForProjectConfiguration = (detectedBrowserAutomation
     if (!configuration[detectedBrowserAutomationFramework][detectedTestingFramework]) {
         throw new Error(`BrowserStack MCP Server currently does not support ${detectedTestingFramework} for ${detectedBrowserAutomationFramework} on ${detectedLanguage}, ${errorMessageSuffix}`);
     }
-    return configuration[detectedBrowserAutomationFramework][detectedTestingFramework].instructions;
+    const instructionFunction = configuration[detectedBrowserAutomationFramework][detectedTestingFramework]
+        .instructions;
+    return instructionFunction(username, accessKey);
 };
 export function generateBrowserStackYMLInstructions(desiredPlatforms, enablePercy = false) {
     let ymlContent = `
 # ======================
 # BrowserStack Reporting
 # ======================
-# A single name for your project to organize all your tests. This is required for Percy.
-projectName: BrowserStack SDK Tests
-# A name for the group of tests you are running
-buildName: mcp-run
+# 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)

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/constants.js

@@ -153,6 +153,7 @@ export const PERCY_INSTRUCTIONS = {
             cucumber: { script_updates: javaSeleniumInstructions },
             junit4: { script_updates: javaSeleniumInstructions },
             junit5: { script_updates: javaSeleniumInstructions },
+            serenity: { script_updates: javaSeleniumInstructions },
         },
     },
     csharp: {

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/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/dist/tools/sdk-utils/types.d.ts

@@ -0,0 +1,39 @@
+export declare enum SDKSupportedLanguageEnum {
+    nodejs = "nodejs",
+    python = "python",
+    java = "java",
+    csharp = "csharp"
+}
+export type SDKSupportedLanguage = keyof typeof SDKSupportedLanguageEnum;
+export declare enum SDKSupportedBrowserAutomationFrameworkEnum {
+    playwright = "playwright",
+    selenium = "selenium",
+    cypress = "cypress"
+}
+export type SDKSupportedBrowserAutomationFramework = keyof typeof SDKSupportedBrowserAutomationFrameworkEnum;
+export declare enum SDKSupportedTestingFrameworkEnum {
+    jest = "jest",
+    codeceptjs = "codeceptjs",
+    playwright = "playwright",
+    pytest = "pytest",
+    robot = "robot",
+    behave = "behave",
+    cucumber = "cucumber",
+    nightwatch = "nightwatch",
+    webdriverio = "webdriverio",
+    mocha = "mocha",
+    junit4 = "junit4",
+    junit5 = "junit5",
+    testng = "testng",
+    serenity = "serenity",
+    cypress = "cypress",
+    nunit = "nunit",
+    mstest = "mstest",
+    xunit = "xunit",
+    specflow = "specflow",
+    reqnroll = "reqnroll"
+}
+export type SDKSupportedTestingFramework = keyof typeof SDKSupportedTestingFrameworkEnum;
+export type ConfigMapping = Record<SDKSupportedLanguageEnum, Partial<Record<SDKSupportedBrowserAutomationFrameworkEnum, Partial<Record<SDKSupportedTestingFrameworkEnum, {
+    instructions: (username: string, accessKey: string) => string;
+}>>>>>;

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

@@ -26,6 +26,7 @@ export var SDKSupportedTestingFrameworkEnum;
     SDKSupportedTestingFrameworkEnum["junit4"] = "junit4";
     SDKSupportedTestingFrameworkEnum["junit5"] = "junit5";
     SDKSupportedTestingFrameworkEnum["testng"] = "testng";
+    SDKSupportedTestingFrameworkEnum["serenity"] = "serenity";
     SDKSupportedTestingFrameworkEnum["cypress"] = "cypress";
     SDKSupportedTestingFrameworkEnum["nunit"] = "nunit";
     SDKSupportedTestingFrameworkEnum["mstest"] = "mstest";

package/dist/tools/selfheal-utils/selfheal.d.ts

@@ -0,0 +1,11 @@
+interface SelectorMapping {
+    originalSelector: string;
+    healedSelector: string;
+    context: {
+        before: string;
+        after: string;
+    };
+}
+import { BrowserStackConfig } from "../../lib/types.js";
+export declare function getSelfHealSelectors(sessionId: string, config: BrowserStackConfig): Promise<SelectorMapping[]>;
+export {};

package/dist/tools/selfheal-utils/selfheal.js

@@ -1,17 +1,21 @@
 import { assertOkResponse } from "../../lib/utils.js";
-import config from "../../config.js";
-export async function getSelfHealSelectors(sessionId) {
-    const credentials = `${config.browserstackUsername}:${config.browserstackAccessKey}`;
-    const auth = Buffer.from(credentials).toString("base64");
+import { getBrowserStackAuth } from "../../lib/get-auth.js";
+import { apiClient } from "../../lib/apiClient.js";
+export async function getSelfHealSelectors(sessionId, config) {
+    const authString = getBrowserStackAuth(config);
+    const auth = Buffer.from(authString).toString("base64");
     const url = `https://api.browserstack.com/automate/sessions/${sessionId}/logs`;
-    const response = await fetch(url, {
+    const response = await apiClient.get({
+        url,
         headers: {
             "Content-Type": "application/json",
             Authorization: `Basic ${auth}`,
         },
     });
     await assertOkResponse(response, "session logs");
-    const logText = await response.text();
+    const logText = typeof response.data === "string"
+        ? response.data
+        : JSON.stringify(response.data);
     return extractHealedSelectors(logText);
 }
 function extractHealedSelectors(logText) {

package/dist/tools/selfheal.d.ts

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

package/dist/tools/selfheal.js

@@ -3,9 +3,9 @@ import { getSelfHealSelectors } from "./selfheal-utils/selfheal.js";
 import logger from "../logger.js";
 import { trackMCP } from "../lib/instrumentation.js";
 // Tool function that fetches self-healing selectors
-export async function fetchSelfHealSelectorTool(args) {
+export async function fetchSelfHealSelectorTool(args, config) {
     try {
-        const selectors = await getSelfHealSelectors(args.sessionId);
+        const selectors = await getSelfHealSelectors(args.sessionId, config);
         return {
             content: [
                 {
@@ -22,16 +22,17 @@ export async function fetchSelfHealSelectorTool(args) {
     }
 }
 // Registers the fetchSelfHealSelector tool with the MCP server
-export default function addSelfHealTools(server) {
-    server.tool("fetchSelfHealedSelectors", "Retrieves AI-generated, self-healed selectors for a BrowserStack Automate session to resolve flaky tests caused by dynamic DOM changes.", {
+export default function addSelfHealTools(server, config) {
+    const tools = {};
+    tools.fetchSelfHealedSelectors = server.tool("fetchSelfHealedSelectors", "Retrieves AI-generated, self-healed selectors for a BrowserStack Automate session to resolve flaky tests caused by dynamic DOM changes.", {
         sessionId: z.string().describe("The session ID of the test run"),
     }, async (args) => {
         try {
-            trackMCP("fetchSelfHealedSelectors", server.server.getClientVersion());
-            return await fetchSelfHealSelectorTool(args);
+            trackMCP("fetchSelfHealedSelectors", server.server.getClientVersion(), undefined, config);
+            return await fetchSelfHealSelectorTool(args, config);
         }
         catch (error) {
-            trackMCP("fetchSelfHealedSelectors", server.server.getClientVersion(), error);
+            trackMCP("fetchSelfHealedSelectors", server.server.getClientVersion(), error, config);
             const errorMessage = error instanceof Error ? error.message : "Unknown error";
             return {
                 content: [
@@ -43,4 +44,5 @@ export default function addSelfHealTools(server) {
             };
         }
     });
+    return tools;
 }

package/dist/tools/testmanagement-utils/TCG-utils/api.d.ts

@@ -0,0 +1,34 @@
+import { DefaultFieldMaps, Scenario, CreateTestCasesFromFileArgs } from "./types.js";
+import { BrowserStackConfig } from "../../../lib/types.js";
+/**
+ * Fetch default and custom form fields for a project.
+ */
+export declare function fetchFormFields(projectId: string, config: BrowserStackConfig): Promise<{
+    default_fields: any;
+    custom_fields: any;
+}>;
+/**
+ * Trigger AI-based test case generation for a document.
+ */
+export declare function triggerTestCaseGeneration(document: string, documentId: number, folderId: string, projectId: string, source: string, config: BrowserStackConfig): Promise<string>;
+/**
+ * Initiate a fetch for test-case details; returns the traceRequestId for polling.
+ */
+export declare function fetchTestCaseDetails(documentId: number, folderId: string, projectId: string, testCaseIds: string[], source: string, config: BrowserStackConfig): Promise<string>;
+/**
+ * Poll for a given traceRequestId until all test-case details are returned.
+ */
+export declare function pollTestCaseDetails(traceRequestId: string, config: BrowserStackConfig): Promise<Record<string, any>>;
+/**
+ * Poll for scenarios & testcases, trigger detail fetches, then poll all details in parallel.
+ */
+export declare function pollScenariosTestDetails(args: CreateTestCasesFromFileArgs, traceId: string, context: any, documentId: number, source: string, config: BrowserStackConfig): Promise<Record<string, Scenario>>;
+/**
+ * Bulk-create generated test cases in BrowserStack.
+ */
+export declare function bulkCreateTestCases(scenariosMap: Record<string, Scenario>, projectId: string, folderId: string, fieldMaps: DefaultFieldMaps, booleanFieldId: number | undefined, traceId: string, context: any, documentId: number, config: BrowserStackConfig): Promise<string>;
+export declare function projectIdentifierToId(projectId: string, config: BrowserStackConfig): Promise<string>;
+export declare function testCaseIdentifierToDetails(projectId: string, testCaseIdentifier: string, config: BrowserStackConfig): Promise<{
+    testCaseId: string;
+    folderId: string;
+}>;