diff --git a/.github/workflows/mcp-registry-publish.yml b/.github/workflows/mcp-registry-publish.yml
new file mode 100644
index 00000000..44e2c34f
--- /dev/null
+++ b/.github/workflows/mcp-registry-publish.yml
@@ -0,0 +1,41 @@
+name: Publish to MCP Registry
+
+on:
+ workflow_dispatch:
+ push:
+ tags: ["v*"]
+
+jobs:
+ publish:
+ runs-on: ubuntu-latest
+ permissions:
+ id-token: write
+ contents: read
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v5
+
+ - name: Setup Node.js
+ uses: actions/setup-node@v5
+ with:
+ node-version: "lts/*"
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Run tests
+ run: npm run test --if-present
+
+ - name: Build package
+ run: npm run build --if-present
+
+ - name: Install MCP Publisher
+ run: |
+ curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.1.0/mcp-publisher_1.1.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+
+ - name: Login to MCP Registry
+ run: ./mcp-publisher login github-oidc
+
+ - name: Publish to MCP Registry
+ run: ./mcp-publisher publish
diff --git a/README.md b/README.md
index 8d65f89c..e84d6b2a 100644
--- a/README.md
+++ b/README.md
@@ -35,10 +35,21 @@ Manage, execute, debug tests, and even fix code using plain English prompts.
#### Reduced context switching:
Stay in flow—keep all project context in one place and trigger actions directly from your IDE or LLM.
-## ⚡️ One Click MCP Setup
+## ⚡️ One Click MCP Setup
-[](http://mcp.browserstack.com/one-click-setup?client=vscode) [](http://mcp.browserstack.com/one-click-setup?client=cursor)
+Click on the buttons below to install MCP in your respective IDE:
+
+
+#### Note : Ensure you are using Node version >= `18.0`
+- Check your node version using `node --version`. Recommended version: `v22.15.0` (LTS)
+- To Upgrade Node :
+- 1. On macOS `(Homebrew) - brew update && brew upgrade node or if using (nvm) - nvm install 22.15.0 && nvm use 22.15.0 && nvm alias default 22.15.0`
+- 2. On Windows `(nvm-windows) : nvm install 22.15.0 && nvm use 22.15.0`
+- 👉 Or directly download the Node.js LTS Installer
+
+.
+
## 💡 Usage Examples
### 📱 Manual App Testing
@@ -142,10 +153,15 @@ Generate test cases from PRDs, convert manual tests to low-code automation, and
## 🛠️ Installation
+### 📋 Prerequisites for MCP Setup
+#### Note : Ensure you are using Node version >= `18.0`
+- Check your node version using `node --version`. Recommended version: `v22.15.0` (LTS)
+
### **One Click MCP Setup**
-[](http://mcp.browserstack.com/one-click-setup?client=vscode) [](http://mcp.browserstack.com/one-click-setup?client=cursor)
+Click on the buttons below to install MCP in your respective IDE:
+
### **Alternate ways to Setup MCP server**
@@ -158,7 +174,9 @@ Generate test cases from PRDs, convert manual tests to low-code automation, and
- Once you have an account (and purchased appropriate plan), note down your `username` and `access_key` from [Account Settings](https://www.browserstack.com/accounts/profile/details).
-2. Ensure you are using Node version >= `18.0`. Check your node version using `node --version`. Recommended version: `v22.15.0` (LTS)
+2. #### Note : Ensure you are using Node version >= `18.0`
+ - Check your node version using `node --version`. Recommended version: `v22.15.0` (LTS)
+
3. **Install the MCP Server**
@@ -404,14 +422,14 @@ As of now we support 20 tools.
**Prompt example**
```text
- Take a screenshot of my app on Google Pixel 6 with Android 14 while testing on App Automate. App file path: /Users/xyz/app-debug.apk
+ Take a screenshot of my app on Google Pixel 6 with Android 12 while testing on App Automate. App file path: /Users/xyz/app-debug.apk
```
15. `runAppTestsOnBrowserStack` — Run automated mobile tests (Espresso/XCUITest, etc.) on real devices.
**Prompt example**
```text
- Run Espresso tests from /tests/checkout.zip on Galaxy S21 and Pixel 6 with Android 14. App path is /apps/beta-release.apk under project 'Checkout Flow'
+ Run Espresso tests from /tests/checkout.zip on Galaxy S21 and Pixel 6 with Android 12. App path is /apps/beta-release.apk under project 'Checkout Flow'
```
---
@@ -456,7 +474,79 @@ As of now we support 20 tools.
```text
Upload PRD from /Users/xyz/Desktop/login-flow.pdf and use BrowserStack AI to generate test cases
```
+## 🚀 Remote MCP Server
+
+Remote MCP comes with all the functionalities of an MCP server without the hassles of complex setup or local installation.
+
+### Key benefits:
+
+- ✅ Works seamlessly in enterprise networks without worrying about firewalls or binaries or where local installation is not allowed.
+
+- ✅ Secure OAuth integration – no password sharing or manual credential handling.
+
+### Limitations:
+
+- ❌ No Local Testing support (cannot test apps behind VPNs, firewalls, or localhost). If you have to do Local Testing, you would have to use a BrowserStack Local MCP server.
+- ❌ Latency can be slightly higher, but nothing considerable — you generally won’t notice it in normal use.
+### Installation Steps:
+
+ - On VSCode (Copilot - Agent Mode): `.vscode/mcp.json`:
+
+ - Locate or Create the Configuration File:
+ - In the root directory of your project, look for a folder named .vscode. This folder is usually hidden so you will need to find it as mentioned in the expand.
+ - If this folder doesn't exist, create it.
+ - Inside the .vscode folder, create a new file named mcp.json
+ - To setup Remote BrowserStack MCP instead of local BrowserStack MCP you can add the following JSON content :
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
VISUAL CHANGE
DETECTED!';
+document.body.appendChild(popup);
+\`;
+
+# Insert this just before the EXISTING snapshot command:
+driver.execute_script(popup_script)
+percy_snapshot(self.driver, "Before Adding to Cart") # (Do NOT change the snapshot name, keep existing one)
+\`\`\`
+
+STEP 4: Run a second Percy build with same label and same test command as the baseline.
+- The snapshot names must remain the same as in the baseline.
+- The visual change should now appear in the same snapshot as before.
+- Use the same build command you ran for the baseline.
+
+STEP 5: Compare the two Percy builds to see the detected visual difference.
+
+STEP 6: Now ask user if they want to expand percy for other testcases? If yes, call the "expandPercyVisualTesting" tool to enable complete coverage for the entire project.
+
+CONSTRAINTS:
+- Do NOT run any builds until explicitly instructed in the steps.
+- Do NOT add new snapshot names—only use existing ones.
+- Do NOT add popup injection until the baseline is established.
+- Visual changes must appear in EXISTING snapshots, not new ones.
+
+VALIDATION CHECKPOINTS (before proceeding to the next step):
+- Are you adding only snapshot commands (not running builds)?
+- Are you reusing existing snapshot names (not creating new ones)?
+- Have you established the baseline first (before adding visual changes)
+
+CRITICAL:
+Do NOT run tests separately or create multiple builds during baseline establishment. The goal is to have exactly TWO builds total: (1) baseline build with all original snapshots, (2) modified build with the same tests but visual changes injected.
+`;
+
+export const PERCY_VERIFICATION_REGEX =
+ /\*\*✅ Verification:\*\*\nPlease verify that you have completed all[\s\S]*?double-check each step and ensure all commands executed successfully\./s;
diff --git a/src/tools/sdk-utils/common/device-validator.ts b/src/tools/sdk-utils/common/device-validator.ts
new file mode 100644
index 00000000..d2047b2b
--- /dev/null
+++ b/src/tools/sdk-utils/common/device-validator.ts
@@ -0,0 +1,639 @@
+import {
+ getDevicesAndBrowsers,
+ BrowserStackProducts,
+} from "../../../lib/device-cache.js";
+import { resolveVersion } from "../../../lib/version-resolver.js";
+import { customFuzzySearch } from "../../../lib/fuzzy.js";
+import { SDKSupportedBrowserAutomationFrameworkEnum } from "./types.js";
+
+// ============================================================================
+// SHARED TYPES AND INTERFACES
+// ============================================================================
+
+// Type definitions for better type safety
+export interface DesktopBrowserEntry {
+ os: string;
+ os_version: string;
+ browser: string;
+ browser_version: string;
+}
+
+export interface MobileDeviceEntry {
+ os: "android" | "ios";
+ os_version: string;
+ display_name: string;
+ browsers?: Array<{
+ browser: string;
+ display_name?: string;
+ }>;
+}
+
+export interface ValidatedEnvironment {
+ platform: string;
+ osVersion: string;
+ browser?: string;
+ browserVersion?: string;
+ deviceName?: string;
+ notes?: string;
+}
+
+// Raw data interfaces for API responses
+interface RawDesktopPlatform {
+ os: string;
+ os_version: string;
+ browsers: Array<{
+ browser: string;
+ browser_version: string;
+ }>;
+}
+
+interface RawMobileGroup {
+ os: "android" | "ios";
+ devices: Array<{
+ os_version: string;
+ display_name: string;
+ browser?: string;
+ browsers?: Array<{
+ browser: string;
+ display_name?: string;
+ }>;
+ }>;
+}
+
+interface RawDeviceData {
+ desktop?: RawDesktopPlatform[];
+ mobile?: RawMobileGroup[];
+}
+
+const DEFAULTS = {
+ windows: { browser: "chrome" },
+ macos: { browser: "safari" },
+ android: { device: "Samsung Galaxy S24", browser: "chrome" },
+ ios: { device: "iPhone 15", browser: "safari" },
+} as const;
+
+// Performance optimization: Indexed maps for faster lookups
+interface DesktopIndex {
+ byOS: Map;
+ byOSVersion: Map;
+ byBrowser: Map;
+ nested: Map>>;
+}
+
+interface MobileIndex {
+ byPlatform: Map;
+ byDeviceName: Map;
+ byOSVersion: Map;
+}
+
+// ============================================================================
+// AUTOMATE SECTION (Desktop + Mobile for BrowserStack SDK)
+// ============================================================================
+
+// Helper functions to build device entries and eliminate duplication
+function buildDesktopEntries(
+ automateData: RawDeviceData,
+): DesktopBrowserEntry[] {
+ if (!automateData.desktop) {
+ return [];
+ }
+
+ return automateData.desktop.flatMap((platform: RawDesktopPlatform) =>
+ platform.browsers.map((browser) => ({
+ os: platform.os,
+ os_version: platform.os_version,
+ browser: browser.browser,
+ browser_version: browser.browser_version,
+ })),
+ );
+}
+
+function buildMobileEntries(
+ appAutomateData: RawDeviceData,
+ platform: "android" | "ios",
+): MobileDeviceEntry[] {
+ if (!appAutomateData.mobile) {
+ return [];
+ }
+
+ return appAutomateData.mobile
+ .filter((group: RawMobileGroup) => group.os === platform)
+ .flatMap((group: RawMobileGroup) =>
+ group.devices.map((device) => ({
+ os: group.os,
+ os_version: device.os_version,
+ display_name: device.display_name,
+ browsers: device.browsers || [
+ {
+ browser:
+ device.browser || (platform === "android" ? "chrome" : "safari"),
+ },
+ ],
+ })),
+ );
+}
+
+// Performance optimization: Create indexed maps for faster lookups
+function createDesktopIndex(entries: DesktopBrowserEntry[]): DesktopIndex {
+ const byOS = new Map();
+ const byOSVersion = new Map();
+ const byBrowser = new Map();
+ const nested = new Map<
+ string,
+ Map>
+ >();
+
+ for (const entry of entries) {
+ // Index by OS
+ if (!byOS.has(entry.os)) {
+ byOS.set(entry.os, []);
+ }
+ byOS.get(entry.os)!.push(entry);
+
+ // Index by OS version
+ if (!byOSVersion.has(entry.os_version)) {
+ byOSVersion.set(entry.os_version, []);
+ }
+ byOSVersion.get(entry.os_version)!.push(entry);
+
+ // Index by browser
+ if (!byBrowser.has(entry.browser)) {
+ byBrowser.set(entry.browser, []);
+ }
+ byBrowser.get(entry.browser)!.push(entry);
+
+ // Build nested index: Map>>
+ if (!nested.has(entry.os)) {
+ nested.set(entry.os, new Map());
+ }
+ const osMap = nested.get(entry.os)!;
+
+ if (!osMap.has(entry.os_version)) {
+ osMap.set(entry.os_version, new Map());
+ }
+ const osVersionMap = osMap.get(entry.os_version)!;
+
+ if (!osVersionMap.has(entry.browser)) {
+ osVersionMap.set(entry.browser, []);
+ }
+ osVersionMap.get(entry.browser)!.push(entry);
+ }
+
+ return { byOS, byOSVersion, byBrowser, nested };
+}
+
+function createMobileIndex(entries: MobileDeviceEntry[]): MobileIndex {
+ const byPlatform = new Map();
+ const byDeviceName = new Map();
+ const byOSVersion = new Map();
+
+ for (const entry of entries) {
+ // Index by platform
+ if (!byPlatform.has(entry.os)) {
+ byPlatform.set(entry.os, []);
+ }
+ byPlatform.get(entry.os)!.push(entry);
+
+ // Index by device name (case-insensitive)
+ const deviceKey = entry.display_name.toLowerCase();
+ if (!byDeviceName.has(deviceKey)) {
+ byDeviceName.set(deviceKey, []);
+ }
+ byDeviceName.get(deviceKey)!.push(entry);
+
+ // Index by OS version
+ if (!byOSVersion.has(entry.os_version)) {
+ byOSVersion.set(entry.os_version, []);
+ }
+ byOSVersion.get(entry.os_version)!.push(entry);
+ }
+
+ return { byPlatform, byDeviceName, byOSVersion };
+}
+
+export async function validateDevices(
+ devices: Array>,
+ framework?: string,
+): Promise {
+ const validatedEnvironments: ValidatedEnvironment[] = [];
+
+ if (!devices || devices.length === 0) {
+ // Use centralized default fallback
+ return [
+ {
+ platform: "windows",
+ osVersion: "11",
+ browser: DEFAULTS.windows.browser,
+ browserVersion: "latest",
+ },
+ ];
+ }
+
+ // Determine what data we need to fetch
+ const needsDesktop = devices.some((env) =>
+ ["windows", "macos"].includes((env[0] || "").toLowerCase()),
+ );
+ const needsMobile = devices.some((env) =>
+ ["android", "ios"].includes((env[0] || "").toLowerCase()),
+ );
+
+ // Fetch data using framework-specific endpoint for both desktop and mobile
+ let deviceData: RawDeviceData | null = null;
+
+ try {
+ if (needsDesktop || needsMobile) {
+ if (framework === SDKSupportedBrowserAutomationFrameworkEnum.playwright) {
+ deviceData = (await getDevicesAndBrowsers(
+ BrowserStackProducts.PLAYWRIGHT_AUTOMATE,
+ )) as RawDeviceData;
+ } else {
+ deviceData = (await getDevicesAndBrowsers(
+ BrowserStackProducts.SELENIUM_AUTOMATE,
+ )) as RawDeviceData;
+ }
+ }
+ } catch (error) {
+ throw new Error(
+ `Failed to fetch device data: ${error instanceof Error ? error.message : String(error)}`,
+ );
+ }
+
+ // Preprocess data into indexed maps for better performance
+ let desktopIndex: DesktopIndex | null = null;
+ let androidIndex: MobileIndex | null = null;
+ let iosIndex: MobileIndex | null = null;
+
+ if (needsDesktop && deviceData) {
+ const desktopEntries = buildDesktopEntries(deviceData);
+ desktopIndex = createDesktopIndex(desktopEntries);
+ }
+
+ if (needsMobile && deviceData) {
+ const androidEntries = buildMobileEntries(deviceData, "android");
+ const iosEntries = buildMobileEntries(deviceData, "ios");
+ androidIndex = createMobileIndex(androidEntries);
+ iosIndex = createMobileIndex(iosEntries);
+ }
+
+ for (const env of devices) {
+ const discriminator = (env[0] || "").toLowerCase();
+ let validatedEnv: ValidatedEnvironment;
+
+ if (discriminator === "windows") {
+ validatedEnv = validateDesktopEnvironment(
+ env,
+ desktopIndex!,
+ "windows",
+ DEFAULTS.windows.browser,
+ );
+ } else if (discriminator === "macos") {
+ validatedEnv = validateDesktopEnvironment(
+ env,
+ desktopIndex!,
+ "macos",
+ DEFAULTS.macos.browser,
+ );
+ } else if (discriminator === "android") {
+ validatedEnv = validateMobileEnvironment(
+ env,
+ androidIndex!,
+ "android",
+ DEFAULTS.android.device,
+ DEFAULTS.android.browser,
+ );
+ } else if (discriminator === "ios") {
+ validatedEnv = validateMobileEnvironment(
+ env,
+ iosIndex!,
+ "ios",
+ DEFAULTS.ios.device,
+ DEFAULTS.ios.browser,
+ );
+ } else {
+ throw new Error(`Unsupported platform: ${discriminator}`);
+ }
+
+ validatedEnvironments.push(validatedEnv);
+ }
+
+ if (framework === SDKSupportedBrowserAutomationFrameworkEnum.playwright) {
+ validatedEnvironments.forEach((env) => {
+ if (env.browser) {
+ env.browser = env.browser.toLowerCase();
+ }
+ });
+ }
+
+ return validatedEnvironments;
+}
+
+// Optimized desktop validation using nested indexed maps for O(1) lookups
+function validateDesktopEnvironment(
+ env: string[],
+ index: DesktopIndex,
+ platform: "windows" | "macos",
+ defaultBrowser: string,
+): ValidatedEnvironment {
+ const [, osVersion, browser, browserVersion] = env;
+
+ const osKey = platform === "windows" ? "Windows" : "OS X";
+
+ // Use nested index for O(1) lookup instead of filtering
+ const osMap = index.nested.get(osKey);
+ if (!osMap) {
+ throw new Error(`No ${platform} devices available`);
+ }
+
+ // Get available OS versions for this platform
+ const availableOSVersions = Array.from(osMap.keys());
+
+ const validatedOSVersion = resolveVersion(
+ osVersion || "latest",
+ availableOSVersions,
+ );
+
+ // Use nested index for O(1) lookup
+ const osVersionMap = osMap.get(validatedOSVersion);
+ if (!osVersionMap) {
+ throw new Error(
+ `OS version "${validatedOSVersion}" not available for ${platform}`,
+ );
+ }
+
+ // Get available browsers for this OS version
+ const availableBrowsers = Array.from(osVersionMap.keys());
+ const validatedBrowser = validateBrowserExact(
+ browser || defaultBrowser,
+ availableBrowsers,
+ );
+
+ // Use nested index for O(1) lookup
+ const browserEntries = osVersionMap.get(validatedBrowser);
+ if (!browserEntries || browserEntries.length === 0) {
+ throw new Error(
+ `Browser "${validatedBrowser}" not available for ${platform} ${validatedOSVersion}`,
+ );
+ }
+
+ const availableBrowserVersions = [
+ ...new Set(browserEntries.map((e) => e.browser_version)),
+ ] as string[];
+ const validatedBrowserVersion = resolveVersion(
+ browserVersion || "latest",
+ availableBrowserVersions,
+ );
+
+ return {
+ platform,
+ osVersion: validatedOSVersion,
+ browser: validatedBrowser,
+ browserVersion: validatedBrowserVersion,
+ };
+}
+
+// Optimized mobile validation using indexed maps
+function validateMobileEnvironment(
+ env: string[],
+ index: MobileIndex,
+ platform: "android" | "ios",
+ defaultDevice: string,
+ defaultBrowser: string,
+): ValidatedEnvironment {
+ const [, deviceName, osVersion, browser] = env;
+
+ const platformEntries = index.byPlatform.get(platform) || [];
+ if (platformEntries.length === 0) {
+ throw new Error(`No ${platform} devices available`);
+ }
+
+ // Use fuzzy search only for device names (as suggested in feedback)
+ const deviceMatches = customFuzzySearch(
+ platformEntries,
+ ["display_name"],
+ deviceName || defaultDevice,
+ 5,
+ );
+ if (deviceMatches.length === 0) {
+ throw new Error(
+ `No ${platform} devices matching "${deviceName}". Available devices: ${platformEntries
+ .map((d) => d.display_name || "unknown")
+ .slice(0, 5)
+ .join(", ")}`,
+ );
+ }
+
+ // Try to find exact match first
+ const exactMatch = deviceMatches.find(
+ (m) => m.display_name.toLowerCase() === (deviceName || "").toLowerCase(),
+ );
+
+ // If no exact match, throw error instead of using fuzzy match
+ if (!exactMatch) {
+ const suggestions = deviceMatches.map((m) => m.display_name).join(", ");
+ throw new Error(
+ `Device "${deviceName}" not found exactly for ${platform}. Available similar devices: ${suggestions}. Please use the exact device name.`,
+ );
+ }
+
+ // Use index for faster filtering
+ const deviceKey = exactMatch.display_name.toLowerCase();
+ const deviceFiltered = index.byDeviceName.get(deviceKey) || [];
+
+ const availableOSVersions = [
+ ...new Set(deviceFiltered.map((d) => d.os_version)),
+ ] as string[];
+ const validatedOSVersion = resolveVersion(
+ osVersion || "latest",
+ availableOSVersions,
+ );
+
+ // Use index for faster filtering
+ const osVersionEntries = index.byOSVersion.get(validatedOSVersion) || [];
+ const osFiltered = osVersionEntries.filter(
+ (d) => d.display_name.toLowerCase() === deviceKey,
+ );
+
+ // Validate browser if provided - use exact matching for browsers
+ let validatedBrowser = browser || defaultBrowser;
+ if (browser && osFiltered.length > 0) {
+ // Extract browsers more carefully - handle different possible structures
+ const availableBrowsers = [
+ ...new Set(
+ osFiltered.flatMap((d) => {
+ if (d.browsers && Array.isArray(d.browsers)) {
+ // If browsers is an array of objects with browser property
+ return d.browsers
+ .map((b) => {
+ // Use display_name for user-friendly browser names, fallback to browser field
+ return b.display_name || b.browser;
+ })
+ .filter(Boolean);
+ }
+ // For mobile devices, provide default browsers if none found
+ return platform === "android" ? ["chrome"] : ["safari"];
+ }),
+ ),
+ ].filter(Boolean) as string[];
+
+ if (availableBrowsers.length > 0) {
+ try {
+ validatedBrowser = validateBrowserExact(browser, availableBrowsers);
+ } catch (error) {
+ // Add more context to browser validation errors
+ throw new Error(
+ `Failed to validate browser "${browser}" for ${platform} device "${exactMatch.display_name}" on OS version "${validatedOSVersion}". ${error instanceof Error ? error.message : String(error)}`,
+ );
+ }
+ } else {
+ // For mobile, if no specific browsers found, just use the requested browser
+ // as most mobile devices support standard browsers
+ validatedBrowser = browser || defaultBrowser;
+ }
+ }
+
+ return {
+ platform,
+ osVersion: validatedOSVersion,
+ deviceName: exactMatch.display_name,
+ browser: validatedBrowser,
+ };
+}
+
+// ============================================================================
+// APP AUTOMATE SECTION (Mobile devices for App Automate)
+// ============================================================================
+
+export async function validateAppAutomateDevices(
+ devices: Array>,
+): Promise {
+ const validatedDevices: ValidatedEnvironment[] = [];
+
+ if (!devices || devices.length === 0) {
+ // Use centralized default fallback
+ return [
+ {
+ platform: "android",
+ osVersion: "latest",
+ deviceName: DEFAULTS.android.device,
+ },
+ ];
+ }
+
+ let appAutomateData: RawDeviceData;
+
+ try {
+ // Fetch app automate device data
+ appAutomateData = (await getDevicesAndBrowsers(
+ BrowserStackProducts.APP_AUTOMATE,
+ )) as RawDeviceData;
+ } catch (error) {
+ // Only wrap fetch-related errors
+ throw new Error(
+ `Failed to fetch device data: ${error instanceof Error ? error.message : String(error)}`,
+ );
+ }
+
+ for (const device of devices) {
+ // Parse device array in format ["android", "Device Name", "OS Version"]
+ const [platform, deviceName, osVersion] = device;
+
+ // Find matching device in the data
+ let validatedDevice: ValidatedEnvironment | null = null;
+
+ if (!appAutomateData.mobile) {
+ throw new Error("No mobile device data available");
+ }
+
+ // Filter by platform first
+ const platformGroup = appAutomateData.mobile.find(
+ (group) => group.os === platform.toLowerCase(),
+ );
+
+ if (!platformGroup) {
+ throw new Error(`Platform "${platform}" not supported for App Automate`);
+ }
+
+ const platformDevices = platformGroup.devices;
+
+ // Find exact device name match (case-insensitive)
+ const exactMatch = platformDevices.find(
+ (d) => d.display_name.toLowerCase() === deviceName.toLowerCase(),
+ );
+
+ if (exactMatch) {
+ // Check if the OS version is available for this device
+ const deviceVersions = platformDevices
+ .filter((d) => d.display_name === exactMatch.display_name)
+ .map((d) => d.os_version);
+
+ const validatedOSVersion = resolveVersion(
+ osVersion || "latest",
+ deviceVersions,
+ );
+
+ validatedDevice = {
+ platform: platformGroup.os,
+ osVersion: validatedOSVersion,
+ deviceName: exactMatch.display_name,
+ };
+ }
+
+ if (!validatedDevice) {
+ // If no exact match found, suggest similar devices from the SAME platform only
+ const platformDevicesForSearch = platformDevices.map((d) => ({
+ ...d,
+ platform: platformGroup.os,
+ }));
+
+ // Try fuzzy search with a more lenient threshold
+ const deviceMatches = customFuzzySearch(
+ platformDevicesForSearch,
+ ["display_name"],
+ deviceName,
+ 5,
+ 0.8, // More lenient threshold
+ );
+
+ const suggestions = deviceMatches
+ .map((m) => `${m.display_name}`)
+ .join(", ");
+
+ // If no fuzzy matches, show some available devices as fallback
+ const fallbackDevices = platformDevicesForSearch
+ .slice(0, 5)
+ .map((d) => d.display_name)
+ .join(", ");
+
+ const errorMessage = suggestions
+ ? `Device "${deviceName}" not found for platform "${platform}".\nAvailable similar devices: ${suggestions}`
+ : `Device "${deviceName}" not found for platform "${platform}".\nAvailable devices: ${fallbackDevices}`;
+
+ throw new Error(errorMessage);
+ }
+
+ validatedDevices.push(validatedDevice);
+ }
+
+ return validatedDevices;
+}
+
+// ============================================================================
+// SHARED UTILITY FUNCTIONS
+// ============================================================================
+
+// Exact browser validation (preferred for structured fields)
+function validateBrowserExact(
+ requestedBrowser: string,
+ availableBrowsers: string[],
+): string {
+ const exactMatch = availableBrowsers.find(
+ (b) => b.toLowerCase() === requestedBrowser.toLowerCase(),
+ );
+ if (exactMatch) {
+ return exactMatch;
+ }
+
+ throw new Error(
+ `Browser "${requestedBrowser}" not found. Available options: ${availableBrowsers.join(", ")}`,
+ );
+}
diff --git a/src/tools/sdk-utils/common/formatUtils.ts b/src/tools/sdk-utils/common/formatUtils.ts
new file mode 100644
index 00000000..e50527b5
--- /dev/null
+++ b/src/tools/sdk-utils/common/formatUtils.ts
@@ -0,0 +1,34 @@
+export function formatInstructionsWithNumbers(
+ instructionText: string,
+ separator: string = "---STEP---",
+): { formattedSteps: string; stepCount: number } {
+ // 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 {
+ formattedSteps: `**Step 1:**\n${instructionText.trim()}`,
+ stepCount: 1,
+ };
+ }
+
+ // Format each step with numbering
+ const formattedSteps = steps
+ .map((step, index) => {
+ return `**Step ${index + 1}:**\n${step.trim()}`;
+ })
+ .join("\n\n");
+
+ return {
+ formattedSteps,
+ stepCount: steps.length,
+ };
+}
+
+export function generateVerificationMessage(stepCount: number): string {
+ return `**✅ Verification:**\nPlease verify that you have completed all ${stepCount} steps above to ensure proper setup. If you encounter any issues, double-check each step and ensure all commands executed successfully.`;
+}
diff --git a/src/tools/sdk-utils/common/index.ts b/src/tools/sdk-utils/common/index.ts
new file mode 100644
index 00000000..7a145f57
--- /dev/null
+++ b/src/tools/sdk-utils/common/index.ts
@@ -0,0 +1,4 @@
+// Common utilities and types for SDK tools
+export * from "./types.js";
+export * from "./constants.js";
+export * from "./formatUtils.js";
diff --git a/src/tools/sdk-utils/common/instructionUtils.ts b/src/tools/sdk-utils/common/instructionUtils.ts
new file mode 100644
index 00000000..484928ed
--- /dev/null
+++ b/src/tools/sdk-utils/common/instructionUtils.ts
@@ -0,0 +1,49 @@
+/**
+ * Core instruction configuration utilities for runTestsOnBrowserStack tool.
+ */
+
+import { SUPPORTED_CONFIGURATIONS } from "../bstack/frameworks.js";
+import {
+ SDKSupportedLanguage,
+ SDKSupportedBrowserAutomationFramework,
+ SDKSupportedTestingFramework,
+} from "./types.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: SDKSupportedBrowserAutomationFramework,
+ detectedTestingFramework: SDKSupportedTestingFramework,
+ detectedLanguage: SDKSupportedLanguage,
+ username: string,
+ accessKey: string,
+) => {
+ 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);
+};
diff --git a/src/tools/sdk-utils/common/schema.ts b/src/tools/sdk-utils/common/schema.ts
new file mode 100644
index 00000000..39c5cb4f
--- /dev/null
+++ b/src/tools/sdk-utils/common/schema.ts
@@ -0,0 +1,153 @@
+import { z } from "zod";
+import { PercyIntegrationTypeEnum } from "./types.js";
+import {
+ SDKSupportedBrowserAutomationFrameworkEnum,
+ SDKSupportedTestingFrameworkEnum,
+ SDKSupportedLanguageEnum,
+} from "./types.js";
+
+// Platform enums for better validation
+export const PlatformEnum = {
+ WINDOWS: "windows",
+ MACOS: "macos",
+ ANDROID: "android",
+ IOS: "ios",
+} as const;
+
+export const WindowsPlatformEnum = {
+ WINDOWS: "windows",
+} as const;
+
+export const MacOSPlatformEnum = {
+ MACOS: "macos",
+} as const;
+
+export const SetUpPercyParamsShape = {
+ projectName: z.string().describe("A unique name for your Percy project."),
+ detectedLanguage: z.nativeEnum(SDKSupportedLanguageEnum),
+ detectedBrowserAutomationFramework: z.nativeEnum(
+ SDKSupportedBrowserAutomationFrameworkEnum,
+ ),
+ detectedTestingFramework: z.nativeEnum(SDKSupportedTestingFrameworkEnum),
+ integrationType: z
+ .nativeEnum(PercyIntegrationTypeEnum)
+ .describe(
+ "Specify the Percy integration type: web (Percy Web) or automate (Percy Automate). If not provided, always prompt the user with: 'Please specify the Percy integration type.' Do not proceed without an explicit selection. Never use a default.",
+ ),
+ folderPaths: z
+ .array(z.string())
+ .optional()
+ .describe(
+ "An array of absolute folder paths containing UI test files. If not provided, analyze codebase for UI test folders by scanning for test patterns which contain UI test cases as per framework. Return empty array if none found.",
+ ),
+ filePaths: z
+ .array(z.string())
+ .optional()
+ .describe(
+ "An array of absolute file paths to specific UI test files. Use this when you want to target specific test files rather than entire folders. If not provided, will use folderPaths instead.",
+ ),
+};
+
+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(
+ z.union([
+ // Windows: [windows, osVersion, browser, browserVersion]
+ z.tuple([
+ z
+ .nativeEnum(WindowsPlatformEnum)
+ .describe("Platform identifier: 'windows'"),
+ z.string().describe("Windows version, e.g. '10', '11'"),
+ z.string().describe("Browser name, e.g. 'chrome', 'firefox', 'edge'"),
+ z
+ .string()
+ .describe("Browser version, e.g. '132', 'latest', 'oldest'"),
+ ]),
+ // Android: [android, name, model, osVersion, browser]
+ z.tuple([
+ z
+ .literal(PlatformEnum.ANDROID)
+ .describe("Platform identifier: 'android'"),
+ z
+ .string()
+ .describe(
+ "Device name, e.g. 'Samsung Galaxy S24', 'Google Pixel 8'",
+ ),
+ z.string().describe("Android version, e.g. '14', '16', 'latest'"),
+ z.string().describe("Browser name, e.g. 'chrome', 'samsung browser'"),
+ ]),
+ // iOS: [ios, name, model, osVersion, browser]
+ z.tuple([
+ z.literal(PlatformEnum.IOS).describe("Platform identifier: 'ios'"),
+ z.string().describe("Device name, e.g. 'iPhone 12 Pro'"),
+ z.string().describe("iOS version, e.g. '17', 'latest'"),
+ z.string().describe("Browser name, typically 'safari'"),
+ ]),
+ // macOS: [mac|macos, name, model, browser, browserVersion]
+ z.tuple([
+ z
+ .nativeEnum(MacOSPlatformEnum)
+ .describe("Platform identifier: 'mac' or 'macos'"),
+ z.string().describe("macOS version name, e.g. 'Sequoia', 'Ventura'"),
+ z.string().describe("Browser name, e.g. 'safari', 'chrome'"),
+ z.string().describe("Browser version, e.g. 'latest'"),
+ ]),
+ ]),
+ )
+ .max(3)
+ .default([])
+ .describe(
+ "Preferred tuples of target devices.Add device only when user asks explicitly for it. Defaults to [] . Example: [['windows', '11', 'chrome', 'latest']]",
+ ),
+};
+
+export const SetUpPercySchema = z.object(SetUpPercyParamsShape);
+
+export const RunTestsOnBrowserStackSchema = z.object(
+ RunTestsOnBrowserStackParamsShape,
+);
+
+export type SetUpPercyInput = z.infer;
+export type RunTestsOnBrowserStackInput = z.infer<
+ typeof RunTestsOnBrowserStackSchema
+>;
+
+export const RunPercyScanParamsShape = {
+ projectName: z.string().describe("The name of the project to run Percy on."),
+ percyRunCommand: z
+ .string()
+ .optional()
+ .describe(
+ "The test command to run with Percy. Optional — the LLM should try to infer it first from project context.",
+ ),
+ integrationType: z
+ .nativeEnum(PercyIntegrationTypeEnum)
+ .describe(
+ "Specifies whether to integrate with Percy Web or Percy Automate. If not explicitly provided, prompt the user to select the desired integration type.",
+ ),
+};
+
+export const FetchPercyChangesParamsShape = {
+ project_name: z
+ .string()
+ .describe(
+ "The name of the BrowserStack project. If not found, ask user directly.",
+ ),
+};
+
+export const ManagePercyBuildApprovalParamsShape = {
+ buildId: z
+ .string()
+ .describe("The ID of the Percy build to approve or reject."),
+ action: z
+ .enum(["approve", "unapprove", "reject"])
+ .describe("The action to perform on the Percy build."),
+};
diff --git a/src/tools/sdk-utils/common/types.ts b/src/tools/sdk-utils/common/types.ts
new file mode 100644
index 00000000..3994a899
--- /dev/null
+++ b/src/tools/sdk-utils/common/types.ts
@@ -0,0 +1,94 @@
+export enum PercyIntegrationTypeEnum {
+ WEB = "web",
+ AUTOMATE = "automate",
+}
+
+export enum SDKSupportedLanguageEnum {
+ nodejs = "nodejs",
+ python = "python",
+ java = "java",
+ csharp = "csharp",
+ ruby = "ruby",
+}
+export type SDKSupportedLanguage = keyof typeof SDKSupportedLanguageEnum;
+
+export enum SDKSupportedBrowserAutomationFrameworkEnum {
+ playwright = "playwright",
+ selenium = "selenium",
+ cypress = "cypress",
+}
+export type SDKSupportedBrowserAutomationFramework =
+ keyof typeof SDKSupportedBrowserAutomationFrameworkEnum;
+
+export 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",
+ cypress = "cypress",
+ nunit = "nunit",
+ mstest = "mstest",
+ xunit = "xunit",
+ specflow = "specflow",
+ reqnroll = "reqnroll",
+ rspec = "rspec",
+ serenity = "serenity",
+}
+
+export const SDKSupportedLanguages = Object.values(SDKSupportedLanguageEnum);
+export type SDKSupportedTestingFramework =
+ keyof typeof SDKSupportedTestingFrameworkEnum;
+export const SDKSupportedTestingFrameworks = Object.values(
+ SDKSupportedTestingFrameworkEnum,
+);
+
+export type ConfigMapping = Partial<
+ Record<
+ SDKSupportedLanguageEnum,
+ Partial<
+ Record<
+ SDKSupportedBrowserAutomationFrameworkEnum,
+ Partial<
+ Record<
+ SDKSupportedTestingFrameworkEnum,
+ {
+ instructions: (
+ username: string,
+ accessKey: string,
+ ) => { setup: string; run: string };
+ }
+ >
+ >
+ >
+ >
+ >
+>;
+
+// Common interfaces for instruction results
+export interface RunTestsStep {
+ type: "instruction" | "error" | "warning";
+ title: string;
+ content: string;
+ isError?: boolean;
+}
+
+export interface RunTestsInstructionResult {
+ steps: RunTestsStep[];
+ requiresPercy: boolean;
+ missingDependencies: string[];
+ shouldSkipFormatting?: boolean;
+}
+
+export enum PercyAutomateNotImplementedType {
+ LANGUAGE = "language",
+ FRAMEWORK = "framework",
+}
diff --git a/src/tools/sdk-utils/common/utils.ts b/src/tools/sdk-utils/common/utils.ts
new file mode 100644
index 00000000..ba167c1a
--- /dev/null
+++ b/src/tools/sdk-utils/common/utils.ts
@@ -0,0 +1,153 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { PercyIntegrationTypeEnum } from "../common/types.js";
+import { isPercyAutomateFrameworkSupported } from "../percy-automate/frameworks.js";
+import { isPercyWebFrameworkSupported } from "../percy-web/frameworks.js";
+import {
+ formatInstructionsWithNumbers,
+ generateVerificationMessage,
+} from "./formatUtils.js";
+import {
+ RunTestsInstructionResult,
+ PercyAutomateNotImplementedType,
+} from "./types.js";
+import { IMPORTANT_SETUP_WARNING } from "./index.js";
+import { PackageJsonVersion } from "../../../index.js";
+
+export function checkPercyIntegrationSupport(input: {
+ integrationType: string;
+ detectedLanguage: string;
+ detectedTestingFramework?: string;
+ detectedBrowserAutomationFramework?: string;
+}): { supported: boolean; errorMessage?: string } {
+ if (input.integrationType === PercyIntegrationTypeEnum.AUTOMATE) {
+ const isSupported = isPercyAutomateFrameworkSupported(
+ input.detectedLanguage,
+ input.detectedBrowserAutomationFramework || "",
+ input.detectedTestingFramework || "",
+ );
+ if (!isSupported) {
+ return {
+ supported: false,
+ errorMessage: `Percy Automate is not supported for this configuration. Language: ${input.detectedLanguage} Testing Framework: ${input.detectedTestingFramework}`,
+ };
+ }
+ } else if (input.integrationType === PercyIntegrationTypeEnum.WEB) {
+ const isSupported = isPercyWebFrameworkSupported(
+ input.detectedLanguage,
+ input.detectedBrowserAutomationFramework || "",
+ );
+ if (!isSupported) {
+ return {
+ supported: false,
+ errorMessage: `Percy Web is not supported for this configuration. Language: ${input.detectedLanguage} Browser Automation Framework: ${input.detectedBrowserAutomationFramework}`,
+ };
+ }
+ }
+ return { supported: true };
+}
+
+export async function formatToolResult(
+ resultPromise: Promise | RunTestsInstructionResult,
+ runType?: "percy-web" | "bstack" | "percy-bstack" | "percy-automate",
+): Promise {
+ const { steps, requiresPercy, missingDependencies, shouldSkipFormatting } =
+ await resultPromise;
+
+ if (shouldSkipFormatting) {
+ return {
+ content: steps.map((step) => ({
+ type: "text" as const,
+ text: step.content,
+ })),
+ isError: steps.some((s) => s.isError),
+ steps,
+ requiresPercy,
+ missingDependencies,
+ };
+ }
+
+ const combinedInstructions = steps.map((step) => step.content).join("\n");
+ const { formattedSteps, stepCount } =
+ formatInstructionsWithNumbers(combinedInstructions);
+ const verificationMessage = generateVerificationMessage(stepCount);
+
+ const finalContent = [
+ { type: "text" as const, text: IMPORTANT_SETUP_WARNING },
+ { type: "text" as const, text: formattedSteps },
+ { type: "text" as const, text: verificationMessage },
+ ];
+
+ if (runType != "percy-web") {
+ finalContent.push({
+ type: "text",
+ text: "CRITICAL: After the build is run, you MUST explicitly ask the user if they want to perform RCA (Root Cause Analysis) for any failed tests. This step is mandatory and should not be skipped.",
+ });
+ }
+
+ return {
+ content: finalContent,
+ isError: steps.some((s) => s.isError),
+ requiresPercy,
+ missingDependencies,
+ };
+}
+
+export function getPercyAutomateNotImplementedMessage(
+ type: PercyAutomateNotImplementedType,
+ input: {
+ detectedLanguage: string;
+ detectedBrowserAutomationFramework: string;
+ },
+ supported: string[],
+): string {
+ if (type === PercyAutomateNotImplementedType.LANGUAGE) {
+ return `Percy Automate does not support the language: ${input.detectedLanguage}. Supported languages are: ${supported.join(", ")}.`;
+ } else {
+ return `Percy Automate does not support ${input.detectedBrowserAutomationFramework} for ${input.detectedLanguage}. Supported frameworks for ${input.detectedLanguage} are: ${supported.join(", ")}.`;
+ }
+}
+
+export function getBootstrapFailedMessage(
+ error: unknown,
+ context: { config: unknown; percyMode?: string },
+): string {
+ const error_message =
+ error instanceof Error ? error.message : "unknown error";
+ return `Failed to bootstrap project with BrowserStack SDK.
+Error: ${error_message}
+Percy Mode: ${context.percyMode ?? "automate"}
+MCP Version: ${PackageJsonVersion}
+Please open an issue on GitHub if the problem persists.`;
+}
+
+export function percyUnsupportedResult(
+ integrationType: PercyIntegrationTypeEnum,
+ supportCheck?: { errorMessage?: string },
+): CallToolResult {
+ const defaultMessage = `Percy ${integrationType} integration is not supported for this configuration.`;
+
+ return {
+ content: [
+ {
+ type: "text",
+ text: supportCheck?.errorMessage || defaultMessage,
+ },
+ ],
+ isError: true,
+ shouldSkipFormatting: true,
+ };
+}
+
+export function validatePercyPathandFolders(input: any): void {
+ const hasFolderPaths = input.folderPaths && input.folderPaths.length > 0;
+ const hasFilePaths = input.filePaths && input.filePaths.length > 0;
+
+ if (!hasFolderPaths && !hasFilePaths) {
+ throw new Error(
+ "Please provide either:\n" +
+ "• folderPaths: Array of directory paths containing test files\n" +
+ "• filePaths: Array of specific test file paths\n\n" +
+ "Example: { filePaths: ['/path/to/test.spec.js'] }",
+ );
+ }
+}
diff --git a/src/tools/sdk-utils/handler.ts b/src/tools/sdk-utils/handler.ts
new file mode 100644
index 00000000..317e2310
--- /dev/null
+++ b/src/tools/sdk-utils/handler.ts
@@ -0,0 +1,228 @@
+import { formatToolResult } from "./common/utils.js";
+import { BrowserStackConfig } from "../../lib/types.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { PercyIntegrationTypeEnum } from "./common/types.js";
+import { getBrowserStackAuth } from "../../lib/get-auth.js";
+import { fetchPercyToken } from "./percy-web/fetchPercyToken.js";
+import { runPercyWeb } from "./percy-web/handler.js";
+import { runPercyAutomateOnly } from "./percy-automate/handler.js";
+import { runBstackSDKOnly } from "./bstack/sdkHandler.js";
+import { runPercyWithBrowserstackSDK } from "./percy-bstack/handler.js";
+import {
+ checkPercyIntegrationSupport,
+ validatePercyPathandFolders,
+} from "./common/utils.js";
+import {
+ SetUpPercySchema,
+ RunTestsOnBrowserStackSchema,
+} from "./common/schema.js";
+import { storedPercyResults } from "../../lib/inmemory-store.js";
+import {
+ getBootstrapFailedMessage,
+ percyUnsupportedResult,
+} from "./common/utils.js";
+import {
+ PERCY_SIMULATE_INSTRUCTION,
+ PERCY_REPLACE_REGEX,
+ PERCY_SIMULATION_DRIVER_INSTRUCTION,
+ PERCY_VERIFICATION_REGEX,
+} from "./common/constants.js";
+
+export async function runTestsOnBrowserStackHandler(
+ rawInput: unknown,
+ config: BrowserStackConfig,
+): Promise {
+ const input = RunTestsOnBrowserStackSchema.parse(rawInput);
+ const result = await runBstackSDKOnly(input, config);
+ return await formatToolResult(result);
+}
+
+export async function setUpPercyHandler(
+ rawInput: unknown,
+ config: BrowserStackConfig,
+): Promise {
+ try {
+ const input = SetUpPercySchema.parse(rawInput);
+ validatePercyPathandFolders(input);
+
+ // Clear any previous Percy results for a fresh start
+ storedPercyResults.clear();
+
+ storedPercyResults.set({
+ projectName: input.projectName,
+ detectedLanguage: input.detectedLanguage,
+ detectedBrowserAutomationFramework:
+ input.detectedBrowserAutomationFramework,
+ detectedTestingFramework: input.detectedTestingFramework,
+ integrationType: input.integrationType,
+ folderPaths: input.folderPaths || [],
+ filePaths: input.filePaths || [],
+ testFiles: {},
+ });
+
+ const authorization = getBrowserStackAuth(config);
+
+ const folderPaths = input.folderPaths || [];
+ const filePaths = input.filePaths || [];
+
+ const percyInput = {
+ projectName: input.projectName,
+ detectedLanguage: input.detectedLanguage,
+ detectedBrowserAutomationFramework:
+ input.detectedBrowserAutomationFramework,
+ detectedTestingFramework: input.detectedTestingFramework,
+ integrationType: input.integrationType,
+ folderPaths,
+ filePaths,
+ };
+
+ // Check for Percy Web integration support
+ if (input.integrationType === PercyIntegrationTypeEnum.WEB) {
+ const supportCheck = checkPercyIntegrationSupport(percyInput);
+ if (!supportCheck.supported) {
+ return percyUnsupportedResult(
+ PercyIntegrationTypeEnum.WEB,
+ supportCheck,
+ );
+ }
+
+ // Fetch the Percy token
+ const percyToken = await fetchPercyToken(
+ input.projectName,
+ authorization,
+ { type: PercyIntegrationTypeEnum.WEB },
+ );
+
+ const result = runPercyWeb(percyInput, percyToken);
+ return await formatToolResult(result, "percy-web");
+ } else if (input.integrationType === PercyIntegrationTypeEnum.AUTOMATE) {
+ // First try Percy with BrowserStack SDK
+ const percyWithBrowserstackSDKResult = runPercyWithBrowserstackSDK(
+ {
+ ...percyInput,
+ devices: [],
+ },
+ config,
+ );
+ const hasPercySDKError =
+ percyWithBrowserstackSDKResult.steps &&
+ percyWithBrowserstackSDKResult.steps.some((step) => step.isError);
+
+ if (!hasPercySDKError) {
+ // Percy with SDK is supported, prepend warning and return those steps
+ if (percyWithBrowserstackSDKResult.steps) {
+ percyWithBrowserstackSDKResult.steps.unshift({
+ type: "instruction" as const,
+ title: "Important: Existing SDK Setup",
+ content:
+ "If you have already set up the BrowserStack SDK, do not override it unless you have explicitly decided to do so.",
+ });
+ }
+ return await formatToolResult(percyWithBrowserstackSDKResult);
+ } else {
+ // Fallback to standalone Percy Automate if supported
+ const supportCheck = checkPercyIntegrationSupport({
+ ...percyInput,
+ integrationType: PercyIntegrationTypeEnum.AUTOMATE,
+ });
+ if (!supportCheck.supported) {
+ return percyUnsupportedResult(
+ PercyIntegrationTypeEnum.AUTOMATE,
+ supportCheck,
+ );
+ }
+ // SDK setup instructions (for Automate, without Percy)
+ const sdkInput = {
+ projectName: input.projectName,
+ detectedLanguage: input.detectedLanguage,
+ detectedBrowserAutomationFramework:
+ input.detectedBrowserAutomationFramework,
+ detectedTestingFramework: input.detectedTestingFramework,
+ devices: [],
+ };
+ const sdkResult = await runBstackSDKOnly(sdkInput, config, true);
+ // Percy Automate instructions
+ const percyToken = await fetchPercyToken(
+ input.projectName,
+ authorization,
+ { type: PercyIntegrationTypeEnum.AUTOMATE },
+ );
+ const percyAutomateResult = runPercyAutomateOnly(
+ percyInput,
+ percyToken,
+ );
+
+ // Combine steps: warning, SDK steps, Percy Automate steps
+ const steps = [
+ {
+ type: "instruction" as const,
+ title: "Important: Existing SDK Setup",
+ content:
+ "If you have already set up the BrowserStack SDK, do not override it unless you have explicitly decided to do so.",
+ },
+ ...(sdkResult.steps || []),
+ ...(percyAutomateResult.steps || []),
+ ];
+
+ // Combine all steps into the final result
+ return await formatToolResult({
+ ...percyAutomateResult,
+ steps,
+ });
+ }
+ } else {
+ return {
+ content: [
+ {
+ type: "text",
+ text: "Unknown or unsupported Percy integration type requested.",
+ },
+ ],
+ isError: true,
+ shouldSkipFormatting: true,
+ };
+ }
+ } catch (error) {
+ throw new Error(getBootstrapFailedMessage(error, { config }));
+ }
+}
+
+export async function simulatePercyChangeHandler(
+ rawInput: unknown,
+ config: BrowserStackConfig,
+): Promise {
+ try {
+ let percyInstruction;
+
+ try {
+ percyInstruction = await setUpPercyHandler(rawInput, config);
+ } catch {
+ throw new Error("Failed to set up Percy");
+ }
+
+ if (percyInstruction.isError) {
+ return percyInstruction;
+ }
+
+ if (Array.isArray(percyInstruction.content)) {
+ percyInstruction.content = percyInstruction.content.map((item) => {
+ if (typeof item.text === "string") {
+ const updatedText = item.text
+ .replace(PERCY_REPLACE_REGEX, PERCY_SIMULATE_INSTRUCTION)
+ .replace(PERCY_VERIFICATION_REGEX, "");
+ return { ...item, text: updatedText };
+ }
+ return item;
+ });
+ }
+
+ percyInstruction.content?.push({
+ type: "text" as const,
+ text: PERCY_SIMULATION_DRIVER_INSTRUCTION,
+ });
+
+ return percyInstruction;
+ } catch (error) {
+ throw new Error(getBootstrapFailedMessage(error, { config }));
+ }
+}
diff --git a/src/tools/sdk-utils/instructions.ts b/src/tools/sdk-utils/instructions.ts
deleted file mode 100644
index d98c872c..00000000
--- a/src/tools/sdk-utils/instructions.ts
+++ /dev/null
@@ -1,138 +0,0 @@
-import { SUPPORTED_CONFIGURATIONS } from "./constants.js";
-import { SDKSupportedLanguage } from "./types.js";
-import { SDKSupportedBrowserAutomationFramework } from "./types.js";
-import { SDKSupportedTestingFramework } from "./types.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: SDKSupportedBrowserAutomationFramework,
- detectedTestingFramework: SDKSupportedTestingFramework,
- detectedLanguage: SDKSupportedLanguage,
- username: string,
- accessKey: string,
-) => {
- 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: string[],
- enablePercy: boolean = 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: string,
- separator: string = "---STEP---",
-): string {
- // 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;
-}
diff --git a/src/tools/sdk-utils/percy-automate/constants.ts b/src/tools/sdk-utils/percy-automate/constants.ts
new file mode 100644
index 00000000..e73e7bde
--- /dev/null
+++ b/src/tools/sdk-utils/percy-automate/constants.ts
@@ -0,0 +1,348 @@
+import { PERCY_SNAPSHOT_INSTRUCTION } from "../common/constants.js";
+export const percyAutomateReviewSnapshotsStep = `
+---STEP---
+Review the snapshots
+ - Go to your Percy project on https://percy.io to review snapshots and approve/reject any visual changes.
+`;
+
+export const pythonPytestSeleniumInstructions = `
+Install Percy Automate dependencies
+ - Install Percy CLI:
+ npm install --save-dev @percy/cli
+ - Install Percy Python SDK for Automate:
+ pip install percy-selenium
+
+---STEP---
+Update your Pytest test script
+${PERCY_SNAPSHOT_INSTRUCTION}
+ - Import the Percy snapshot helper:
+ from percy import percy_screenshot
+ - In your test, take snapshots at key points:
+ percy_screenshot(driver, "Your snapshot name")
+
+Example:
+\`\`\`python
+import pytest
+from selenium import webdriver
+from percy import percy_screenshot
+
+@pytest.fixture
+def driver():
+ driver = webdriver.Chrome()
+ yield driver
+ driver.quit()
+
+def test_homepage(driver):
+ driver.get("http://localhost:8000")
+ percy_screenshot(driver, "Home page")
+ # ... more test steps ...
+ percy_screenshot(driver, "After login")
+\`\`\`
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- browserstack-sdk pytest').
+${percyAutomateReviewSnapshotsStep}
+`;
+
+export const pythonPytestPlaywrightInstructions = `
+Install Percy Automate dependencies
+ - Install Percy CLI:
+ npm install --save @percy/cli
+ - Install Percy Playwright SDK for Automate:
+ pip install percy-playwright
+
+---STEP---
+Update your Playwright test script
+${PERCY_SNAPSHOT_INSTRUCTION}
+ - Import the Percy screenshot helper:
+ from percy import percy_screenshot
+ - In your test, take snapshots at key points:
+ percy_screenshot(page, name="Your snapshot name")
+ # You can pass \`options\`:
+ percy_screenshot(page, name="Your snapshot name", options={ "full_page": True })
+
+Example:
+\`\`\`python
+from playwright.sync_api import sync_playwright
+from percy import percy_screenshot
+
+def test_visual_regression():
+ with sync_playwright() as p:
+ browser = p.chromium.launch()
+ page = browser.new_page()
+ page.goto("http://localhost:8000")
+ percy_screenshot(page, name="Home page")
+ # ... more test steps ...
+ percy_screenshot(page, name="After login", options={ "full_page": True })
+ browser.close()
+\`\`\`
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- ').
+${percyAutomateReviewSnapshotsStep}
+`;
+
+export const jsCypressPercyAutomateInstructions = `
+Install Percy Automate dependencies
+ - Install Percy CLI:
+ npm install --save-dev @percy/cli
+ - Install Percy Cypress SDK:
+ npm install --save-dev @percy/cypress
+
+---STEP---
+Update your Cypress test script
+${PERCY_SNAPSHOT_INSTRUCTION}
+ - Import and initialize Percy in your cypress/support/index.js:
+ import '@percy/cypress';
+ - In your test, take snapshots at key points:
+ cy.percySnapshot('Your snapshot name');
+
+Example:
+\`\`\`javascript
+describe('Percy Automate Cypress Example', () => {
+ it('should take Percy snapshots', () => {
+ cy.visit('http://localhost:8000');
+ cy.percySnapshot('Home page');
+ // ... more test steps ...
+ cy.percySnapshot('After login');
+ });
+});
+\`\`\`
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- cypress run').
+${percyAutomateReviewSnapshotsStep}
+`;
+
+export const mochaPercyAutomateInstructions = `
+Install Percy Automate dependencies
+ - Install Percy CLI:
+ npm install --save @percy/cli
+ - Install Percy Selenium SDK:
+ npm install @percy/selenium-webdriver@2.0.1
+
+---STEP---
+Update your Mocha Automate test script
+ - Import the Percy screenshot helper:
+ const { percyScreenshot } = require('@percy/selenium-webdriver');
+ - Use the Percy screenshot command to take required screenshots in your Automate session:
+ await percyScreenshot(driver, 'Screenshot 1');
+ options = { percyCSS: 'h1{color:red;}' };
+ await percyScreenshot(driver, 'Screenshot 2', options);
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- mocha').
+${percyAutomateReviewSnapshotsStep}
+`;
+
+// Mocha Percy Playwright Instructions
+export const mochaPercyPlaywrightInstructions = `
+Install Percy Automate dependencies
+ - Install the latest Percy CLI:
+ npm install --save @percy/cli
+ - Install the Percy Playwright SDK:
+ npm install @percy/playwright
+
+---STEP---
+Update your Mocha Playwright test script
+ - Import the Percy screenshot helper:
+ const { percyScreenshot } = require("@percy/playwright");
+ - Use the Percy screenshot command to take required screenshots in your Automate session.
+
+Example:
+\`\`\`javascript
+const { percyScreenshot } = require("@percy/playwright");
+await percyScreenshot(page, "Screenshot 1");
+// With options
+await percyScreenshot(page, "Screenshot 2", { percyCSS: "h1{color:green;}" });
+\`\`\`
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- ').
+${percyAutomateReviewSnapshotsStep}
+`;
+
+export const jestPercyAutomateInstructions = `
+Install or upgrade the BrowserStack SDK:
+ - Install the SDK:
+ npm i -D browserstack-node-sdk@latest
+ - Run the setup:
+ npx setup --username "YOUR_USERNAME" --key "YOUR_ACCESS_KEY"
+
+---STEP---
+Manually capture screenshots:
+ 1. Import the BrowserStack Percy SDK in your test script:
+ const { percy } = require('browserstack-node-sdk');
+ 2. Use \`percy.screenshot(driver, name)\` at desired points in your test.
+
+Example:
+\`\`\`javascript
+const { percy } = require('browserstack-node-sdk');
+describe("JestJS test", () => {
+ let driver;
+ const caps = require("../" + conf_file).capabilities;
+
+ beforeAll(() => {
+ driver = new Builder()
+ .usingServer("http://example-servername/hub")
+ .withCapabilities(caps)
+ .build();
+ });
+
+ test("my test", async () => {
+ // ...
+ await percy.screenshot(driver, "My Screenshot");
+ // ...
+ });
+});
+\`\`\`
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npm run [your-test-script-name]-browserstack').
+${percyAutomateReviewSnapshotsStep}
+`;
+
+export const webdriverioPercyAutomateInstructions = `
+Install or upgrade BrowserStack SDK
+ - Install the BrowserStack SDK:
+ npm i -D @wdio/browserstack-service
+
+---STEP---
+Update your WebdriverIO config file
+ 1. Set \`percy: true\`
+ 2. Set a \`projectName\`
+ 3. Set \`percyCaptureMode: auto\` (or another mode as needed)
+
+Example WebdriverIO config:
+\`\`\`js
+exports.config = {
+ user: process.env.BROWSERSTACK_USERNAME || 'YOUR_USERNAME',
+ key: process.env.BROWSERSTACK_ACCESS_KEY || 'YOUR_ACCESS_KEY',
+ hostname: 'hub.browserstack.com',
+ services: [
+ [
+ 'browserstack',
+ { browserstackLocal: true, opts: { forcelocal: false }, percy: true, percyCaptureMode: 'auto' }
+ ],
+ ],
+ // add path to the test file
+}
+\`\`\`
+
+---STEP---
+(Optional) Manually capture screenshots
+ 1. Import the BrowserStack Percy SDK in your test script:
+ const { percy } = require('browserstack-node-sdk');
+ 2. Add the \`await percy.screenshot(driver, name)\` method at required points in your test script.
+
+Example:
+\`\`\`javascript
+ const { percy } = require('browserstack-node-sdk');
+ 2. Add the \`await percy.screenshot(driver, name)\` method at required points in your test script.
+
+Example:
+\`\`\`javascript
+const { percy } = require('browserstack-node-sdk');
+describe("WebdriverIO Test", () => {
+ it("my test", async () => {
+ // ....
+ await percy.screenshot(driver, "My Screenshot")
+ // ....
+ });
+});
+\`\`\`
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command as defined in your package.json file.
+${percyAutomateReviewSnapshotsStep}
+`;
+
+export const testcafePercyAutomateInstructions = `
+Install Percy dependencies
+ - Install the required dependencies:
+ npm install --save-dev @percy/cli @percy/testcafe
+
+---STEP---
+Update your test script
+${PERCY_SNAPSHOT_INSTRUCTION}
+ - Import the Percy library and use the percySnapshot function to take screenshots.
+
+Example:
+\`\`\`javascript
+import percySnapshot from '@percy/testcafe';
+fixture('MyFixture')
+ .page('https://devexpress.github.io/testcafe/example/');
+test('Test1', async t => {
+ await t.typeText('#developer-name', 'John Doe');
+ await percySnapshot(t, 'TestCafe Example');
+});
+\`\`\`
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- testcafe chrome:headless tests').
+${percyAutomateReviewSnapshotsStep}
+`;
+
+// Java Playwright Percy Automate Instructions
+export const javaPlaywrightJunitInstructions = `
+Install Percy Automate dependencies
+ - Install the latest Percy CLI:
+ npm install --save @percy/cli
+ - Add the Percy Playwright Java SDK to your pom.xml:
+\`\`\`xml
+
+ io.percy
+ percy-playwright-java
+ 1.0.0
+
+\`\`\`
+
+---STEP---
+Update your Automate test script
+ - Import the Percy library:
+ import io.percy.playwright.Percy;
+ - Use the Percy screenshot command to take required screenshots in your Automate session.
+
+Example:
+\`\`\`java
+Percy percy = new Percy(page);
+percy.screenshot("screenshot_1");
+// With options
+percy.screenshot("screenshot_2", options);
+\`\`\`
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- ').
+
+${percyAutomateReviewSnapshotsStep}
+`;
+
+// C# Playwright NUnit Percy Automate Instructions
+export const csharpPlaywrightNunitInstructions = `
+Install Percy Automate dependencies
+ - Install the latest Percy CLI:
+ npm install --save @percy/cli
+ - Add the Percy Playwright SDK to your .csproj file:
+\`\`\`xml
+
+\`\`\`
+
+---STEP---
+Update your NUnit Playwright test script
+ - Import the Percy library:
+ using PercyIO.Playwright;
+ - Use the Percy screenshot command to take required screenshots in your Automate session.
+
+Example:
+\`\`\`csharp
+using PercyIO.Playwright;
+Percy.Screenshot(page, "example_screenshot_1");
+// With options
+Percy.Screenshot(page, "example_screenshot_2", options);
+\`\`\`
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- ').
+
+${percyAutomateReviewSnapshotsStep}
+`;
diff --git a/src/tools/sdk-utils/percy-automate/frameworks.ts b/src/tools/sdk-utils/percy-automate/frameworks.ts
new file mode 100644
index 00000000..50ba8444
--- /dev/null
+++ b/src/tools/sdk-utils/percy-automate/frameworks.ts
@@ -0,0 +1,56 @@
+import { ConfigMapping } from "./types.js";
+import * as instructions from "./constants.js";
+
+export const SUPPORTED_CONFIGURATIONS: ConfigMapping = {
+ python: {
+ selenium: {
+ pytest: {
+ instructions: instructions.pythonPytestSeleniumInstructions,
+ },
+ },
+ playwright: {
+ pytest: {
+ instructions: instructions.pythonPytestPlaywrightInstructions,
+ },
+ },
+ },
+ java: {
+ playwright: {
+ junit: { instructions: instructions.javaPlaywrightJunitInstructions },
+ },
+ },
+ nodejs: {
+ selenium: {
+ mocha: { instructions: instructions.mochaPercyAutomateInstructions },
+ jest: { instructions: instructions.jestPercyAutomateInstructions },
+ webdriverio: {
+ instructions: instructions.webdriverioPercyAutomateInstructions,
+ },
+ testcafe: {
+ instructions: instructions.testcafePercyAutomateInstructions,
+ },
+ },
+ playwright: {
+ mocha: { instructions: instructions.mochaPercyPlaywrightInstructions },
+ jest: { instructions: instructions.jestPercyAutomateInstructions },
+ },
+ },
+};
+
+/**
+ * Utility function to check if a given language, driver, and testing framework
+ * are supported by Percy Automate.
+ * This now expects the structure: language -> driver -> framework
+ */
+export function isPercyAutomateFrameworkSupported(
+ language: string,
+ driver: string,
+ framework: string,
+): boolean {
+ const languageConfig =
+ SUPPORTED_CONFIGURATIONS[language as keyof typeof SUPPORTED_CONFIGURATIONS];
+ if (!languageConfig) return false;
+ const driverConfig = languageConfig[driver as keyof typeof languageConfig];
+ if (!driverConfig) return false;
+ return !!driverConfig[framework as keyof typeof driverConfig];
+}
diff --git a/src/tools/sdk-utils/percy-automate/handler.ts b/src/tools/sdk-utils/percy-automate/handler.ts
new file mode 100644
index 00000000..f5e43135
--- /dev/null
+++ b/src/tools/sdk-utils/percy-automate/handler.ts
@@ -0,0 +1,43 @@
+import { RunTestsInstructionResult, RunTestsStep } from "../common/types.js";
+import { SetUpPercyInput } from "../common/schema.js";
+import { SUPPORTED_CONFIGURATIONS } from "./frameworks.js";
+import { SDKSupportedLanguage } from "../common/types.js";
+
+export function runPercyAutomateOnly(
+ input: SetUpPercyInput,
+ percyToken: string,
+): RunTestsInstructionResult {
+ const steps: RunTestsStep[] = [];
+
+ // Assume configuration is supported due to guardrails at orchestration layer
+ const languageConfig =
+ SUPPORTED_CONFIGURATIONS[input.detectedLanguage as SDKSupportedLanguage];
+ const driverConfig = languageConfig[input.detectedBrowserAutomationFramework];
+ const testingFrameworkConfig = driverConfig
+ ? driverConfig[input.detectedTestingFramework]
+ : undefined;
+
+ // Generate instructions for the supported configuration with project name
+ const instructions = testingFrameworkConfig
+ ? testingFrameworkConfig.instructions
+ : "";
+
+ // Prepend a step to set the Percy token in the environment
+ steps.push({
+ type: "instruction",
+ title: "Set Percy Token in Environment",
+ content: `Here is percy token if required {${percyToken}}`,
+ });
+
+ steps.push({
+ type: "instruction",
+ title: `Percy Automate Setup for ${input.detectedLanguage} with ${input.detectedTestingFramework}`,
+ content: instructions,
+ });
+
+ return {
+ steps,
+ requiresPercy: true,
+ missingDependencies: [],
+ };
+}
diff --git a/src/tools/sdk-utils/percy-automate/index.ts b/src/tools/sdk-utils/percy-automate/index.ts
new file mode 100644
index 00000000..230bfcb5
--- /dev/null
+++ b/src/tools/sdk-utils/percy-automate/index.ts
@@ -0,0 +1,2 @@
+// Percy Automate utilities
+export { runPercyAutomateOnly } from "./handler.js";
diff --git a/src/tools/sdk-utils/percy-automate/types.ts b/src/tools/sdk-utils/percy-automate/types.ts
new file mode 100644
index 00000000..c1860f80
--- /dev/null
+++ b/src/tools/sdk-utils/percy-automate/types.ts
@@ -0,0 +1,13 @@
+/**
+ * Type for Percy Automate configuration mapping.
+ * Structure: language -> driver -> testingFramework -> { instructions: string }
+ */
+export type ConfigMapping = {
+ [language: string]: {
+ [driver: string]: {
+ [framework: string]: {
+ instructions: string;
+ };
+ };
+ };
+};
diff --git a/src/tools/sdk-utils/percy/constants.ts b/src/tools/sdk-utils/percy-bstack/constants.ts
similarity index 72%
rename from src/tools/sdk-utils/percy/constants.ts
rename to src/tools/sdk-utils/percy-bstack/constants.ts
index 39dea6a1..7f9da914 100644
--- a/src/tools/sdk-utils/percy/constants.ts
+++ b/src/tools/sdk-utils/percy-bstack/constants.ts
@@ -1,10 +1,10 @@
-import { PercyConfigMapping } from "./types.js";
+import { PERCY_SNAPSHOT_INSTRUCTION } from "../common/constants.js";
-const javaSeleniumInstructions = `
+export const javaSeleniumInstructions = `
Import the BrowserStack Percy SDK in your test script:
Add the Percy import to your test file.
----STEP---
+${PERCY_SNAPSHOT_INSTRUCTION}
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.
@@ -35,6 +35,8 @@ 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,20 +49,20 @@ describe("sample Test", () => {
test("my test", async () => {
// ....
- await percy.snapshot(driver, "My Snapshot")
+ await percy.screenshot(driver, "My Snapshot")
// ....
});
})
\`\`\`
`;
-const webdriverioPercyInstructions = `
+export 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\`.
+- Set \`percyCaptureMode\`. The default \`manual\` as we are adding screenshot commands manually.
Here's how to modify the service configuration:
\`\`\`javascript
@@ -74,7 +76,7 @@ exports.config = {
{
// ... other service options
percy: true,
- percyCaptureMode: 'auto' // or 'manual', 'testcase', etc.
+ percyCaptureMode: 'manual' // or 'auto', etc.
},
],
],
@@ -89,6 +91,8 @@ exports.config = {
};
\`\`\`
+${PERCY_SNAPSHOT_INSTRUCTION}
+
---STEP---
Manually Capturing Screenshots (Optional):
@@ -117,11 +121,11 @@ describe("My WebdriverIO Test", () => {
\`\`\`
`;
-const csharpSeleniumInstructions = `
+export const csharpSeleniumInstructions = `
Import the BrowserStack Percy SDK in your test script:
Add the Percy import to your test file.
----STEP---
+${PERCY_SNAPSHOT_INSTRUCTION}
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,8 +134,6 @@ Here's an example:
\`\`\`csharp
using BrowserStackSDK.Percy;
-using NUnit.Framework;
-
namespace Tests;
public class MyTest
@@ -151,33 +153,3 @@ public class MyTest
}
\`\`\`
`;
-
-export const PERCY_INSTRUCTIONS: PercyConfigMapping = {
- 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,
- },
- },
- },
-};
diff --git a/src/tools/sdk-utils/percy-bstack/frameworks.ts b/src/tools/sdk-utils/percy-bstack/frameworks.ts
new file mode 100644
index 00000000..ed51557e
--- /dev/null
+++ b/src/tools/sdk-utils/percy-bstack/frameworks.ts
@@ -0,0 +1,29 @@
+import { ConfigMapping } from "./types.js";
+import * as constants from "./constants.js";
+
+export const PERCY_INSTRUCTIONS: ConfigMapping = {
+ java: {
+ selenium: {
+ testng: { instructions: constants.javaSeleniumInstructions },
+ cucumber: { instructions: constants.javaSeleniumInstructions },
+ junit4: { instructions: constants.javaSeleniumInstructions },
+ junit5: { instructions: constants.javaSeleniumInstructions },
+ selenide: { instructions: constants.javaSeleniumInstructions },
+ jbehave: { instructions: constants.javaSeleniumInstructions },
+ },
+ },
+ csharp: {
+ selenium: {
+ nunit: { instructions: constants.csharpSeleniumInstructions },
+ xunit: { instructions: constants.csharpSeleniumInstructions },
+ specflow: { instructions: constants.csharpSeleniumInstructions },
+ },
+ },
+ nodejs: {
+ selenium: {
+ mocha: { instructions: constants.nodejsSeleniumInstructions },
+ jest: { instructions: constants.nodejsSeleniumInstructions },
+ webdriverio: { instructions: constants.webdriverioPercyInstructions },
+ },
+ },
+};
diff --git a/src/tools/sdk-utils/percy-bstack/handler.ts b/src/tools/sdk-utils/percy-bstack/handler.ts
new file mode 100644
index 00000000..9ee200fc
--- /dev/null
+++ b/src/tools/sdk-utils/percy-bstack/handler.ts
@@ -0,0 +1,164 @@
+// Percy + BrowserStack SDK combined handler
+import { RunTestsInstructionResult, RunTestsStep } from "../common/types.js";
+import { RunTestsOnBrowserStackInput } from "../common/schema.js";
+import { getBrowserStackAuth } from "../../../lib/get-auth.js";
+import { getSDKPrefixCommand } from "../bstack/commands.js";
+import { generateBrowserStackYMLInstructions } from "../bstack/configUtils.js";
+import { getInstructionsForProjectConfiguration } from "../common/instructionUtils.js";
+import {
+ formatPercyInstructions,
+ getPercyInstructions,
+} from "./instructions.js";
+import { BrowserStackConfig } from "../../../lib/types.js";
+import {
+ SDKSupportedBrowserAutomationFramework,
+ SDKSupportedTestingFramework,
+ SDKSupportedLanguage,
+} from "../common/types.js";
+
+export function runPercyWithBrowserstackSDK(
+ input: RunTestsOnBrowserStackInput,
+ config: BrowserStackConfig,
+): RunTestsInstructionResult {
+ const steps: RunTestsStep[] = [];
+ const authString = getBrowserStackAuth(config);
+ const [username, accessKey] = authString.split(":");
+
+ // Check if Percy is supported for this configuration
+ const percyResult = getPercyInstructions(
+ input.detectedLanguage as SDKSupportedLanguage,
+ input.detectedBrowserAutomationFramework as SDKSupportedBrowserAutomationFramework,
+ input.detectedTestingFramework as SDKSupportedTestingFramework,
+ );
+
+ if (!percyResult) {
+ // Percy not supported for this configuration
+ return {
+ steps: [
+ {
+ type: "error",
+ title: "Percy Not Supported",
+ content: `Percy is not supported for this ${input.detectedBrowserAutomationFramework} framework configuration. Please use BrowserStack SDK only mode or try a different framework combination.`,
+ isError: true,
+ },
+ ],
+ requiresPercy: true,
+ shouldSkipFormatting: true,
+ missingDependencies: [],
+ };
+ }
+
+ // 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 && frameworkInstructions.setup) {
+ steps.push({
+ type: "instruction",
+ title: "Framework-Specific Setup",
+ content: frameworkInstructions.setup,
+ });
+ }
+
+ steps.push({
+ type: "instruction",
+ title: "Percy Setup (BrowserStack SDK + Percy)",
+ content: formatPercyInstructions(percyResult),
+ });
+
+ if (frameworkInstructions && frameworkInstructions.run) {
+ steps.push({
+ type: "instruction",
+ title: "Run the tests",
+ content: frameworkInstructions.run,
+ });
+ }
+
+ return {
+ steps,
+ requiresPercy: true,
+ missingDependencies: [],
+ };
+ }
+
+ // Default flow using browserstack.yml with Percy
+ 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 ymlInstructions = generateBrowserStackYMLInstructions(
+ {
+ platforms:
+ ((input as any).devices as string[][] | undefined)?.map((t) =>
+ t.join(" "),
+ ) || [],
+ enablePercy: true,
+ projectName: input.projectName,
+ },
+ config,
+ );
+
+ if (ymlInstructions) {
+ steps.push({
+ type: "instruction",
+ title: "Configure browserstack.yml",
+ content: ymlInstructions,
+ });
+ }
+
+ const frameworkInstructions = getInstructionsForProjectConfiguration(
+ input.detectedBrowserAutomationFramework as SDKSupportedBrowserAutomationFramework,
+ input.detectedTestingFramework as SDKSupportedTestingFramework,
+ input.detectedLanguage as SDKSupportedLanguage,
+ username,
+ accessKey,
+ );
+
+ if (frameworkInstructions && frameworkInstructions.setup) {
+ steps.push({
+ type: "instruction",
+ title: "Framework-Specific Setup",
+ content: frameworkInstructions.setup,
+ });
+ }
+
+ steps.push({
+ type: "instruction",
+ title: "Percy Setup (BrowserStack SDK + Percy)",
+ content: formatPercyInstructions(percyResult),
+ });
+
+ if (frameworkInstructions && frameworkInstructions.run) {
+ steps.push({
+ type: "instruction",
+ title: "Run the tests",
+ content: frameworkInstructions.run,
+ });
+ }
+
+ return {
+ steps,
+ requiresPercy: true,
+ missingDependencies: [],
+ };
+}
diff --git a/src/tools/sdk-utils/percy-bstack/index.ts b/src/tools/sdk-utils/percy-bstack/index.ts
new file mode 100644
index 00000000..6338ed2e
--- /dev/null
+++ b/src/tools/sdk-utils/percy-bstack/index.ts
@@ -0,0 +1,8 @@
+// Percy + BrowserStack SDK utilities
+export { runPercyWithBrowserstackSDK } from "./handler.js";
+export {
+ getPercyInstructions,
+ formatPercyInstructions,
+} from "./instructions.js";
+export { PERCY_INSTRUCTIONS } from "./frameworks.js";
+export type { ConfigMapping } from "./types.js";
diff --git a/src/tools/sdk-utils/percy/instructions.ts b/src/tools/sdk-utils/percy-bstack/instructions.ts
similarity index 60%
rename from src/tools/sdk-utils/percy/instructions.ts
rename to src/tools/sdk-utils/percy-bstack/instructions.ts
index f642efa5..dab7941b 100644
--- a/src/tools/sdk-utils/percy/instructions.ts
+++ b/src/tools/sdk-utils/percy-bstack/instructions.ts
@@ -1,19 +1,17 @@
+// Percy + BrowserStack SDK instructions and utilities
import {
SDKSupportedBrowserAutomationFramework,
SDKSupportedLanguage,
SDKSupportedTestingFramework,
-} from "../types.js";
-import { PERCY_INSTRUCTIONS } from "./constants.js";
-import { PercyInstructions } from "./types.js";
+} from "../common/types.js";
+import { PERCY_INSTRUCTIONS } from "./frameworks.js";
-/**
- * Retrieves Percy-specific instructions for a given language and framework.
- */
+// Retrieves Percy-specific instructions for a given language and framework
export function getPercyInstructions(
language: SDKSupportedLanguage,
automationFramework: SDKSupportedBrowserAutomationFramework,
testingFramework: SDKSupportedTestingFramework,
-): PercyInstructions | null {
+): { instructions: string } | null {
const langConfig = PERCY_INSTRUCTIONS[language];
if (!langConfig) {
return null;
@@ -32,14 +30,12 @@ export function getPercyInstructions(
return percyInstructions;
}
-/**
- * Formats the retrieved Percy instructions into a user-friendly string.
- */
-export function formatPercyInstructions(
- instructions: PercyInstructions,
-): string {
- return `\n\n## Percy Visual Testing Setup
+// Formats the retrieved Percy instructions into a user-friendly string
+export function formatPercyInstructions(instructions: {
+ instructions: string;
+}): string {
+ return `---STEP--- 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}
+${instructions.instructions}
`;
}
diff --git a/src/tools/sdk-utils/percy-bstack/types.ts b/src/tools/sdk-utils/percy-bstack/types.ts
new file mode 100644
index 00000000..b45f9628
--- /dev/null
+++ b/src/tools/sdk-utils/percy-bstack/types.ts
@@ -0,0 +1,14 @@
+/**
+ * Type for Percy + BrowserStack SDK configuration mapping.
+ * Structure: language -> automationFramework -> testingFramework -> { instructions: (bsdkToken: string) => string }
+ */
+
+export type ConfigMapping = {
+ [language: string]: {
+ [automationFramework: string]: {
+ [testingFramework: string]: {
+ instructions: string;
+ };
+ };
+ };
+};
diff --git a/src/tools/sdk-utils/percy-web/constants.ts b/src/tools/sdk-utils/percy-web/constants.ts
new file mode 100644
index 00000000..fbbb2b89
--- /dev/null
+++ b/src/tools/sdk-utils/percy-web/constants.ts
@@ -0,0 +1,971 @@
+import { PERCY_SNAPSHOT_INSTRUCTION } from "../common/constants.js";
+export const percyReviewSnapshotsStep = `
+---STEP---
+Review the snapshots
+ - Go to your Percy project on https://percy.io to review snapshots and approve/reject any visual changes.
+`;
+
+export const pythonInstructionsSnapshot = `
+Example:
+\`\`\`python
+- Import the Percy snapshot helper:
+from selenium import webdriver
+from percy import percy_snapshot
+
+driver = webdriver.Chrome()
+driver.get('http://localhost:8000')
+percy_snapshot(driver, 'Home page')
+# ... more test steps ...
+percy_snapshot(driver, 'After login')
+\`\`\`
+`;
+
+export const nodejsInstructionsSnapshot = `
+- Import the Percy snapshot helper:
+ const { percySnapshot } = require('@percy/selenium-js');
+ - In your test, take snapshots like this:
+ await percySnapshot(driver, "Your snapshot name");
+
+Example:
+\`\`\`javascript
+const { Builder } = require('selenium-webdriver');
+const percySnapshot = require('@percy/selenium-webdriver');
+
+const driver = await new Builder().forBrowser('chrome').build();
+await driver.get('http://localhost:8000');
+await percySnapshot(driver, 'Home page');
+\`\`\`
+`;
+
+export const javaInstructionsSnapshot = `
+ - Import the Percy snapshot helper:
+ import io.percy.selenium.Percy;
+ - In your test, take snapshots like this:
+ Percy percy = new Percy(driver);
+ percy.snapshot("Your snapshot name");
+ Example:
+\`\`\`java
+import org.openqa.selenium.WebDriver;
+import org.openqa.selenium.chrome.ChromeDriver;
+import io.percy.selenium.Percy;
+
+public class PercyExample {
+ public static void main(String[] args) {
+ WebDriver driver = new ChromeDriver();
+ driver.get("http://localhost:8000");
+ Percy percy = new Percy(driver);
+ percy.snapshot("Home page");
+ driver.quit();
+ }
+}
+\`\`\``;
+
+export const rubyInstructionsSnapshot = `
+ - Require the Percy snapshot helper:
+ require 'percy'
+ - In your test, take snapshots like this:
+ Percy.snapshot(page, 'Your snapshot name')
+
+Example:
+\`\`\`ruby
+require 'selenium-webdriver'
+require 'percy'
+
+driver = Selenium::WebDriver.for :chrome
+driver.get('http://localhost:8000')
+Percy.snapshot(driver, 'Your snapshot name')
+driver.quit
+\`\`\`
+`;
+
+export const rubyCapybaraInstructionsSnapshot = `
+ - In your test setup file, require percy/capybara:
+ require 'percy/capybara'
+ - In your test, take snapshots like this:
+ page.percy_snapshot('Capybara snapshot')
+
+Example:
+\`\`\`ruby
+require 'percy/capybara'
+
+describe 'my feature', type: :feature do
+ it 'renders the page' do
+ visit 'https://example.com'
+ page.percy_snapshot('Capybara snapshot')
+ end
+end
+\`\`\`
+
+ - The snapshot method arguments are:
+ page.percy_snapshot(name[, options])
+ name - The snapshot name; must be unique to each snapshot; defaults to the test title
+ options - See per-snapshot configuration options
+`;
+
+export const csharpInstructionsSnapshot = `
+ - Import the Percy snapshot helper:
+ using PercyIO.Selenium;
+ - In your test, take snapshots like this:
+ Percy.Snapshot(driver,"Your snapshot name");
+
+Example:
+\`\`\`csharp
+using OpenQA.Selenium;
+using OpenQA.Selenium.Chrome;
+using PercyIO.Selenium;
+
+class PercyExample
+{
+ static void Main()
+ {
+ IWebDriver driver = new ChromeDriver();
+ driver.Navigate().GoToUrl("http://localhost:8000");
+ Percy.Snapshot(driver,"Empty Todo State");
+ driver.Quit();
+ }
+}
+\`\`\`
+`;
+
+export const javaPlaywrightInstructionsSnapshot = `
+ - Import the Percy library and use the snapshot method:
+ percy.snapshot("snapshot_1");
+ - You can also pass options:
+ Map options = new HashMap<>();
+ options.put("testCase", "Should add product to cart");
+ percy.snapshot("snapshot_2", options);
+
+Example:
+\`\`\`java
+import com.microsoft.playwright.*;
+import io.percy.playwright.*;
+
+public class PercyPlaywrightExample {
+ public static void main(String[] args) {
+ try (Playwright playwright = Playwright.create()) {
+ Browser browser = playwright.chromium().launch();
+ Page page = browser.newPage();
+ Percy percy = new Percy(page);
+
+ page.navigate("http://localhost:8000");
+ percy.snapshot("Home page");
+
+ // ... more test steps ...
+ percy.snapshot("After login");
+
+ browser.close();
+ }
+ }
+}
+\`\`\`
+`;
+
+export const nodejsPlaywrightInstructionsSnapshot = `
+ - Import the Percy snapshot helper:
+ const percySnapshot = require('@percy/playwright');
+ - In your test, take snapshots like this:
+ await percySnapshot(page, "Your snapshot name");
+
+Example:
+\`\`\`javascript
+const { chromium } = require('playwright');
+const percySnapshot = require('@percy/playwright');
+
+(async () => {
+ const browser = await chromium.launch();
+ const page = await browser.newPage();
+ await page.goto('http://example.com/', { waitUntil: 'networkidle' });
+ await percySnapshot(page, 'Example Site');
+ await browser.close();
+})();
+\`\`\`
+`;
+
+export const nodejsWebdriverioInstructionsSnapshot = `
+ - Import the Percy snapshot helper:
+ const percySnapshot = require('@percy/selenium-webdriver');
+ - In your test, take snapshots like this:
+ await percySnapshot(driver, "Your snapshot name");
+
+Example:
+\`\`\`javascript
+const { remote } = require('webdriverio');
+const percySnapshot = require('@percy/selenium-webdriver');
+
+(async () => {
+ const browser = await remote({
+ logLevel: 'error',
+ capabilities: { browserName: 'chrome' }
+ });
+
+ await browser.url('https://example.com');
+ await percySnapshot(browser, 'WebdriverIO example');
+ await browser.deleteSession();
+})();
+\`\`\`
+`;
+
+export const nodejsEmberInstructionsSnapshot = `
+ - Import the Percy snapshot helper:
+ import percySnapshot from '@percy/ember';
+ - In your test, take snapshots like this:
+ await percySnapshot('My Snapshot');
+
+Example:
+\`\`\`javascript
+import percySnapshot from '@percy/ember';
+describe('My ppp', () => {
+ // ...app setup
+ it('about page should look good', async () => {
+ await visit('/about');
+ await percySnapshot('My Snapshot');
+ });
+});
+\`\`\`
+
+ - The snapshot method arguments are:
+ percySnapshot(name[, options])
+ name - The snapshot name; must be unique to each snapshot; defaults to the test title
+ options - See per-snapshot configuration options
+`;
+
+export const nodejsCypressInstructionsSnapshot = `
+ - Import the Percy snapshot helper in your cypress/support/e2e.js file:
+ import '@percy/cypress';
+ - If you’re using TypeScript, include "types": ["cypress", "@percy/cypress"] in your tsconfig.json file.
+ - In your test, take snapshots like this:
+ cy.percySnapshot();
+
+Example:
+\`\`\`javascript
+import '@percy/cypress';
+
+describe('Integration test with visual testing', function() {
+ it('Loads the homepage', function() {
+ // Load the page or perform any other interactions with the app.
+ cy.visit('');
+ // Take a snapshot for visual diffing
+ cy.percySnapshot();
+ });
+});
+\`\`\`
+
+ - The snapshot method arguments are:
+ cy.percySnapshot([name][, options])
+ name - The snapshot name; must be unique to each snapshot; defaults to the test title
+ options - See per-snapshot configuration options
+
+ - For example:
+ cy.percySnapshot();
+ cy.percySnapshot('Homepage test');
+ cy.percySnapshot('Homepage responsive test', { widths: [768, 992, 1200] });
+`;
+
+export const nodejsPuppeteerInstructionsSnapshot = `
+ - Import the Percy snapshot helper:
+ const percySnapshot = require('@percy/puppeteer');
+ - In your test, take snapshots like this:
+ await percySnapshot(page, 'Snapshot name');
+
+Example:
+\`\`\`javascript
+const puppeteer = require('puppeteer');
+const percySnapshot = require('@percy/puppeteer');
+
+describe('Integration test with visual testing', function() {
+ it('Loads the homepage', async function() {
+ const browser = await puppeteer.launch();
+ const page = await browser.newPage();
+ await page.goto('https://example.com');
+ await percySnapshot(page, this.test.fullTitle());
+ await browser.close();
+ });
+});
+\`\`\`
+
+ - The snapshot method arguments are:
+ percySnapshot(page, name[, options])
+ page (required) - A puppeteer page instance
+ name (required) - The snapshot name; must be unique to each snapshot
+ options - See per-snapshot configuration options
+
+ - For example:
+ percySnapshot(page, 'Homepage test');
+ percySnapshot(page, 'Homepage responsive test', { widths: [768, 992, 1200] });
+`;
+
+export const nodejsNightmareInstructionsSnapshot = `
+ - Import the Percy snapshot helper:
+ const Nightmare = require('nightmare');
+ const percySnapshot = require('@percy/nightmare');
+ - In your test, take snapshots like this:
+ .use(percySnapshot('Snapshot name'))
+
+Example:
+\`\`\`javascript
+const Nightmare = require('nightmare');
+const percySnapshot = require('@percy/nightmare');
+
+Nightmare()
+ .goto('http://example.com')
+ // ... other actions ...
+ .use(percySnapshot('Example Snapshot'))
+ // ... more actions ...
+ .end()
+ .then(() => {
+ // ...
+ });
+\`\`\`
+
+ - The snapshot method arguments are:
+ percySnapshot(name[, options])
+ name (required) - The snapshot name; must be unique to each snapshot
+ options - See per-snapshot configuration options
+`;
+
+export const nodejsNightwatchInstructionsSnapshot = `
+ - Import the Percy library and add the path exported by @percy/nightwatch to your Nightwatch configuration’s custom_commands_path property:
+ const percy = require('@percy/nightwatch');
+ module.exports = {
+ // ...
+ custom_commands_path: [percy.path],
+ // ...
+ };
+ - In your test, take snapshots like this:
+ browser.percySnapshot('Snapshot name');
+
+Example:
+\`\`\`javascript
+const percy = require('@percy/nightwatch');
+module.exports = {
+ // ...
+ custom_commands_path: [percy.path],
+ // ...
+};
+
+// Example test
+module.exports = {
+ 'Snapshots pages': function(browser) {
+ browser
+ .url('http://example.com')
+ .assert.containsText('h1', 'Example Domain')
+ .percySnapshot('Example snapshot');
+ browser
+ .url('http://google.com')
+ .assert.elementPresent('img[alt="Google"]')
+ .percySnapshot('Google homepage');
+ browser.end();
+ }
+};
+\`\`\`
+
+ - The snapshot method arguments are:
+ percySnapshot([name][, options])
+ name (required) - The snapshot name; must be unique to each snapshot
+ options - See per-snapshot configuration options
+`;
+
+export const nodejsProtractorInstructionsSnapshot = `
+ - Import the Percy snapshot helper:
+ import percySnapshot from '@percy/protractor';
+ - In your test, take snapshots like this:
+ await percySnapshot('Snapshot name');
+ // or
+ await percySnapshot(browser, 'Snapshot name');
+
+Example:
+\`\`\`javascript
+import percySnapshot from '@percy/protractor';
+describe('angularjs homepage', function() {
+ it('should greet the named user', async function() {
+ await browser.get('https://www.angularjs.org');
+ await percySnapshot('AngularJS homepage');
+ await element(by.model('yourName')).sendKeys('Percy');
+ var greeting = element(by.binding('yourName'));
+ expect(await greeting.getText()).toEqual('Hello Percy!');
+ await percySnapshot('AngularJS homepage greeting');
+ });
+});
+\`\`\`
+
+ - The snapshot method arguments are:
+ percySnapshot(name[, options])
+ Standalone mode:
+ percySnapshot(browser, name[, options])
+ browser (required) - The Protractor browser object
+ name (required) - The snapshot name; must be unique to each snapshot
+ options - See per-snapshot configuration options
+`;
+
+export const nodejsTestcafeInstructionsSnapshot = `
+ - Import the Percy snapshot helper:
+ import percySnapshot from '@percy/testcafe';
+ - In your test, take snapshots like this:
+ await percySnapshot(t, 'Snapshot name');
+
+Example:
+\`\`\`javascript
+import percySnapshot from '@percy/testcafe';
+fixture('MyFixture')
+ .page('https://devexpress.github.io/testcafe/example');
+test('Test1', async t => {
+ await t.typeText('#developer-name', 'John Doe');
+ await percySnapshot(t, 'TestCafe Example');
+});
+\`\`\`
+
+ - The snapshot method arguments are:
+ percySnapshot(t, name[, options])
+ t (required) - The test controller instance passed from test
+ name (required) - The snapshot name; must be unique to each snapshot
+ options - See per-snapshot configuration options
+`;
+
+export const nodejsGatsbyInstructionsSnapshot = `
+ - Add the Percy plugin to your gatsby-config.js file:
+ module.exports = {
+ plugins: [\`gatsby-plugin-percy\`]
+ }
+
+ - The plugin will take snapshots of discovered pages during the build process.
+
+ - Example gatsby-config.js with options:
+\`\`\`javascript
+module.exports = {
+ plugins: [{
+ resolve: \`gatsby-plugin-percy\`,
+ options: {
+ // gatsby specific options
+ query: \`{
+ allSitePage { nodes { path } }
+ allOtherPage { nodes { path } }
+ }\`,
+ resolvePages: ({
+ allSitePage: { nodes: allPages },
+ allOtherPage: { nodes: otherPages }
+ }) => {
+ return [...allPages, ...otherPages]
+ .map(({ path }) => path);
+ },
+ // percy static snapshot options
+ exclude: [
+ '/dev-404-page/',
+ '/offline-plugin-app-shell-fallback/'
+ ],
+ overrides: [{
+ include: '/foobar/',
+ waitForSelector: '.done-loading',
+ additionalSnapshots: [{
+ suffix: ' - after btn click',
+ execute: () => document.querySelector('.btn').click()
+ }]
+ }]
+ }
+ }]
+}
+\`\`\`
+`;
+
+export const nodejsStorybookInstructionsSnapshot = `
+ - Add Percy parameters to your stories to customize snapshots:
+\`\`\`js
+MyStory.parameters = {
+ percy: {
+ name: 'My snapshot',
+ additionalSnapshots: [
+ { prefix: '[Dark mode] ', args: { colorScheme: 'dark' } },
+ { suffix: ' with globals', globals: { textDirection: 'rtl' } },
+ { name: 'Search snapshot', queryParams: { search: 'foobar' } }
+ ]
+ }
+};
+\`\`\`
+ - Use argument names and values defined in your codebase.
+`;
+
+export const pythonPlaywrightInstructionsSnapshot = `
+ - Import the Percy snapshot helper and use the snapshot method:
+ percy_snapshot(page, name="Your snapshot name")
+ - You can also use:
+ percy_screenshot(page, name="Your snapshot name", options={})
+
+Example:
+\`\`\`python
+from playwright.sync_api import sync_playwright
+from percy import percy_snapshot
+
+with sync_playwright() as p:
+ browser = p.chromium.launch()
+ page = browser.new_page()
+ page.goto("http://localhost:8000")
+ percy_snapshot(page, name="Home page")
+
+ # ... more test steps ...
+ percy_snapshot(page, name="After login")
+
+ browser.close()
+\`\`\`
+`;
+
+export const csharpPlaywrightInstructionsSnapshot = `
+ - Import the Percy snapshot helper and use the snapshot method:
+ Percy.Snapshot(page, "Your snapshot name");
+ - You can also pass options:
+ Percy.Snapshot(page, "Your snapshot name", options);
+
+Example:
+\`\`\`csharp
+using Microsoft.Playwright;
+using PercyIO.Playwright;
+
+class PercyPlaywrightExample
+{
+ public static async Task Main()
+ {
+ using var playwright = await Playwright.CreateAsync();
+ var browser = await playwright.Chromium.LaunchAsync();
+ var page = await browser.NewPageAsync();
+
+ await page.GotoAsync("http://localhost:8000");
+ Percy.Snapshot(page, "Home page");
+
+ // ... more test steps ...
+ Percy.Snapshot(page, "After login");
+
+ await browser.CloseAsync();
+ }
+}
+\`\`\`
+`;
+
+export const pythonInstructions = `
+Install Percy dependencies
+ - Install Percy CLI:
+ npm install --save-dev @percy/cli
+ - Install Percy Selenium Python package:
+ pip install percy-selenium
+If faced any issue create a virtual environment and proceed.
+Update your Python Selenium script
+${PERCY_SNAPSHOT_INSTRUCTION}
+${pythonInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- python tests.py').
+${percyReviewSnapshotsStep}
+`;
+
+export const nodejsInstructions = `
+---STEP---
+Install Percy dependencies
+ - Install Percy CLI:
+ npm install --save-dev @percy/cli
+ - Install Percy SDK for Node.js:
+ npm install @percy/selenium-webdriver
+---STEP---
+Update your Node.js Selenium script
+${PERCY_SNAPSHOT_INSTRUCTION}
+${nodejsInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- node script.js').
+
+${percyReviewSnapshotsStep}
+`;
+
+export const javaInstructions = `
+---STEP---
+Add Percy dependencies to your project
+ - For Maven, add to your pom.xml:
+
+ io.percy
+ percy-java-selenium
+ 1.0.0
+
+ - For Gradle, add to your build.gradle:
+ implementation 'io.percy:percy-java-selenium:1.0.0'
+ - For CLI usage, install Percy CLI:
+ npm install --save-dev @percy/cli
+
+---STEP---
+Update your Java Selenium test
+${PERCY_SNAPSHOT_INSTRUCTION}
+${javaInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- mvn test').
+
+${percyReviewSnapshotsStep}
+`;
+
+export const rubyInstructions = `
+---STEP---
+Install Percy dependencies
+ - Install Percy CLI:
+ npm install --save-dev @percy/cli
+ - Install Percy Ruby Selenium gem:
+ gem install percy-selenium
+
+---STEP---
+Update your Ruby Selenium test
+${PERCY_SNAPSHOT_INSTRUCTION}
+${rubyInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- bundle exec rspec').
+
+${percyReviewSnapshotsStep}
+`;
+
+// Percy Capybara instructions for Ruby
+export const rubyCapybaraInstructions = `
+---STEP---
+Install Percy dependencies
+ - Install Percy CLI:
+ npm install --save-dev @percy/cli
+ - Install Percy Capybara gem:
+ gem install percy-capybara
+
+---STEP---
+Update your Capybara or Rails test script
+${PERCY_SNAPSHOT_INSTRUCTION}
+${rubyCapybaraInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- bundle exec rspec').
+
+${percyReviewSnapshotsStep}
+`;
+
+export const csharpInstructions = `
+Install Percy CLI by running the following command:
+npm install --save-dev @percy/cli
+
+---STEP---
+Add Percy dependencies to your project
+ - Add the Percy .NET Selenium NuGet package:
+ dotnet add package PercyIO.Selenium
+
+---STEP---
+Update your C# Selenium test
+${PERCY_SNAPSHOT_INSTRUCTION}
+${csharpInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- dotnet test').
+
+${percyReviewSnapshotsStep}
+`;
+
+export const javaPlaywrightInstructions = `
+Install Percy dependencies
+ - For Maven, add to your pom.xml:
+
+ io.percy
+ percy-playwright-java
+ 1.0.0
+
+
+---STEP---
+Update your Java Playwright test
+${PERCY_SNAPSHOT_INSTRUCTION}
+${javaPlaywrightInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g. npx percy exec -- ).
+
+${percyReviewSnapshotsStep}
+`;
+
+export const nodejsPlaywrightInstructions = `
+Install Percy dependencies
+ - Install Percy Playwright SDK:
+ npm install @percy/playwright
+
+---STEP---
+Update your Playwright JavaScript test
+${PERCY_SNAPSHOT_INSTRUCTION}
+${nodejsPlaywrightInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., npx percy exec -- ).
+${percyReviewSnapshotsStep}
+`;
+
+// Percy WebdriverIO instructions for JavaScript
+export const nodejsWebdriverioInstructions = `
+---STEP---
+Install Percy dependencies
+ - Install Percy CLI:
+ npm install --save-dev @percy/cli
+ - Install Percy Selenium Webdriver package:
+ npm install --save-dev @percy/selenium-webdriver
+
+---STEP---
+Update your WebdriverIO test script
+${PERCY_SNAPSHOT_INSTRUCTION}
+${nodejsWebdriverioInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- wdio run wdio.conf.js').
+
+${percyReviewSnapshotsStep}
+`;
+
+// Percy Ember instructions for JavaScript
+export const nodejsEmberInstructions = `
+---STEP---
+Install Percy dependencies
+ - Install Percy CLI and Ember SDK:
+ npm install --save-dev @percy/cli @percy/ember
+
+---STEP---
+Update your Ember test script
+${PERCY_SNAPSHOT_INSTRUCTION}
+${nodejsEmberInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- ember test').
+
+${percyReviewSnapshotsStep}
+`;
+
+// Percy Cypress instructions for JavaScript
+export const nodejsCypressInstructions = `
+---STEP---
+Install Percy dependencies
+ - Install Percy CLI and Cypress SDK:
+ npm install --save-dev @percy/cli @percy/cypress
+
+---STEP---
+Update your Cypress test script
+${PERCY_SNAPSHOT_INSTRUCTION}
+${nodejsCypressInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- cypress run').
+
+${percyReviewSnapshotsStep}
+`;
+
+// Percy Puppeteer instructions for JavaScript
+export const nodejsPuppeteerInstructions = `
+---STEP---
+Install Percy dependencies
+ - Install Percy CLI and Puppeteer SDK:
+ npm install --save-dev @percy/cli @percy/puppeteer
+
+---STEP---
+Update your Puppeteer test script
+${PERCY_SNAPSHOT_INSTRUCTION}
+${nodejsPuppeteerInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- ').
+
+${percyReviewSnapshotsStep}
+`;
+
+// Percy Nightmare instructions for JavaScript
+export const nodejsNightmareInstructions = `
+---STEP---
+Install Percy dependencies
+ - Install Percy CLI and Nightmare SDK:
+ npm install --save-dev @percy/cli @percy/nightmare
+
+---STEP---
+Update your Nightmare test script
+${PERCY_SNAPSHOT_INSTRUCTION}
+${nodejsNightmareInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- node script.js').
+
+${percyReviewSnapshotsStep}
+`;
+
+// Percy Nightwatch instructions for JavaScript
+export const nodejsNightwatchInstructions = `
+---STEP---
+Install Percy dependencies
+ - Install Percy CLI and Nightwatch SDK:
+ npm install --save-dev @percy/cli @percy/nightwatch
+
+---STEP---
+Update your Nightwatch configuration and test script
+${PERCY_SNAPSHOT_INSTRUCTION}
+${nodejsNightwatchInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- nightwatch').
+
+${percyReviewSnapshotsStep}
+`;
+
+// Percy Protractor instructions for JavaScript
+export const nodejsProtractorInstructions = `
+---STEP---
+Install Percy dependencies
+ - Install Percy CLI and Protractor SDK:
+ npm install --save-dev @percy/cli @percy/protractor
+
+---STEP---
+Update your Protractor test script
+${PERCY_SNAPSHOT_INSTRUCTION}
+${nodejsProtractorInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- protractor conf.js').
+
+${percyReviewSnapshotsStep}
+`;
+
+// Percy TestCafe instructions for JavaScript
+export const nodejsTestcafeInstructions = `
+---STEP---
+Install Percy dependencies
+ - Install Percy CLI and TestCafe SDK:
+ npm install --save-dev @percy/cli @percy/testcafe
+
+---STEP---
+Update your TestCafe test script
+${PERCY_SNAPSHOT_INSTRUCTION}
+${nodejsTestcafeInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- testcafe chrome:headless tests').
+${percyReviewSnapshotsStep}
+`;
+
+// Percy Gatsby instructions for JavaScript
+export const nodejsGatsbyInstructions = `
+---STEP---
+Install Percy dependencies
+ - Install Percy CLI and Gatsby plugin:
+ npm install --save @percy/cli gatsby-plugin-percy
+
+---STEP---
+Update your Gatsby configuration
+${PERCY_SNAPSHOT_INSTRUCTION}
+${nodejsGatsbyInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g., 'npx percy exec -- gatsby build').
+${percyReviewSnapshotsStep}
+`;
+
+// Percy Storybook instructions for JavaScript
+export const nodejsStorybookInstructions = `
+---STEP---
+Install Percy dependencies
+ - Install Percy CLI and Storybook SDK:
+ npm install --save-dev @percy/cli @percy/storybook
+
+---STEP---
+Update your Storybook stories
+${PERCY_SNAPSHOT_INSTRUCTION}
+${nodejsStorybookInstructionsSnapshot}
+
+---STEP---
+Run Percy with your Storybook
+ - With a static Storybook build:
+ percy storybook ./storybook-build
+ - With a local or live Storybook URL:
+ percy storybook http://localhost:9009
+ percy storybook https://storybook.foobar.com
+ - Automatically run start-storybook:
+ Run this scan using tool runPercyScan with 'npx percy exec -- percy storybook:start --port=9009'.
+
+${percyReviewSnapshotsStep}
+`;
+
+export const pythonPlaywrightInstructions = `
+---STEP---
+Create a Percy project
+ - Sign in to Percy and create a project of type "Web". Name the project and note the generated token.
+
+---STEP---
+Set the project token as an environment variable
+ - On macOS/Linux:
+ export PERCY_TOKEN=""
+ - On Windows PowerShell:
+ $env:PERCY_TOKEN=""
+ - On Windows CMD:
+ set PERCY_TOKEN=
+
+---STEP---
+Install Percy dependencies
+ - Install Percy Playwright SDK:
+ pip install percy-playwright
+
+---STEP---
+Update your Playwright Python test
+${PERCY_SNAPSHOT_INSTRUCTION}
+${pythonPlaywrightInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g. npx percy exec -- ).
+${percyReviewSnapshotsStep}
+`;
+
+export const csharpPlaywrightInstructions = `
+Install Percy dependencies
+ - Add the Percy Playwright NuGet package:
+
+
+---STEP---
+Update your Playwright .NET test
+${PERCY_SNAPSHOT_INSTRUCTION}
+${csharpPlaywrightInstructionsSnapshot}
+
+---STEP---
+To run the Percy build, call the tool runPercyScan with the appropriate test command (e.g. npx percy exec -- ).
+${percyReviewSnapshotsStep}
+`;
+
+export function getFrameworkTestCommand(
+ language: string,
+ framework: string,
+): string {
+ const percyPrefix = "npx percy exec --labels=mcp --";
+
+ const nodeCommands: Record = {
+ cypress: "cypress run",
+ playwright: "playwright test",
+ webdriverio: "wdio",
+ puppeteer: "node",
+ testcafe: "testcafe",
+ nightwatch: "nightwatch",
+ protractor: "protractor",
+ gatsby: "gatsby build",
+ storybook: "storybook build",
+ ember: "ember test",
+ default: "npm test",
+ };
+
+ const languageMap: Record = {
+ python: "python -m pytest",
+ java: "mvn test",
+ ruby: "bundle exec rspec",
+ csharp: "dotnet test",
+ };
+
+ if (language === "nodejs") {
+ const cmd = nodeCommands[framework] ?? nodeCommands.default;
+ return `${percyPrefix} ${cmd}`;
+ }
+
+ const cmd = languageMap[language];
+ return cmd ? `${percyPrefix} ${cmd}` : `${percyPrefix} `;
+}
+
+export const PERCY_FALLBACK_STEPS = [
+ `Attempt to infer the project's test command from context (high confidence commands first):
+- Node.js: npm test, cypress run, npx playwright test, npx wdio, npx testcafe, npx nightwatch, npx protractor, ember test, npx gatsby build, npx storybook build
+- Python: python -m pytest
+- Java: mvn test
+- Ruby: bundle exec rspec
+- C#: dotnet test
+or from package.json scripts`,
+ `Wrap the inferred command with Percy along with label: \nnpx percy exec --labels=mcp -- `,
+ `If the test command cannot be inferred confidently, ask the user directly for the correct test command.`,
+];
diff --git a/src/tools/sdk-utils/percy-web/fetchPercyToken.ts b/src/tools/sdk-utils/percy-web/fetchPercyToken.ts
new file mode 100644
index 00000000..b6ed135f
--- /dev/null
+++ b/src/tools/sdk-utils/percy-web/fetchPercyToken.ts
@@ -0,0 +1,55 @@
+import { PercyIntegrationTypeEnum } from "../common/types.js";
+
+let globalPercyToken: string | null = null;
+let globalProjectName: string | null = null;
+
+async function fetchTokenFromAPI(
+ projectName: string,
+ authorization: string,
+ options: { type?: PercyIntegrationTypeEnum } = {},
+): Promise {
+ const authHeader = `Basic ${Buffer.from(authorization).toString("base64")}`;
+ const baseUrl =
+ "https://api.browserstack.com/api/app_percy/get_project_token";
+ const params = new URLSearchParams({ name: projectName });
+
+ if (options.type) {
+ params.append("type", options.type);
+ }
+
+ const url = `${baseUrl}?${params.toString()}`;
+ const response = await fetch(url, { headers: { Authorization: authHeader } });
+
+ if (!response.ok) {
+ throw new Error(`Failed to fetch Percy token (status: ${response.status})`);
+ }
+
+ const data = await response.json();
+
+ if (!data?.token || !data?.success) {
+ throw new Error(
+ "Project exists but is likely set up for Automate. Please use a different project name.",
+ );
+ }
+
+ return data.token;
+}
+
+export async function fetchPercyToken(
+ projectName: string,
+ authorization: string,
+ options: { type?: PercyIntegrationTypeEnum } = {},
+): Promise {
+ if (globalProjectName !== projectName) {
+ globalProjectName = projectName;
+ globalPercyToken = null;
+ }
+
+ if (globalPercyToken) {
+ return globalPercyToken;
+ }
+
+ const token = await fetchTokenFromAPI(projectName, authorization, options);
+ globalPercyToken = token;
+ return token;
+}
diff --git a/src/tools/sdk-utils/percy-web/frameworks.ts b/src/tools/sdk-utils/percy-web/frameworks.ts
new file mode 100644
index 00000000..4484eed9
--- /dev/null
+++ b/src/tools/sdk-utils/percy-web/frameworks.ts
@@ -0,0 +1,109 @@
+import { ConfigMapping } from "./types.js";
+import * as constants from "./constants.js";
+
+export const SUPPORTED_CONFIGURATIONS: ConfigMapping = {
+ python: {
+ selenium: {
+ instructions: constants.pythonInstructions,
+ snapshotInstruction: constants.pythonInstructionsSnapshot,
+ },
+ playwright: {
+ instructions: constants.pythonPlaywrightInstructions,
+ snapshotInstruction: constants.pythonPlaywrightInstructionsSnapshot,
+ },
+ },
+ nodejs: {
+ selenium: {
+ instructions: constants.nodejsInstructions,
+ snapshotInstruction: constants.nodejsInstructionsSnapshot,
+ },
+ playwright: {
+ instructions: constants.nodejsPlaywrightInstructions,
+ snapshotInstruction: constants.nodejsPlaywrightInstructionsSnapshot,
+ },
+ webdriverio: {
+ instructions: constants.nodejsWebdriverioInstructions,
+ snapshotInstruction: constants.nodejsWebdriverioInstructionsSnapshot,
+ },
+ ember: {
+ instructions: constants.nodejsEmberInstructions,
+ snapshotInstruction: constants.nodejsEmberInstructionsSnapshot,
+ },
+ cypress: {
+ instructions: constants.nodejsCypressInstructions,
+ snapshotInstruction: constants.nodejsCypressInstructionsSnapshot,
+ },
+ puppeteer: {
+ instructions: constants.nodejsPuppeteerInstructions,
+ snapshotInstruction: constants.nodejsPuppeteerInstructionsSnapshot,
+ },
+ nightmare: {
+ instructions: constants.nodejsNightmareInstructions,
+ snapshotInstruction: constants.nodejsNightmareInstructionsSnapshot,
+ },
+ nightwatch: {
+ instructions: constants.nodejsNightwatchInstructions,
+ snapshotInstruction: constants.nodejsNightwatchInstructionsSnapshot,
+ },
+ protractor: {
+ instructions: constants.nodejsProtractorInstructions,
+ snapshotInstruction: constants.nodejsProtractorInstructionsSnapshot,
+ },
+ testcafe: {
+ instructions: constants.nodejsTestcafeInstructions,
+ snapshotInstruction: constants.nodejsTestcafeInstructionsSnapshot,
+ },
+ gatsby: {
+ instructions: constants.nodejsGatsbyInstructions,
+ snapshotInstruction: constants.nodejsGatsbyInstructionsSnapshot,
+ },
+ storybook: {
+ instructions: constants.nodejsStorybookInstructions,
+ snapshotInstruction: constants.nodejsStorybookInstructionsSnapshot,
+ },
+ },
+ java: {
+ selenium: {
+ instructions: constants.javaInstructions,
+ snapshotInstruction: constants.javaInstructionsSnapshot,
+ },
+ playwright: {
+ instructions: constants.javaPlaywrightInstructions,
+ snapshotInstruction: constants.javaPlaywrightInstructionsSnapshot,
+ },
+ },
+ ruby: {
+ selenium: {
+ instructions: constants.rubyInstructions,
+ snapshotInstruction: constants.rubyInstructionsSnapshot,
+ },
+ capybara: {
+ instructions: constants.rubyCapybaraInstructions,
+ snapshotInstruction: constants.rubyCapybaraInstructionsSnapshot,
+ },
+ },
+ csharp: {
+ selenium: {
+ instructions: constants.csharpInstructions,
+ snapshotInstruction: constants.csharpInstructionsSnapshot,
+ },
+ playwright: {
+ instructions: constants.csharpPlaywrightInstructions,
+ snapshotInstruction: constants.csharpPlaywrightInstructionsSnapshot,
+ },
+ },
+};
+
+/**
+ * Utility function to check if a given language and testing framework
+ * are supported by Percy Web.
+ */
+export function isPercyWebFrameworkSupported(
+ language: string,
+ framework: string,
+): boolean {
+ const languageConfig =
+ SUPPORTED_CONFIGURATIONS[language as keyof typeof SUPPORTED_CONFIGURATIONS];
+ if (!languageConfig) return false;
+ return !!languageConfig[framework as keyof typeof languageConfig];
+}
diff --git a/src/tools/sdk-utils/percy-web/handler.ts b/src/tools/sdk-utils/percy-web/handler.ts
new file mode 100644
index 00000000..681fa614
--- /dev/null
+++ b/src/tools/sdk-utils/percy-web/handler.ts
@@ -0,0 +1,51 @@
+// Handler for Percy Web only mode - Visual testing without BrowserStack infrastructure
+import { RunTestsInstructionResult, RunTestsStep } from "../common/types.js";
+import { SetUpPercyInput } from "../common/schema.js";
+import { SUPPORTED_CONFIGURATIONS } from "./frameworks.js";
+
+import {
+ SDKSupportedBrowserAutomationFramework,
+ SDKSupportedLanguage,
+} from "../common/types.js";
+
+export let percyWebSetupInstructions = "";
+
+export function runPercyWeb(
+ input: SetUpPercyInput,
+ percyToken: string,
+): RunTestsInstructionResult {
+ const steps: RunTestsStep[] = [];
+
+ // Assume configuration is supported due to guardrails at orchestration layer
+ const languageConfig =
+ SUPPORTED_CONFIGURATIONS[input.detectedLanguage as SDKSupportedLanguage];
+ const frameworkConfig =
+ languageConfig[
+ input.detectedBrowserAutomationFramework as SDKSupportedBrowserAutomationFramework
+ ];
+
+ // Generate instructions for the supported configuration
+ const instructions = frameworkConfig.instructions;
+ percyWebSetupInstructions = frameworkConfig.snapshotInstruction;
+
+ // Prepend a step to set the Percy token in the environment
+ steps.push({
+ type: "instruction",
+ title: "Set Percy Token in Environment",
+ content: `Set the environment variable for your project:
+ export PERCY_TOKEN="${percyToken}"
+ (For Windows: use 'setx PERCY_TOKEN "${percyToken}"' or 'set PERCY_TOKEN=${percyToken}' as appropriate.)`,
+ });
+
+ steps.push({
+ type: "instruction",
+ title: `Percy Web Setup Instructions`,
+ content: instructions,
+ });
+
+ return {
+ steps,
+ requiresPercy: true,
+ missingDependencies: [],
+ };
+}
diff --git a/src/tools/sdk-utils/percy-web/index.ts b/src/tools/sdk-utils/percy-web/index.ts
new file mode 100644
index 00000000..6dd10c6b
--- /dev/null
+++ b/src/tools/sdk-utils/percy-web/index.ts
@@ -0,0 +1,5 @@
+// Percy Web utilities
+export { runPercyWeb } from "./handler.js";
+export { SUPPORTED_CONFIGURATIONS } from "./frameworks.js";
+export * as constants from "./constants.js";
+export type { ConfigMapping } from "./types.js";
diff --git a/src/tools/sdk-utils/percy-web/types.ts b/src/tools/sdk-utils/percy-web/types.ts
new file mode 100644
index 00000000..0445800a
--- /dev/null
+++ b/src/tools/sdk-utils/percy-web/types.ts
@@ -0,0 +1,12 @@
+/**
+ * Type for Percy Web configuration mapping.
+ * Structure: language -> automationFramework -> { instructions: string }
+ */
+export type ConfigMapping = {
+ [language: string]: {
+ [automationFramework: string]: {
+ instructions: string;
+ snapshotInstruction: string;
+ };
+ };
+};
diff --git a/src/tools/sdk-utils/percy/types.ts b/src/tools/sdk-utils/percy/types.ts
deleted file mode 100644
index 1ddd464f..00000000
--- a/src/tools/sdk-utils/percy/types.ts
+++ /dev/null
@@ -1,21 +0,0 @@
-import {
- SDKSupportedBrowserAutomationFramework,
- SDKSupportedLanguage,
- SDKSupportedTestingFramework,
-} from "../types.js";
-
-export interface PercyInstructions {
- script_updates: string;
-}
-
-export type PercyConfigMapping = Partial<
- Record<
- SDKSupportedLanguage,
- Partial<
- Record<
- SDKSupportedBrowserAutomationFramework,
- Partial>
- >
- >
- >
->;
diff --git a/src/tools/sdk-utils/types.ts b/src/tools/sdk-utils/types.ts
deleted file mode 100644
index caba6eaa..00000000
--- a/src/tools/sdk-utils/types.ts
+++ /dev/null
@@ -1,56 +0,0 @@
-export enum SDKSupportedLanguageEnum {
- nodejs = "nodejs",
- python = "python",
- java = "java",
- csharp = "csharp",
-}
-export type SDKSupportedLanguage = keyof typeof SDKSupportedLanguageEnum;
-
-export enum SDKSupportedBrowserAutomationFrameworkEnum {
- playwright = "playwright",
- selenium = "selenium",
- cypress = "cypress",
- webdriverio = "webdriverio",
-}
-export type SDKSupportedBrowserAutomationFramework =
- keyof typeof SDKSupportedBrowserAutomationFrameworkEnum;
-
-export 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 }
- >
- >
- >
- >
->;
diff --git a/tests/tools/appautomate.test.ts b/tests/tools/appautomate.test.ts
index 8598ecfa..cd7de09e 100644
--- a/tests/tools/appautomate.test.ts
+++ b/tests/tools/appautomate.test.ts
@@ -3,7 +3,7 @@ import {
getDeviceVersions,
resolveVersion,
validateArgs,
-} from '../../src/tools/appautomate-utils/appautomate';
+} from '../../src/tools/appautomate-utils/native-execution/appautomate';
import { beforeEach, it, expect, describe, vi } from 'vitest'