@browserstack/mcp-server 1.1.7 → 1.1.9

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

@@ -13,16 +13,15 @@ export const getInstructionsForProjectConfiguration = (detectedBrowserAutomation
     }
     return configuration[detectedBrowserAutomationFramework][detectedTestingFramework].instructions;
 };
-export function generateBrowserStackYMLInstructions(desiredPlatforms) {
-    return `
-      Create a browserstack.yml file in the project root. The file should be in the following format:
-
-      \`\`\`yaml
+export function generateBrowserStackYMLInstructions(desiredPlatforms, enablePercy = false) {
+    let ymlContent = `
 # ======================
 # BrowserStack Reporting
 # ======================
-projectName: BrowserStack MCP Runs
-build: mcp-run
+# 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
 
 # =======================================
 # Platforms (Browsers / Devices to test)
@@ -47,13 +46,52 @@ platforms:
 # 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
-testObservability: true
+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.js

@@ -0,0 +1,176 @@
+const javaSeleniumInstructions = `
+Import the BrowserStack Percy SDK in your test script:
+Add the Percy import to your test file.
+
+---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.
+
+Here's an example:
+
+\`\`\`java
+// ...imports
+import com.browserstack.PercySDK;
+
+public class YourTestClass extends YourBaseTest {
+    @Test
+    public void test() throws Exception {
+         // your test logic
+         // ...
+         
+         // Capture a Percy screenshot
+         PercySDK.screenshot(driver, "My Screenshot Name");
+         
+         // ...
+         // more test logic
+    }
+}
+\`\`\`
+`;
+export const nodejsSeleniumInstructions = `
+Import the BrowserStack Percy SDK in your test script:
+Add the Percy import to your test file.
+
+---STEP---
+
+Add screenshot capture method at required points:
+Use the \`percy.snapshot(driver, name)\` method at points in your test script where you want to capture screenshots.
+
+\`\`\`javascript
+const { percy } = require('browserstack-node-sdk');
+describe("sample Test", () => {
+  // ... other imports and setup
+  
+  test("my test", async () => {
+    // ....
+    await percy.snapshot(driver, "My Snapshot")
+    // ....
+  });
+})
+\`\`\`
+`;
+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 \`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
+// in wdio.conf.js
+
+exports.config = {
+  // ... other configs
+  services: [
+    [
+      'browserstack',
+      { 
+        // ... other service options
+        percy: true,
+        percyCaptureMode: 'auto' // or 'manual', 'testcase', etc.
+      },
+    ],
+  ],
+
+  commonCapabilities: {
+    'bstack:options': {
+      projectName: "My Percy Project", // This is required for Percy
+      // ... other common capabilities
+    }
+  },
+  // ... rest of your config
+};
+\`\`\`
+
+---STEP---
+
+Manually Capturing Screenshots (Optional):
+If you set \`percyCaptureMode: 'manual'\` or want to take extra screenshots in \`auto\` mode, you need to add screenshot commands to your tests.
+
+First, install \`browserstack-node-sdk\`:
+\`\`\`bash
+npm install browserstack-node-sdk
+\`\`\`
+
+Then, in your test script, import \`percy\` and use it to take a snapshot:
+\`\`\`javascript
+// your_test_file.js
+const { percy } = require('browserstack-node-sdk');
+
+describe("My WebdriverIO Test", () => {
+  it("should take a percy snapshot", async () => {
+    // ... your test logic (e.g., browser.url('https://example.com'))
+    
+    // Capture a Percy screenshot
+    await percy.screenshot(driver, "My Snapshot Name");
+    
+    // ... more test logic
+  });
+});
+\`\`\`
+`;
+const csharpSeleniumInstructions = `
+Import the BrowserStack Percy SDK in your test script:
+Add the Percy import to your test file.
+
+---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.
+
+Here's an example:
+
+\`\`\`csharp
+using BrowserStackSDK.Percy;
+using NUnit.Framework;
+
+namespace Tests;
+
+public class MyTest
+{
+    [Test]
+    public void SampleTest()
+    {
+        // your test logic
+        // ...
+        
+        // Capture a Percy screenshot
+        PercySDK.Screenshot(driver, "Screenshot name");
+        
+        // ...
+        // more test logic
+    }
+}
+\`\`\`
+`;
+export const PERCY_INSTRUCTIONS = {
+    java: {
+        selenium: {
+            testng: { script_updates: javaSeleniumInstructions },
+            cucumber: { script_updates: javaSeleniumInstructions },
+            junit4: { script_updates: javaSeleniumInstructions },
+            junit5: { 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.js

@@ -0,0 +1,28 @@
+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) {
+        return null;
+    }
+    const frameworkConfig = langConfig[automationFramework];
+    if (!frameworkConfig) {
+        return null;
+    }
+    const percyInstructions = frameworkConfig[testingFramework];
+    if (!percyInstructions) {
+        return null;
+    }
+    return percyInstructions;
+}
+/**
+ * Formats the retrieved Percy instructions into a user-friendly string.
+ */
+export function formatPercyInstructions(instructions) {
+    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.script_updates}
+`;
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -1 +1,35 @@
-export {};
+export var SDKSupportedLanguageEnum;
+(function (SDKSupportedLanguageEnum) {
+    SDKSupportedLanguageEnum["nodejs"] = "nodejs";
+    SDKSupportedLanguageEnum["python"] = "python";
+    SDKSupportedLanguageEnum["java"] = "java";
+    SDKSupportedLanguageEnum["csharp"] = "csharp";
+})(SDKSupportedLanguageEnum || (SDKSupportedLanguageEnum = {}));
+export var SDKSupportedBrowserAutomationFrameworkEnum;
+(function (SDKSupportedBrowserAutomationFrameworkEnum) {
+    SDKSupportedBrowserAutomationFrameworkEnum["playwright"] = "playwright";
+    SDKSupportedBrowserAutomationFrameworkEnum["selenium"] = "selenium";
+    SDKSupportedBrowserAutomationFrameworkEnum["cypress"] = "cypress";
+})(SDKSupportedBrowserAutomationFrameworkEnum || (SDKSupportedBrowserAutomationFrameworkEnum = {}));
+export var SDKSupportedTestingFrameworkEnum;
+(function (SDKSupportedTestingFrameworkEnum) {
+    SDKSupportedTestingFrameworkEnum["jest"] = "jest";
+    SDKSupportedTestingFrameworkEnum["codeceptjs"] = "codeceptjs";
+    SDKSupportedTestingFrameworkEnum["playwright"] = "playwright";
+    SDKSupportedTestingFrameworkEnum["pytest"] = "pytest";
+    SDKSupportedTestingFrameworkEnum["robot"] = "robot";
+    SDKSupportedTestingFrameworkEnum["behave"] = "behave";
+    SDKSupportedTestingFrameworkEnum["cucumber"] = "cucumber";
+    SDKSupportedTestingFrameworkEnum["nightwatch"] = "nightwatch";
+    SDKSupportedTestingFrameworkEnum["webdriverio"] = "webdriverio";
+    SDKSupportedTestingFrameworkEnum["mocha"] = "mocha";
+    SDKSupportedTestingFrameworkEnum["junit4"] = "junit4";
+    SDKSupportedTestingFrameworkEnum["junit5"] = "junit5";
+    SDKSupportedTestingFrameworkEnum["testng"] = "testng";
+    SDKSupportedTestingFrameworkEnum["cypress"] = "cypress";
+    SDKSupportedTestingFrameworkEnum["nunit"] = "nunit";
+    SDKSupportedTestingFrameworkEnum["mstest"] = "mstest";
+    SDKSupportedTestingFrameworkEnum["xunit"] = "xunit";
+    SDKSupportedTestingFrameworkEnum["specflow"] = "specflow";
+    SDKSupportedTestingFrameworkEnum["reqnroll"] = "reqnroll";
+})(SDKSupportedTestingFrameworkEnum || (SDKSupportedTestingFrameworkEnum = {}));

package/package.json

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