@browserstack/mcp-server 1.2.1 → 1.2.2-beta.1

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

@@ -0,0 +1,144 @@
+import { SetUpPercySchema, RunTestsOnBrowserStackSchema, } from "./common/schema.js";
+import { getBootstrapFailedMessage, percyUnsupportedResult, } from "./common/utils.js";
+import { formatToolResult } from "./common/utils.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 } from "./common/utils.js";
+import { PERCY_SIMULATE_INSTRUCTION, PERCY_REPLACE_REGEX, PERCY_SIMULATION_DRIVER_INSTRUCTION, } from "./common/constants.js";
+export async function runTestsOnBrowserStackHandler(rawInput, config) {
+    try {
+        const input = RunTestsOnBrowserStackSchema.parse(rawInput);
+        // Only handle BrowserStack SDK setup for functional/integration tests.
+        const result = runBstackSDKOnly(input, config);
+        return await formatToolResult(result);
+    }
+    catch (error) {
+        throw new Error(getBootstrapFailedMessage(error, { config }));
+    }
+}
+export async function setUpPercyHandler(rawInput, config) {
+    try {
+        const input = SetUpPercySchema.parse(rawInput);
+        const authorization = getBrowserStackAuth(config);
+        const percyInput = {
+            projectName: input.projectName,
+            detectedLanguage: input.detectedLanguage,
+            detectedBrowserAutomationFramework: input.detectedBrowserAutomationFramework,
+            detectedTestingFramework: input.detectedTestingFramework,
+            integrationType: input.integrationType,
+            folderPaths: input.folderPaths || [],
+        };
+        // 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);
+        }
+        else if (input.integrationType === PercyIntegrationTypeEnum.AUTOMATE) {
+            // First try Percy with BrowserStack SDK
+            const percyWithBrowserstackSDKResult = runPercyWithBrowserstackSDK({
+                ...percyInput,
+                desiredPlatforms: [],
+            }, 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",
+                        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,
+                    desiredPlatforms: [],
+                };
+                const sdkResult = 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",
+                        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 setUpSimulatePercyChangeHandler(rawInput, config) {
+    try {
+        const percyInstruction = await setUpPercyHandler(rawInput, config);
+        if (percyInstruction.isError) {
+            return percyInstruction;
+        }
+        if (Array.isArray(percyInstruction.content)) {
+            percyInstruction.content.forEach((item) => {
+                if (typeof item.text === "string" &&
+                    PERCY_REPLACE_REGEX.test(item.text)) {
+                    item.text = item.text.replace(PERCY_REPLACE_REGEX, PERCY_SIMULATE_INSTRUCTION);
+                }
+            });
+        }
+        percyInstruction.content?.push({
+            type: "text",
+            text: PERCY_SIMULATION_DRIVER_INSTRUCTION,
+        });
+        return percyInstruction;
+    }
+    catch (error) {
+        throw new Error(getBootstrapFailedMessage(error, { config }));
+    }
+}

package/dist/tools/sdk-utils/percy-automate/constants.d.ts

@@ -0,0 +1,11 @@
+export declare const percyAutomateReviewSnapshotsStep = "\n---STEP---\nReview the snapshots\n  - Go to your Percy project on https://percy.io to review snapshots and approve/reject any visual changes.\n";
+export declare const pythonPytestSeleniumInstructions = "\nInstall Percy Automate dependencies\n  - Install Percy CLI:\n    npm install --save-dev @percy/cli\n  - Install Percy Python SDK for Automate:\n    pip install percy-selenium\n\n---STEP---\nUpdate your Pytest test script  \n\nInvoke listTestFiles() with the provided directories from user to gather all test files in memory and obtain the generated UUID ---STEP---\nProcess files in STRICT sequential order using tool addPercySnapshotCommands() with below instructions:\n- Start with index 0\n- Then index 1  \n- Then index 2\n- Continue sequentially until the last index\n- DO NOT skip any index numbers\n- DO NOT jump to random indices like 10, 20, 30\n- DO NOT worry about time consuming and any constraints.\n- DO NOT STOP until you add commands in all the files or you reach end of the files.\n\n  - Import the Percy snapshot helper:\n    from percy import percy_screenshot\n  - In your test, take snapshots at key points:\n    percy_screenshot(driver, \"Your snapshot name\")\n\nExample:\n```python\nimport pytest\nfrom selenium import webdriver\nfrom percy import percy_screenshot\n\n@pytest.fixture\ndef driver():\n    driver = webdriver.Chrome()\n    yield driver\n    driver.quit()\n\ndef test_homepage(driver):\n    driver.get(\"http://localhost:8000\")\n    percy_screenshot(driver, \"Home page\")\n    # ... more test steps ...\n    percy_screenshot(driver, \"After login\")\n```\n\n---STEP---\nRun Percy Automate with your tests\n  - Use the following command:\n    npx percy exec -- browserstack-sdk pytest\n\n\n---STEP---\nReview the snapshots\n  - Go to your Percy project on https://percy.io to review snapshots and approve/reject any visual changes.\n\n";
+export declare const pythonPytestPlaywrightInstructions = "\nInstall Percy Automate dependencies\n  - Install Percy CLI:\n    npm install --save @percy/cli\n  - Install Percy Playwright SDK for Automate:\n    pip install percy-playwright\n\n---STEP---\nUpdate your Playwright test script\n\nInvoke listTestFiles() with the provided directories from user to gather all test files in memory and obtain the generated UUID ---STEP---\nProcess files in STRICT sequential order using tool addPercySnapshotCommands() with below instructions:\n- Start with index 0\n- Then index 1  \n- Then index 2\n- Continue sequentially until the last index\n- DO NOT skip any index numbers\n- DO NOT jump to random indices like 10, 20, 30\n- DO NOT worry about time consuming and any constraints.\n- DO NOT STOP until you add commands in all the files or you reach end of the files.\n\n  - Import the Percy screenshot helper:\n    from percy import percy_screenshot\n  - In your test, take snapshots at key points:\n    percy_screenshot(page, name=\"Your snapshot name\")\n    # You can pass `options`:\n    percy_screenshot(page, name=\"Your snapshot name\", options={ \"full_page\": True })\n\nExample:\n```python\nfrom playwright.sync_api import sync_playwright\nfrom percy import percy_screenshot\n\ndef test_visual_regression():\n    with sync_playwright() as p:\n        browser = p.chromium.launch()\n        page = browser.new_page()\n        page.goto(\"http://localhost:8000\")\n        percy_screenshot(page, name=\"Home page\")\n        # ... more test steps ...\n        percy_screenshot(page, name=\"After login\", options={ \"full_page\": True })\n        browser.close()\n```\n\n---STEP---\nRun Percy Automate with your tests\n  - Use the following command:\n    npx percy exec -- <command to run the automate script file>\n\n\n---STEP---\nReview the snapshots\n  - Go to your Percy project on https://percy.io to review snapshots and approve/reject any visual changes.\n\n";
+export declare const jsCypressPercyAutomateInstructions = "\nInstall Percy Automate dependencies\n  - Install Percy CLI:\n    npm install --save-dev @percy/cli\n  - Install Percy Cypress SDK:\n    npm install --save-dev @percy/cypress\n\n---STEP---\nUpdate your Cypress test script\n\nInvoke listTestFiles() with the provided directories from user to gather all test files in memory and obtain the generated UUID ---STEP---\nProcess files in STRICT sequential order using tool addPercySnapshotCommands() with below instructions:\n- Start with index 0\n- Then index 1  \n- Then index 2\n- Continue sequentially until the last index\n- DO NOT skip any index numbers\n- DO NOT jump to random indices like 10, 20, 30\n- DO NOT worry about time consuming and any constraints.\n- DO NOT STOP until you add commands in all the files or you reach end of the files.\n\n  - Import and initialize Percy in your cypress/support/index.js:\n    import '@percy/cypress';\n  - In your test, take snapshots at key points:\n    cy.percySnapshot('Your snapshot name');\n\nExample:\n```javascript\ndescribe('Percy Automate Cypress Example', () => {\n  it('should take Percy snapshots', () => {\n    cy.visit('http://localhost:8000');\n    cy.percySnapshot('Home page');\n    // ... more test steps ...\n    cy.percySnapshot('After login');\n  });\n});\n```  \n\n---STEP---\nRun Percy Automate with your tests\n  - Use the following command:\n    npx percy exec -- cypress run\n\n\n---STEP---\nReview the snapshots\n  - Go to your Percy project on https://percy.io to review snapshots and approve/reject any visual changes.\n\n";
+export declare const mochaPercyAutomateInstructions = "\nInstall Percy Automate dependencies\n  - Install Percy CLI:\n    npm install --save @percy/cli\n  - Install Percy Selenium SDK:\n    npm install @percy/selenium-webdriver@2.0.1\n\n---STEP---\nUpdate your Mocha Automate test script\n  - Import the Percy screenshot helper:\n    const { percyScreenshot } = require('@percy/selenium-webdriver');\n  - Use the Percy screenshot command to take required screenshots in your Automate session:\n    await percyScreenshot(driver, 'Screenshot 1');\n    options = { percyCSS: 'h1{color:red;}' };\n    await percyScreenshot(driver, 'Screenshot 2', options);\n\n---STEP---\nRun Percy Automate with your tests\n  - Use the following command:\n    npx percy exec -- <command to run the automate script file>\n\n\n---STEP---\nReview the snapshots\n  - Go to your Percy project on https://percy.io to review snapshots and approve/reject any visual changes.\n\n";
+export declare const mochaPercyPlaywrightInstructions = "\nInstall Percy Automate dependencies\n  - Install the latest Percy CLI:\n    npm install --save @percy/cli\n  - Install the Percy Playwright SDK:\n    npm install @percy/playwright\n\n---STEP---\nUpdate your Mocha Playwright test script\n  - Import the Percy screenshot helper:\n    const { percyScreenshot } = require(\"@percy/playwright\");\n  - Use the Percy screenshot command to take required screenshots in your Automate session.\n\nExample:\n```javascript\nconst { percyScreenshot } = require(\"@percy/playwright\");\nawait percyScreenshot(page, \"Screenshot 1\");\n// With options\nawait percyScreenshot(page, \"Screenshot 2\", { percyCSS: \"h1{color:green;}\" });\n```\n\n---STEP---\nRun Percy Automate with your tests\n  - Use the following command:\n    npx percy exec -- <command to run the automate script file>\n\n\n---STEP---\nReview the snapshots\n  - Go to your Percy project on https://percy.io to review snapshots and approve/reject any visual changes.\n\n";
+export declare const jestPercyAutomateInstructions = "\nInstall or upgrade the BrowserStack SDK:\n  - Install the SDK:\n    npm i -D browserstack-node-sdk@latest\n  - Run the setup:\n    npx setup --username \"YOUR_USERNAME\" --key \"YOUR_ACCESS_KEY\"\n\n---STEP---\nManually capture screenshots:\n  1. Import the BrowserStack Percy SDK in your test script:\n     const { percy } = require('browserstack-node-sdk');\n  2. Use `percy.screenshot(driver, name)` at desired points in your test.\n\nExample:\n```javascript\nconst { percy } = require('browserstack-node-sdk');\ndescribe(\"JestJS test\", () => {\n  let driver;\n  const caps = require(\"../\" + conf_file).capabilities;\n\n  beforeAll(() => {\n    driver = new Builder()\n      .usingServer(\"http://example-servername/hub\")\n      .withCapabilities(caps)\n      .build();\n  });\n\n  test(\"my test\", async () => {\n    // ...\n    await percy.screenshot(driver, \"My Screenshot\");\n    // ...\n  });\n});\n```\n\n---STEP---\nRun your test script:\n  - Use the following command:\n    npm run [your-test-script-name]-browserstack\n\n\n---STEP---\nReview the snapshots\n  - Go to your Percy project on https://percy.io to review snapshots and approve/reject any visual changes.\n\n";
+export declare const webdriverioPercyAutomateInstructions = "\nInstall or upgrade BrowserStack SDK\n  - Install the BrowserStack SDK:\n    npm i -D @wdio/browserstack-service\n\n---STEP---\nUpdate your WebdriverIO config file\n  1. Set `percy: true`\n  2. Set a `projectName`\n  3. Set `percyCaptureMode: auto` (or another mode as needed)\n\nExample WebdriverIO config:\n```js\nexports.config = {\n  user: process.env.BROWSERSTACK_USERNAME || 'YOUR_USERNAME',\n  key: process.env.BROWSERSTACK_ACCESS_KEY || 'YOUR_ACCESS_KEY',\n  hostname: 'hub.browserstack.com',\n  services: [\n    [\n      'browserstack',\n      { browserstackLocal: true, opts: { forcelocal: false }, percy: true, percyCaptureMode: 'auto' }\n    ],\n  ],\n  // add path to the test file\n}\n```\n\n---STEP---\n(Optional) Manually capture screenshots\n  1. Import the BrowserStack Percy SDK in your test script:\n    const { percy } = require('browserstack-node-sdk');\n  2. Add the `await percy.screenshot(driver, name)` method at required points in your test script.\n\nExample:\n```javascript\n    const { percy } = require('browserstack-node-sdk');\n  2. Add the `await percy.screenshot(driver, name)` method at required points in your test script.\n\nExample:\n```javascript\nconst { percy } = require('browserstack-node-sdk');\ndescribe(\"WebdriverIO Test\", () => {\n  it(\"my test\", async () => {\n    // ....\n    await percy.screenshot(driver, \"My Screenshot\")\n    // ....\n  });\n});\n```\n\n---STEP---\nRun your test script\n  - Use the commands defined in your package.json file to run the tests on BrowserStack.\n\n\n---STEP---\nReview the snapshots\n  - Go to your Percy project on https://percy.io to review snapshots and approve/reject any visual changes.\n\n";
+export declare const testcafePercyAutomateInstructions = "\nInstall Percy dependencies\n  - Install the required dependencies:\n    npm install --save-dev @percy/cli @percy/testcafe\n\n---STEP---\nUpdate your test script\n\nInvoke listTestFiles() with the provided directories from user to gather all test files in memory and obtain the generated UUID ---STEP---\nProcess files in STRICT sequential order using tool addPercySnapshotCommands() with below instructions:\n- Start with index 0\n- Then index 1  \n- Then index 2\n- Continue sequentially until the last index\n- DO NOT skip any index numbers\n- DO NOT jump to random indices like 10, 20, 30\n- DO NOT worry about time consuming and any constraints.\n- DO NOT STOP until you add commands in all the files or you reach end of the files.\n\n  - Import the Percy library and use the percySnapshot function to take screenshots.\n\nExample:\n```javascript\nimport percySnapshot from '@percy/testcafe';\nfixture('MyFixture')\n  .page('https://devexpress.github.io/testcafe/example/');\ntest('Test1', async t => {\n  await t.typeText('#developer-name', 'John Doe');\n  await percySnapshot(t, 'TestCafe Example');\n});\n```\n\n---STEP---\nRun Percy\n  - Use the following command to run your tests with Percy:\n    npx percy exec -- testcafe chrome:headless tests\n\n\n---STEP---\nReview the snapshots\n  - Go to your Percy project on https://percy.io to review snapshots and approve/reject any visual changes.\n\n";
+export declare const javaPlaywrightJunitInstructions = "\nInstall Percy Automate dependencies\n  - Install the latest Percy CLI:\n    npm install --save @percy/cli\n  - Add the Percy Playwright Java SDK to your pom.xml:\n```xml\n<dependency>\n  <groupId>io.percy</groupId>\n  <artifactId>percy-playwright-java</artifactId>\n  <version>1.0.0</version>\n</dependency>\n```\n\n---STEP---\nUpdate your Automate test script\n  - Import the Percy library:\n    import io.percy.playwright.Percy;\n  - Use the Percy screenshot command to take required screenshots in your Automate session.\n\nExample:\n```java\nPercy percy = new Percy(page);\npercy.screenshot(\"screenshot_1\");\n// With options\npercy.screenshot(\"screenshot_2\", options);\n```\n\n---STEP---\nRun Percy Automate with your tests\n  - Use the following command:\n    npx percy exec -- <command to run the automate script file>\n\n\n---STEP---\nReview the snapshots\n  - Go to your Percy project on https://percy.io to review snapshots and approve/reject any visual changes.\n\n";
+export declare const csharpPlaywrightNunitInstructions = "\nInstall Percy Automate dependencies\n  - Install the latest Percy CLI:\n    npm install --save @percy/cli\n  - Add the Percy Playwright SDK to your .csproj file:\n```xml\n<PackageReference Include=\"PercyIO.Playwright\" Version=\"1.0.0\" />\n```\n\n---STEP---\nUpdate your NUnit Playwright test script\n  - Import the Percy library:\n    using PercyIO.Playwright;\n  - Use the Percy screenshot command to take required screenshots in your Automate session.\n\nExample:\n```csharp\nusing PercyIO.Playwright;\nPercy.Screenshot(page, \"example_screenshot_1\");\n// With options\nPercy.Screenshot(page, \"example_screenshot_2\", options);\n```\n\n---STEP---\nRun Percy Automate with your tests\n  - Use the following command:\n    npx percy exec -- <command to run the automate script file>\n\n\n---STEP---\nReview the snapshots\n  - Go to your Percy project on https://percy.io to review snapshots and approve/reject any visual changes.\n\n";

package/dist/tools/sdk-utils/percy-automate/constants.js

@@ -0,0 +1,365 @@
+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---
+Run Percy Automate with your tests
+  - Use the following command:
+    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---
+Run Percy Automate with your tests
+  - Use the following command:
+    npx percy exec -- <command to run the automate script file>
+
+${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---
+Run Percy Automate with your tests
+  - Use the following command:
+    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---
+Run Percy Automate with your tests
+  - Use the following command:
+    npx percy exec -- <command to run the automate script file>
+
+${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---
+Run Percy Automate with your tests
+  - Use the following command:
+    npx percy exec -- <command to run the automate script file>
+
+${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---
+Run your test script:
+  - Use the following command:
+    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---
+Run your test script
+  - Use the commands defined in your package.json file to run the tests on BrowserStack.
+
+${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---
+Run Percy
+  - Use the following command to run your tests with Percy:
+    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
+<dependency>
+  <groupId>io.percy</groupId>
+  <artifactId>percy-playwright-java</artifactId>
+  <version>1.0.0</version>
+</dependency>
+\`\`\`
+
+---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---
+Run Percy Automate with your tests
+  - Use the following command:
+    npx percy exec -- <command to run the automate script file>
+
+${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
+<PackageReference Include="PercyIO.Playwright" Version="1.0.0" />
+\`\`\`
+
+---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---
+Run Percy Automate with your tests
+  - Use the following command:
+    npx percy exec -- <command to run the automate script file>
+
+${percyAutomateReviewSnapshotsStep}
+`;

package/dist/tools/sdk-utils/percy-automate/frameworks.d.ts

@@ -0,0 +1,8 @@
+import { ConfigMapping } from "./types.js";
+export declare const SUPPORTED_CONFIGURATIONS: ConfigMapping;
+/**
+ * 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 declare function isPercyAutomateFrameworkSupported(language: string, driver: string, framework: string): boolean;

package/dist/tools/sdk-utils/percy-automate/frameworks.js

@@ -0,0 +1,50 @@
+import * as instructions from "./constants.js";
+export const SUPPORTED_CONFIGURATIONS = {
+    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, driver, framework) {
+    const languageConfig = SUPPORTED_CONFIGURATIONS[language];
+    if (!languageConfig)
+        return false;
+    const driverConfig = languageConfig[driver];
+    if (!driverConfig)
+        return false;
+    return !!driverConfig[framework];
+}

package/dist/tools/sdk-utils/percy-automate/handler.d.ts

@@ -0,0 +1,3 @@
+import { RunTestsInstructionResult } from "../common/types.js";
+import { SetUpPercyInput } from "../common/schema.js";
+export declare function runPercyAutomateOnly(input: SetUpPercyInput, percyToken: string): RunTestsInstructionResult;

package/dist/tools/sdk-utils/percy-automate/handler.js

@@ -0,0 +1,30 @@
+import { SUPPORTED_CONFIGURATIONS } from "./frameworks.js";
+export function runPercyAutomateOnly(input, percyToken) {
+    const steps = [];
+    // Assume configuration is supported due to guardrails at orchestration layer
+    const languageConfig = SUPPORTED_CONFIGURATIONS[input.detectedLanguage];
+    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: `---STEP---Set the environment variable generated for your project before running your tests:\n\nexport PERCY_TOKEN="${percyToken}"\n\n(For Windows, use 'setx PERCY_TOKEN "${percyToken}"' or 'set PERCY_TOKEN=${percyToken}' as appropriate.)---STEP---`,
+    });
+    steps.push({
+        type: "instruction",
+        title: `Percy Automate Setup for ${input.detectedLanguage} with ${input.detectedTestingFramework}`,
+        content: instructions,
+    });
+    return {
+        steps,
+        requiresPercy: true,
+        missingDependencies: [],
+    };
+}

package/dist/tools/sdk-utils/percy-automate/index.d.ts

@@ -0,0 +1 @@
+export { runPercyAutomateOnly } from "./handler.js";

package/dist/tools/sdk-utils/percy-automate/index.js

@@ -0,0 +1,2 @@
+// Percy Automate utilities
+export { runPercyAutomateOnly } from "./handler.js";

package/dist/tools/sdk-utils/percy-automate/types.d.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;
+            };
+        };
+    };
+};

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

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