@browserstack/mcp-server 1.2.3-beta.1 → 1.2.4

package/dist/tools/percy-sdk.js

@@ -0,0 +1,71 @@
+import { trackMCP } from "../index.js";
+import { fetchPercyChanges } from "./review-agent.js";
+import { addListTestFiles } from "./list-test-files.js";
+import { runPercyScan } from "./run-percy-scan.js";
+import { SetUpPercyParamsShape } from "./sdk-utils/common/schema.js";
+import { updateTestsWithPercyCommands } from "./add-percy-snapshots.js";
+import { approveOrDeclinePercyBuild } from "./review-agent-utils/percy-approve-reject.js";
+import { setUpPercyHandler } from "./sdk-utils/handler.js";
+import { SETUP_PERCY_DESCRIPTION, LIST_TEST_FILES_DESCRIPTION, PERCY_SNAPSHOT_COMMANDS_DESCRIPTION, } from "./sdk-utils/common/constants.js";
+import { ListTestFilesParamsShape, UpdateTestFileWithInstructionsParams, } from "./percy-snapshot-utils/constants.js";
+import { RunPercyScanParamsShape, FetchPercyChangesParamsShape, ManagePercyBuildApprovalParamsShape, } from "./sdk-utils/common/schema.js";
+import { handleMCPError } from "../lib/utils.js";
+export function registerPercyTools(server, config) {
+    const tools = {};
+    tools.setupPercyVisualTesting = server.tool("setupPercyVisualTesting", SETUP_PERCY_DESCRIPTION, SetUpPercyParamsShape, async (args) => {
+        try {
+            trackMCP("setupPercyVisualTesting", server.server.getClientVersion(), config);
+            return setUpPercyHandler(args, config);
+        }
+        catch (error) {
+            return handleMCPError("setupPercyVisualTesting", server, config, error);
+        }
+    });
+    tools.addPercySnapshotCommands = server.tool("addPercySnapshotCommands", PERCY_SNAPSHOT_COMMANDS_DESCRIPTION, UpdateTestFileWithInstructionsParams, async (args) => {
+        try {
+            trackMCP("addPercySnapshotCommands", server.server.getClientVersion(), config);
+            return await updateTestsWithPercyCommands(args);
+        }
+        catch (error) {
+            return handleMCPError("addPercySnapshotCommands", server, config, error);
+        }
+    });
+    tools.listTestFiles = server.tool("listTestFiles", LIST_TEST_FILES_DESCRIPTION, ListTestFilesParamsShape, async (args) => {
+        try {
+            trackMCP("listTestFiles", server.server.getClientVersion(), config);
+            return addListTestFiles(args);
+        }
+        catch (error) {
+            return handleMCPError("listTestFiles", server, config, error);
+        }
+    });
+    tools.runPercyScan = server.tool("runPercyScan", "Run a Percy visual test scan. Example prompts : Run this Percy build/scan. Never run percy scan/build without this tool", RunPercyScanParamsShape, async (args) => {
+        try {
+            trackMCP("runPercyScan", server.server.getClientVersion(), config);
+            return runPercyScan(args, config);
+        }
+        catch (error) {
+            return handleMCPError("runPercyScan", server, config, error);
+        }
+    });
+    tools.fetchPercyChanges = server.tool("fetchPercyChanges", "Retrieves and summarizes all visual changes detected by Percy AI between the latest and previous builds, helping quickly review what has changed in your project.", FetchPercyChangesParamsShape, async (args) => {
+        try {
+            trackMCP("fetchPercyChanges", server.server.getClientVersion(), config);
+            return await fetchPercyChanges(args, config);
+        }
+        catch (error) {
+            return handleMCPError("fetchPercyChanges", server, config, error);
+        }
+    });
+    tools.managePercyBuildApproval = server.tool("managePercyBuildApproval", "Approve or reject a Percy build", ManagePercyBuildApprovalParamsShape, async (args) => {
+        try {
+            trackMCP("managePercyBuildApproval", server.server.getClientVersion(), config);
+            return await approveOrDeclinePercyBuild(args, config);
+        }
+        catch (error) {
+            return handleMCPError("managePercyBuildApproval", server, config, error);
+        }
+    });
+    return tools;
+}
+export default registerPercyTools;

