Merge pull request #149 from tech-sushant/simulate-tool

feat :  Adding percy simulate tool

Author: gaurav-singh-9227

src/tools/percy-sdk.ts

@@ -7,12 +7,16 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.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 {
+  setUpPercyHandler,
+  simulatePercyChangeHandler,
+} from "./sdk-utils/handler.js";
+import { z } from "zod";
 import {
   SETUP_PERCY_DESCRIPTION,
   LIST_TEST_FILES_DESCRIPTION,
   PERCY_SNAPSHOT_COMMANDS_DESCRIPTION,
+  SIMULATE_PERCY_CHANGE_DESCRIPTION,
 } from "./sdk-utils/common/constants.js";
 
 import {
@@ -33,8 +37,53 @@ export function registerPercyTools(
 ) {
   const tools: Record<string, any> = {};
 
+  server.prompt(
+    "integrate-percy",
+    {
+      project_name: z
+        .string()
+        .describe("The name of the project to integrate with Percy"),
+    },
+    async ({ project_name }) => {
+      return {
+        messages: [
+          {
+            role: "assistant",
+            content: {
+              type: "text",
+              text: `Integrate percy in this project ${project_name} using tool percyVisualTestIntegrationAgent.`,
+            },
+          },
+        ],
+      };
+    },
+  );
+  
+  tools.percyVisualTestIntegrationAgent = server.tool(
+    "percyVisualTestIntegrationAgent",
+    SIMULATE_PERCY_CHANGE_DESCRIPTION,
+    SetUpPercyParamsShape,
+    async (args) => {
+      try {
+        trackMCP(
+          "VisualTestIntegrationAgent",
+          server.server.getClientVersion()!,
+          config,
+        );
+        return simulatePercyChangeHandler(args, config);
+      } catch (error) {
+        return handleMCPError(
+          "VisualTestIntegrationAgent",
+          server,
+          config,
+          error,
+        );
+      }
+    },
+  );
+
   tools.setupPercyVisualTesting = server.tool(
-    "setupPercyVisualTesting",
+    "expandPercyVisualTesting",
     SETUP_PERCY_DESCRIPTION,
     SetUpPercyParamsShape,
     async (args) => {

src/tools/run-percy-scan.ts

@@ -34,7 +34,7 @@ export async function runPercyScan(
     - Node.js → npm test or yarn test
     - Cypress → cypress run
     or from package.json scripts`,
-    `Wrap the inferred command with Percy:\nnpx percy exec -- <test command>`,
+    `Wrap the inferred command with Percy along with label: \nnpx percy exec --labels=mcp -- <test command>`,
     `If the test command cannot be inferred confidently, ask the user directly for the correct test command.`,
   );
 

src/tools/sdk-utils/common/constants.ts

@@ -2,7 +2,7 @@ export const IMPORTANT_SETUP_WARNING =
   "IMPORTANT: DO NOT SKIP ANY STEP. All the setup steps described below MUST be executed regardless of any existing configuration or setup. This ensures proper BrowserStack SDK setup.";
 
 export const SETUP_PERCY_DESCRIPTION =
-  "Set up Percy visual testing for your project. This supports both Percy Web Standalone and Percy Automate.";
+  "Set up or expand Percy visual testing configuration with comprehensive coverage for existing projects that might have Percy integrated. This supports both Percy Web Standalone and Percy Automate. Example prompts: Expand percy coverage for this project {project_name}";
 
 export const LIST_TEST_FILES_DESCRIPTION =
   "Lists all test files for a given set of directories.";
@@ -13,8 +13,7 @@ export const PERCY_SNAPSHOT_COMMANDS_DESCRIPTION =
 export const RUN_ON_BROWSERSTACK_DESCRIPTION =
   "Set up and run automated web-based tests on BrowserStack using the BrowserStack SDK. Use this tool for functional or integration test setup on BrowserStack only. For any visual testing or Percy integration, use the dedicated Percy setup tool. Example prompts: run this test on browserstack; set up this project for browserstack.";
 
-export const SIMULATE_PERCY_CHANGE_DESCRIPTION =
-  "This tool helps new users simulate a Percy visual change by guiding them to make a visible UI modification, rerun Percy, and verify that the change is detected. Only Percy web is supported";
+export const SIMULATE_PERCY_CHANGE_DESCRIPTION = `Integrate Percy visual testing into new projects and demonstrate visual change detection through a step-by-step simulation. This tool handles initial Percy integration, setup, and creates a working demonstration for new users. Primary tool for prompts like: "Integrate percy for this project", "Integrate percy in this project {project_name}"`;
 
 export const PERCY_REPLACE_REGEX =
   /Invoke listTestFiles\(\) with the provided directories[\s\S]*?- DO NOT STOP until you add commands in all the files or you reach end of the files\./;
@@ -35,7 +34,7 @@ Process files in STRICT sequential order using tool addPercySnapshotCommands() w
 export const PERCY_SIMULATE_INSTRUCTION = `
 MANDATORY: Aggressive, Accurate Percy Snapshots Integration
 
-Prerequisite: Before making any code changes in the user's repo, switch to a branch named temp-percy (run git init first if the repo is not yet initialized).
+Prerequisite: Before making any code changes in the user's repository, create and switch to a new branch named browserstack-simulation. Stage all changes but do not commit them. If the repository has not been initialized yet, run git init first.
 
 You MUST follow these steps with NO EXCEPTIONS:
 1. Identify 4-5 key test files in the project that are critical for visual testing.
@@ -53,7 +52,7 @@ STEP 1: At this case we have added Percy snapshot commands to the test files at
 - Do NOT add any popup injection or visual changes yet.
 - Do NOT run any Percy builds at this stage.
 
-STEP 2: Run ONE comprehensive baseline Percy build that executes ALL tests containing Percy snapshots in a SINGLE build. This creates one baseline build with all snapshots for comparison. Use a command like: npx percy exec -- python -m pytest tests/ -k 'test_name1 or test_name2 or test_name3' -v to run multiple specific tests in one build."
+STEP 2: Run ONE comprehensive baseline Percy build that executes ALL tests containing Percy snapshots in a SINGLE build. This creates one baseline build with all snapshots for comparison. Use a command like: npx percy exec --label=mcp -- python -m pytest tests/ -k 'test_name1 or test_name2 or test_name3' -v to run multiple specific tests in one build."
 
 STEP 3: Modify your test to inject a visible UI change (such as a popup) IMMEDIATELY BEFORE an EXISTING snapshot command (e.g., before percy_snapshot(self.driver, "screenshot name")).
 - Do NOT add a new snapshot name for the popup.
@@ -77,14 +76,14 @@ 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.
+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 setup percy for full project coverage? If yes, call the "setupPercyVisualTesting" tool to enable complete coverage for the entire project.
+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.
@@ -100,3 +99,6 @@ VALIDATION CHECKPOINTS (before proceeding to the next step):
 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;

src/tools/sdk-utils/handler.ts

@@ -17,6 +17,12 @@ 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,
@@ -155,3 +161,43 @@ export async function setUpPercyHandler(
     throw new Error(getBootstrapFailedMessage(error, { config }));
   }
 }
+
+export async function simulatePercyChangeHandler(
+  rawInput: unknown,
+  config: BrowserStackConfig,
+): Promise<CallToolResult> {
+  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 }));
+  }
+}

src/tools/sdk-utils/percy-web/handler.ts

@@ -32,7 +32,9 @@ export function runPercyWeb(
   steps.push({
     type: "instruction",
     title: "Set Percy Token in Environment",
-    content: `Here is percy token if required {${percyToken}}`,
+    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({