feat: Enhance test file handling by supporting specific file paths and improving validation

Author: tech-sushant

src/index.ts

@@ -51,3 +51,4 @@ process.on("exit", () => {
 export { setLogger } from "./logger.js";
 export { BrowserStackMcpServer } from "./server-factory.js";
 export { trackMCP } from "./lib/instrumentation.js";
+export const PackageJsonVersion = packageJson.version;

src/lib/inmemory-store.ts

@@ -1,2 +1,11 @@
 export const signedUrlMap = new Map<string, object>();
 export const testFilePathsMap = new Map<string, string[]>();
+
+let _storedPercyResults: any = null;
+
+export const storedPercyResults = {
+  get: () => _storedPercyResults,
+  set: (value: any) => {
+    _storedPercyResults = value;
+  },
+};

src/tools/automate-utils/fetch-screenshots.ts

@@ -59,9 +59,9 @@ async function convertUrlsToBase64(
 ): Promise<Array<{ url: string; base64: string }>> {
   const screenshots = await Promise.all(
     urls.map(async (url) => {
-      const response = await apiClient.get({ 
-        url, 
-        responseType: "arraybuffer"
+      const response = await apiClient.get({
+        url,
+        responseType: "arraybuffer",
       });
       // Axios returns response.data as a Buffer for binary data
       const base64 = Buffer.from(response.data).toString("base64");

src/tools/list-test-files.ts

@@ -1,32 +1,57 @@
 import { listTestFiles } from "./percy-snapshot-utils/detect-test-files.js";
-import { testFilePathsMap } from "../lib/inmemory-store.js";
+import { testFilePathsMap, storedPercyResults } from "../lib/inmemory-store.js";
+import { updateFileAndStep } from "./percy-snapshot-utils/utils.js";
+import { percyWebSetupInstructions } from "./sdk-utils/percy-web/handler.js";
 import crypto from "crypto";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 
-export async function addListTestFiles(args: any): Promise<CallToolResult> {
-  const { dirs, language, framework } = args;
-  let testFiles: string[] = [];
-
-  if (!dirs || dirs.length === 0) {
+export async function addListTestFiles(): Promise<CallToolResult> {
+  const storedResults = storedPercyResults.get();
+  if (!storedResults) {
     throw new Error(
-      "No directories provided to add the test files. Please provide test directories to add percy snapshot commands.",
+      "No Framework details found. Please call expandPercyVisualTesting first to fetch the framework details.",
     );
   }
 
-  for (const dir of dirs) {
-    const files = await listTestFiles({
-      language,
-      framework,
-      baseDir: dir,
-    });
+  const language = storedResults.detectedLanguage;
+  const framework = storedResults.detectedTestingFramework;
+
+  // Use stored paths from setUpPercy
+  const dirs = storedResults.folderPaths;
+  const files = storedResults.filePaths;
+
+  let testFiles: string[] = [];
+
+  if (files && files.length > 0) {
     testFiles = testFiles.concat(files);
   }
 
+  if (dirs && dirs.length > 0) {
+    for (const dir of dirs) {
+      const discoveredFiles = await listTestFiles({
+        language,
+        framework,
+        baseDir: dir,
+      });
+      testFiles = testFiles.concat(discoveredFiles);
+    }
+  }
+
+  // Validate that we have at least one test file
   if (testFiles.length === 0) {
-    throw new Error("No test files found");
+    throw new Error(
+      "No test files found. Please provide either specific file paths (files) or directory paths (dirs) containing test files.",
+    );
+  }
+
+  if (testFiles.length === 1) {
+    const result = await updateFileAndStep(testFiles[0],0,1,percyWebSetupInstructions);
+    return {
+      content: result,
+    };
   }
 
-  // Generate a UUID and store the test files in memory
+  // For multiple files, use the UUID workflow
   const uuid = crypto.randomUUID();
   testFilePathsMap.set(uuid, testFiles);
 

src/tools/percy-sdk.ts

@@ -18,11 +18,7 @@ import {
   PERCY_SNAPSHOT_COMMANDS_DESCRIPTION,
   SIMULATE_PERCY_CHANGE_DESCRIPTION,
 } from "./sdk-utils/common/constants.js";
-
-import {
-  ListTestFilesParamsShape,
-  UpdateTestFileWithInstructionsParams,
-} from "./percy-snapshot-utils/constants.js";
+import { UpdateTestFileWithInstructionsParams } from "./percy-snapshot-utils/constants.js";
 
 import {
   RunPercyScanParamsShape,
@@ -126,11 +122,11 @@ export function registerPercyTools(
   tools.listTestFiles = server.tool(
     "listTestFiles",
     LIST_TEST_FILES_DESCRIPTION,
-    ListTestFilesParamsShape,
-    async (args) => {
+    {},
+    async () => {
       try {
         trackMCP("listTestFiles", server.server.getClientVersion()!, config);
-        return addListTestFiles(args);
+        return addListTestFiles();
       } catch (error) {
         return handleMCPError("listTestFiles", server, config, error);
       }

src/tools/percy-snapshot-utils/constants.ts

@@ -1,8 +1,4 @@
 import { z } from "zod";
-import {
-  SDKSupportedLanguages,
-  SDKSupportedTestingFrameworks,
-} from "../sdk-utils/common/types.js";
 import { SDKSupportedLanguage } from "../sdk-utils/common/types.js";
 import { DetectionConfig } from "./types.js";
 
@@ -13,18 +9,6 @@ export const UpdateTestFileWithInstructionsParams = {
   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 as [string, ...string[]])
-    .describe("Programming language"),
-  framework: z
-    .enum(SDKSupportedTestingFrameworks as [string, ...string[]])
-    .describe("Testing framework (optional)"),
-};
-
 export const TEST_FILE_DETECTION: Record<
   SDKSupportedLanguage,
   DetectionConfig

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

@@ -36,9 +36,16 @@ export const SetUpPercyParamsShape = {
     ),
   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 = {

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

@@ -11,6 +11,7 @@ import {
   PercyAutomateNotImplementedType,
 } from "./types.js";
 import { IMPORTANT_SETUP_WARNING } from "./index.js";
+import { PackageJsonVersion } from "../../../index.js";
 
 export function checkPercyIntegrationSupport(input: {
   integrationType: string;
@@ -108,14 +109,14 @@ export function getPercyAutomateNotImplementedMessage(
 
 export function getBootstrapFailedMessage(
   error: unknown,
-  context: { config: unknown; percyMode?: string; sdkVersion?: string },
+  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"}
-SDK Version: ${context.sdkVersion ?? "N/A"}
+MCP Version: ${PackageJsonVersion}
 Please open an issue on GitHub if the problem persists.`;
 }
 
@@ -136,3 +137,17 @@ export function percyUnsupportedResult(
     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'] }",
+    );
+  }
+}

src/tools/sdk-utils/handler.ts

@@ -8,11 +8,15 @@ 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 } from "./common/utils.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,
@@ -39,16 +43,32 @@ export async function setUpPercyHandler(
 ): Promise<CallToolResult> {
   try {
     const input = SetUpPercySchema.parse(rawInput);
+    validatePercyPathandFolders(input);
+
+    storedPercyResults.set({
+      detectedLanguage: input.detectedLanguage,
+      detectedBrowserAutomationFramework:
+        input.detectedBrowserAutomationFramework,
+      detectedTestingFramework: input.detectedTestingFramework,
+      integrationType: input.integrationType,
+      folderPaths: input.folderPaths || [],
+      filePaths: input.filePaths || [],
+    });
+
     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: input.folderPaths || [],
+      folderPaths,
+      filePaths,
     };
 
     // Check for Percy Web integration support