package/dist/tools/percy-snapshot-utils/constants.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { SDKSupportedLanguage } from "../sdk-utils/common/types.js";
+import { DetectionConfig } from "./types.js";
+export declare const UpdateTestFileWithInstructionsParams: {
+    uuid: z.ZodString;
+    index: z.ZodNumber;
+};
+export declare const ListTestFilesParamsShape: {
+    dirs: z.ZodArray<z.ZodString, "many">;
+    language: z.ZodEnum<[string, ...string[]]>;
+    framework: z.ZodEnum<[string, ...string[]]>;
+};
+export declare const TEST_FILE_DETECTION: Record<SDKSupportedLanguage, DetectionConfig>;
+export declare const EXCLUDED_DIRS: Set<string>;
+export declare const backendIndicators: RegExp[];
+export declare const strongUIIndicators: RegExp[];

package/dist/tools/percy-snapshot-utils/constants.js

@@ -0,0 +1,500 @@
+import { z } from "zod";
+import { SDKSupportedLanguages, SDKSupportedTestingFrameworks, } from "../sdk-utils/common/types.js";
+export const UpdateTestFileWithInstructionsParams = {
+    uuid: z
+        .string()
+        .describe("UUID referencing the in-memory array of test file paths"),
+    index: z.number().describe("Index of the test file to update"),
+};
+export const ListTestFilesParamsShape = {
+    dirs: z
+        .array(z.string())
+        .describe("Array of directory paths to search for test files"),
+    language: z
+        .enum(SDKSupportedLanguages)
+        .describe("Programming language"),
+    framework: z
+        .enum(SDKSupportedTestingFrameworks)
+        .describe("Testing framework (optional)"),
+};
+export const TEST_FILE_DETECTION = {
+    java: {
+        extensions: [".java"],
+        namePatterns: [
+            /Test\.java$/,
+            /Tests\.java$/,
+            /Steps\.java$/,
+            /.*UI.*Test\.java$/,
+            /.*Web.*Test\.java$/,
+            /.*E2E.*Test\.java$/,
+            /.*Integration.*Test\.java$/,
+            /.*Functional.*Test\.java$/,
+        ],
+        contentRegex: [
+            /@Test\b/,
+            /@RunWith\b/,
+            /@CucumberOptions\b/,
+            /import\s+org\.junit/,
+            /import\s+org\.testng/,
+            /import\s+io\.cucumber/,
+            /import\s+org\.jbehave/,
+        ],
+        uiDriverRegex: [
+            /import\s+org\.openqa\.selenium/,
+            /import\s+org\.seleniumhq\.selenium/,
+            /import\s+io\.appium\.java_client/,
+            /import\s+com\.microsoft\.playwright/,
+            /import\s+com\.codeborne\.selenide/,
+            /import\s+net\.serenitybdd/,
+            /import\s+cucumber\.api\.java\.en/,
+            /new\s+\w*Driver\s*\(/,
+            /\.findElement\s*\(/,
+            /\.get\s*\(['"]https?:/,
+            /\.click\s*\(/,
+            /\.navigate\(\)/,
+            /WebDriver/,
+            /RemoteWebDriver/,
+            /ChromeDriver/,
+            /FirefoxDriver/,
+        ],
+        uiIndicatorRegex: [
+            // UI interactions without explicit driver imports
+            /\.sendKeys\s*\(/,
+            /\.getText\s*\(/,
+            /\.isDisplayed\s*\(/,
+            /By\.id\s*\(/,
+            /By\.className\s*\(/,
+            /By\.xpath\s*\(/,
+            /waitForElement/,
+            /waitForVisible/,
+            /assertTitle/,
+            /screenshot/,
+            /captureScreenshot/,
+            // Page Object patterns
+            /PageObject/,
+            /BasePage/,
+            /WebPage/,
+            // UI test annotations and patterns
+            /@UITest/,
+            /@WebTest/,
+            /@E2ETest/,
+            // Common UI assertions
+            /assertUrl/,
+            /verifyText/,
+            /checkElement/,
+            // Browser/window operations
+            /maximizeWindow/,
+            /setWindowSize/,
+            /switchTo/,
+            // Cucumber UI steps
+            /Given.*I\s+(open|visit|navigate)/,
+            /When.*I\s+(click|type|select)/,
+            /Then.*I\s+(see|verify|check)/,
+            /And.*I\s+(wait|scroll)/,
+        ],
+        backendRegex: [
+            /import\s+org\.springframework\.test/,
+            /import\s+javax\.persistence/,
+            /@DataJpaTest/,
+            /@WebMvcTest/,
+            /@MockBean/,
+            /EntityManager/,
+            /JdbcTemplate/,
+            /TestRestTemplate/,
+            /@Repository/,
+            /@Service/,
+            /@Entity/,
+        ],
+        excludeRegex: [
+            /UnitTest/,
+            /MockTest/,
+            /StubTest/,
+            /DatabaseTest/,
+            /import\s+org\.mockito/,
+            /@Mock\b/,
+            /@Spy\b/,
+        ],
+    },
+    csharp: {
+        extensions: [".cs"],
+        namePatterns: [
+            /Test\.cs$/,
+            /Tests\.cs$/,
+            /Steps\.cs$/,
+            /.*UI.*Test\.cs$/,
+            /.*Web.*Test\.cs$/,
+            /.*E2E.*Test\.cs$/,
+        ],
+        contentRegex: [
+            /\[Test\]/,
+            /\[TestCase\]/,
+            /\[Fact\]/,
+            /\[Theory\]/,
+            /\[Binding\]/,
+            /using\s+NUnit\.Framework/,
+            /using\s+Xunit/,
+            /using\s+TechTalk\.SpecFlow/,
+        ],
+        uiDriverRegex: [
+            /using\s+OpenQA\.Selenium/,
+            /using\s+Appium/,
+            /using\s+Microsoft\.Playwright/,
+            /using\s+Selenide/,
+            /using\s+Atata/,
+            /new\s+\w*Driver\s*\(/,
+            /\.FindElement\s*\(/,
+            /\.Navigate\(\)/,
+            /IWebDriver/,
+            /WebDriver/,
+        ],
+        uiIndicatorRegex: [
+            /\.SendKeys\s*\(/,
+            /\.Click\s*\(/,
+            /\.Text/,
+            /\.Displayed/,
+            /By\.Id/,
+            /By\.ClassName/,
+            /By\.XPath/,
+            /WaitForElement/,
+            /TakeScreenshot/,
+            /PageObject/,
+            /\[UITest\]/,
+            /\[WebTest\]/,
+            /\[E2ETest\]/,
+            /NavigateTo/,
+            /VerifyText/,
+            /AssertUrl/,
+        ],
+        backendRegex: [
+            /using\s+Microsoft\.EntityFrameworkCore/,
+            /using\s+System\.Data/,
+            /DbContext/,
+            /Repository/,
+            /Controller/,
+            /\[ApiTest\]/,
+            /\[DatabaseTest\]/,
+        ],
+        excludeRegex: [/\[UnitTest\]/, /Mock/, /Stub/, /using\s+Moq/],
+    },
+    nodejs: {
+        extensions: [".js", ".ts"],
+        namePatterns: [
+            /.test.js$/,
+            /.spec.js$/,
+            /.test.ts$/,
+            /.spec.ts$/,
+            /.*ui.*.test.(js|ts)$/,
+            /.*web.*.test.(js|ts)$/,
+            /.*e2e.*.(js|ts)$/,
+            /.*integration.*.test.(js|ts)$/,
+        ],
+        contentRegex: [
+            /\bdescribe\s*\(/,
+            /\bit\s*\(/,
+            /\btest\s*\(/,
+            /require\(['"]mocha['"]\)/,
+            /require\(['"]jest['"]\)/,
+            /import.*from\s+['"]jest['"]/,
+            /from\s+['"]@jest/,
+        ],
+        uiDriverRegex: [
+            /require\(['"]selenium-webdriver['"]\)/,
+            /require\(['"]webdriverio['"]\)/,
+            /require\(['"]puppeteer['"]\)/,
+            /require\(['"]playwright['"]\)/,
+            /require\(['"]cypress['"]\)/,
+            /require\(['"]@wdio\/sync['"]\)/,
+            /import.*from\s+['"]selenium-webdriver['"]/,
+            /import.*from\s+['"]webdriverio['"]/,
+            /import.*from\s+['"]puppeteer['"]/,
+            /import.*from\s+['"]playwright['"]/,
+            /import.*from\s+['"]cypress['"]/,
+            /import.*from\s+['"]@wdio/,
+            /\.launch\(/,
+            /\.goto\(/,
+            /driver\./,
+            /browser\./,
+        ],
+        uiIndicatorRegex: [
+            // Browser automation - SPECIFIC CONTEXT
+            /driver\.click\(/,
+            /driver\.type\(/,
+            /driver\.fill\(/,
+            /browser\.click\(/,
+            /driver\.waitForSelector\(/,
+            /browser\.waitForElement\(/,
+            /driver\.screenshot\(/,
+            /browser\.screenshot\(/,
+            /driver\.evaluate\(/,
+            /driver\.focus\(/,
+            /driver\.hover\(/,
+            // Page object patterns - UI specific
+            /page\.goto/,
+            /page\.click/,
+            /page\.fill/,
+            /page\.screenshot/,
+            /page\.waitForSelector/,
+            /page\.locator/,
+            /page\.getByRole/,
+            // Cypress specific patterns
+            /cy\.visit/,
+            /cy\.get/,
+            /cy\.click/,
+            /cy\.type/,
+            /cy\.should/,
+            /cy\.wait/,
+            /cy\.screenshot/,
+            /cy\.viewport/,
+            // WebDriverIO specific patterns
+            /browser\.url/,
+            /browser\.click/,
+            /browser\.setValue/,
+            /\$\(['"][#.]/,
+            /\$\$\(['"][#.]/, // CSS/XPath selectors
+            // Playwright specific
+            /expect.*toBeVisible/,
+            /expect.*toHaveText/,
+            /expect.*toBeEnabled/,
+            /locator\(/,
+            /getByText\(/,
+            /getByRole\(/,
+            /getByTestId\(/,
+            // DOM queries in test context
+            /findElement/,
+            /querySelector.*\)\.click/,
+            /getElementById.*\)\.click/,
+            // Test descriptions clearly indicating UI
+            /describe.*['"`].*UI/,
+            /describe.*['"`].*Web/,
+            /describe.*['"`].*E2E/,
+            /describe.*['"`].*Browser/,
+            /describe.*['"`].*Selenium/,
+            /it.*['"`].*(click|type|navigate|visit|see).*element/,
+            /it.*['"`].*(open|load).*page/,
+            /it.*['"`].*browser/,
+        ],
+        backendRegex: [
+            /require\(['"]express['"]\)/,
+            /require\(['"]fastify['"]\)/,
+            /require\(['"]supertest['"]\)/,
+            /request\(app\)/,
+            /mongoose/,
+            /sequelize/,
+            /prisma/,
+            /knex/,
+            /app\.get\(/,
+            /app\.post\(/,
+            /server\./,
+            /\.connect\(/,
+            /\.query\(/,
+        ],
+        excludeRegex: [
+            /\.unit\./,
+            /\.mock\./,
+            /jest\.mock/,
+            /sinon/,
+            /describe.*['"`]Unit/,
+            /describe.*['"`]Mock/,
+        ],
+    },
+    python: {
+        extensions: [".py"],
+        namePatterns: [
+            /^test_.*\.py$/,
+            /_test\.py$/,
+            /test.*ui.*\.py$/,
+            /test.*web.*\.py$/,
+            /test.*e2e.*\.py$/,
+            /test.*integration.*\.py$/,
+        ],
+        contentRegex: [
+            /import\s+pytest/,
+            /@pytest\.mark/,
+            /def\s+test_/,
+            /\bpytest\./,
+            /import\s+unittest/,
+            /class.*TestCase/,
+        ],
+        uiDriverRegex: [
+            /import\s+selenium/,
+            /from\s+selenium/,
+            /import\s+playwright/,
+            /from\s+playwright/,
+            /import\s+appium/,
+            /from\s+appium/,
+            /import\s+splinter/,
+            /from\s+splinter/,
+            /driver\s*=\s*webdriver\./,
+            /webdriver\.Chrome/,
+            /webdriver\.Firefox/,
+        ],
+        uiIndicatorRegex: [
+            // Selenium patterns without imports
+            /\.find_element/,
+            /\.click\(/,
+            /\.send_keys/,
+            /\.get\(/,
+            /\.screenshot/,
+            /\.execute_script/,
+            /\.switch_to/,
+            /By\.ID/,
+            /By\.CLASS_NAME/,
+            /By\.XPATH/,
+            // Playwright patterns
+            /page\.goto/,
+            /page\.click/,
+            /page\.fill/,
+            /page\.screenshot/,
+            /expect.*to_be_visible/,
+            /expect.*to_have_text/,
+            // Generic UI patterns
+            /WebDriverWait/,
+            /expected_conditions/,
+            /ActionChains/,
+            /@pytest\.mark\.ui/,
+            /@pytest\.mark\.web/,
+            /@pytest\.mark\.e2e/,
+            // Page object patterns
+            /BasePage/,
+            /PageObject/,
+            /WebPage/,
+            // BDD step patterns
+            /def\s+.*_(open|visit|navigate|click|type|see|verify)/,
+        ],
+        backendRegex: [
+            /import\s+flask/,
+            /from\s+flask/,
+            /import\s+fastapi/,
+            /from\s+fastapi/,
+            /import\s+django/,
+            /from\s+django/,
+            /sqlalchemy/,
+            /requests\.get/,
+            /requests\.post/,
+            /TestClient/,
+            /@pytest\.mark\.django_db/,
+            /django\.test/,
+        ],
+        excludeRegex: [
+            /unittest\.mock/,
+            /from\s+unittest\.mock/,
+            /mock\.patch/,
+            /@pytest\.mark\.unit/,
+            /@mock\./,
+        ],
+    },
+    ruby: {
+        extensions: [".rb"],
+        namePatterns: [
+            /_spec\.rb$/,
+            /_test\.rb$/,
+            /.*ui.*_spec\.rb$/,
+            /.*web.*_spec\.rb$/,
+            /.*e2e.*_spec\.rb$/,
+        ],
+        contentRegex: [
+            /\bdescribe\s/,
+            /\bit\s/,
+            /require\s+['"]rspec/,
+            /require\s+['"]minitest/,
+            /RSpec\.describe/,
+        ],
+        uiDriverRegex: [
+            /require\s+['"]selenium-webdriver['"]/,
+            /require\s+['"]capybara['"]/,
+            /require\s+['"]appium_lib['"]/,
+            /require\s+['"]watir['"]/,
+            /Selenium::WebDriver/,
+            /Capybara\./,
+        ],
+        uiIndicatorRegex: [
+            // Capybara without explicit require
+            /visit\s/,
+            /click_button/,
+            /click_link/,
+            /fill_in/,
+            /find\(['"]/,
+            /has_content/,
+            /page\./,
+            /current_path/,
+            // Selenium patterns
+            /\.find_element/,
+            /\.click/,
+            /\.send_keys/,
+            // Generic UI patterns
+            /screenshot/,
+            /driver\./,
+            /browser\./,
+            /feature\s+['"]/,
+            /scenario\s+['"]/,
+            /expect.*to\s+have_content/,
+            /expect.*to\s+have_selector/,
+        ],
+        backendRegex: [
+            /require\s+['"]sinatra['"]/,
+            /require\s+['"]rails['"]/,
+            /ActiveRecord/,
+            /DatabaseCleaner/,
+            /FactoryBot/,
+        ],
+        excludeRegex: [
+            /double\(/,
+            /instance_double/,
+            /class_double/,
+            /allow\(.*\)\.to\s+receive/,
+            /mock/i,
+        ],
+    },
+};
+export const EXCLUDED_DIRS = new Set([
+    "node_modules",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "site-packages",
+    "dist",
+    "build",
+    ".git",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".tox",
+    ".idea",
+    ".vscode",
+    "coverage",
+    ".nyc_output",
+    "target",
+    "bin",
+    "obj",
+    "packages",
+    ".nuget",
+]);
+export const backendIndicators = [
+    /import\s+requests/,
+    /requests\.(get|post|put|delete|patch)/,
+    /@pytest\.mark\.(api|backend|integration)/,
+    /BASE_URL\s*=/,
+    /\.status_code/,
+    /\.json\(\)/,
+    /TestClient/,
+    /Bearer\s+/,
+    /Authorization.*Bearer/,
+];
+export const strongUIIndicators = [
+    // Browser automation with specific context
+    /(driver|browser|page)\.(click|type|fill|screenshot|wait)/,
+    /webdriver\.(Chrome|Firefox|Safari|Edge)/,
+    /(selenium|playwright|puppeteer|cypress).*import/,
+    // CSS/XPath selectors
+    /By\.(ID|CLASS_NAME|XPATH|CSS_SELECTOR)/,
+    /\$\(['"#[.][^'"]*['"]\)/, // $(".class") or $("#id")
+    // Page Object Model
+    /class.*Page.*:/,
+    /class.*PageObject/,
+    // UI test markers
+    /@(ui|web|e2e|browser)_?test/,
+    /@pytest\.mark\.(ui|web|e2e|browser)/,
+    // Browser navigation
+    /\.goto\s*\(['"]https?:/,
+    /\.visit\s*\(['"]https?:/,
+    /\.navigate\(\)\.to\(/,
+];

package/dist/tools/percy-snapshot-utils/detect-test-files.d.ts

@@ -0,0 +1,10 @@
+import { SDKSupportedLanguage, SDKSupportedTestingFrameworkEnum } from "../sdk-utils/common/types.js";
+export interface ListTestFilesOptions {
+    language: SDKSupportedLanguage;
+    framework?: SDKSupportedTestingFrameworkEnum;
+    baseDir: string;
+    strictMode?: boolean;
+}
+export declare function listTestFiles(options: ListTestFilesOptions): Promise<string[]>;
+export declare function listUITestFilesStrict(options: Omit<ListTestFilesOptions, "strictMode">): Promise<string[]>;
+export declare function listUITestFilesRelaxed(options: Omit<ListTestFilesOptions, "strictMode">): Promise<string[]>;