@browserstack/mcp-server 1.2.17-beta.1 → 1.2.18

package/dist/tools/selfheal-utils/fetch-test-code.d.ts

@@ -0,0 +1,60 @@
+import { BrowserStackConfig } from "../../lib/types.js";
+export interface TestCodeEntry {
+    testRunId: number;
+    code: string | null;
+    filename: string | null;
+    url: string | null;
+    language?: string | null;
+    type?: string | null;
+}
+/**
+ * Why a session's test code fetch succeeded or failed, so downstream callers
+ * can phrase their "please give me the file" prompt correctly:
+ *   - ok:               entries returned with real `code`/`filename`.
+ *   - non_sdk_build:    HTTP 200, entries present but every entry has
+ *                       `code === null && filename === null`. Classic signature
+ *                       of a non-SDK Automate build — the source is not
+ *                       introspectable via the API, so ask the user for the
+ *                       file path.
+ *   - empty:            HTTP 200 with no entries — session had no tests.
+ *   - unauthorized:     401 — credentials are wrong/expired. Offer retry.
+ *   - forbidden:        403 — credentials valid but no access to this session.
+ *   - not_found:        404 — session id is wrong.
+ *   - error:            any other transport/network failure.
+ */
+export type TestCodeFetchStatus = "ok" | "non_sdk_build" | "empty" | "unauthorized" | "forbidden" | "not_found" | "error";
+export interface SessionTestCode {
+    sessionId: string;
+    tests: TestCodeEntry[];
+    status: TestCodeFetchStatus;
+    httpStatus?: number;
+    errorMessage?: string;
+}
+/**
+ * Fetches the test code for all tests in a given session from the
+ * Observability API.
+ *
+ * Endpoint: GET /ext/v1/sessions/{sessionId}/testCode
+ * Returns: Array of { testRunId, code, filename, url }
+ */
+export declare function fetchTestCodeBySession(sessionId: string, config: BrowserStackConfig): Promise<SessionTestCode>;
+/**
+ * Builds a directive guidance block for the calling LLM when one or more
+ * sessions did not return usable test code. Each status block contains:
+ *   - A diagnosis (what happened, per BrowserStack)
+ *   - An explicit "do NOT paraphrase this as X" constraint
+ *   - A ready-to-say phrasing the LLM can quote when replying to the user
+ *
+ * Returns empty string when every session returned `status: ok`.
+ */
+export declare function describeTestCodeFetchIssues(sessionTestCodes: SessionTestCode[]): string;
+/**
+ * Fetches test code for multiple sessions in parallel.
+ * Failures for individual sessions are logged and skipped (partial results).
+ */
+export declare function fetchTestCodeForSessions(sessionIds: string[], config: BrowserStackConfig): Promise<SessionTestCode[]>;
+/**
+ * Formats test code entries into a concise context string suitable for
+ * inclusion in an LLM prompt. Groups by file, includes code snippets.
+ */
+export declare function formatTestCodeAsContext(sessionTestCodes: SessionTestCode[]): string;

package/dist/tools/selfheal-utils/fetch-test-code.js

@@ -0,0 +1,258 @@
+import { getBrowserStackAuth } from "../../lib/get-auth.js";
+import { apiClient } from "../../lib/apiClient.js";
+import logger from "../../logger.js";
+const OBSERVABILITY_API_BASE = "https://api-automation.browserstack.com/ext/v1";
+/**
+ * Normalizes the testCode response. The Observability API used to return a
+ * bare array of TestCodeEntry, but now wraps it as
+ * `{ sessionId, buildUuid, tests: TestCodeEntry[] }`. Accept both shapes so
+ * the integration is resilient to either deployment.
+ */
+function extractTests(data) {
+    if (!data)
+        return [];
+    if (Array.isArray(data))
+        return data;
+    return Array.isArray(data.tests) ? data.tests : [];
+}
+function classifyByHttpStatus(status) {
+    if (status === 401)
+        return "unauthorized";
+    if (status === 403)
+        return "forbidden";
+    if (status === 404)
+        return "not_found";
+    return "error";
+}
+function classifyOkResponse(tests) {
+    if (tests.length === 0)
+        return "empty";
+    const allNullCode = tests.every((t) => t.code === null && t.filename === null);
+    return allNullCode ? "non_sdk_build" : "ok";
+}
+/**
+ * Fetches the test code for all tests in a given session from the
+ * Observability API.
+ *
+ * Endpoint: GET /ext/v1/sessions/{sessionId}/testCode
+ * Returns: Array of { testRunId, code, filename, url }
+ */
+export async function fetchTestCodeBySession(sessionId, config) {
+    if (!sessionId) {
+        throw new Error("sessionId is required to fetch test code");
+    }
+    const authString = getBrowserStackAuth(config);
+    const auth = Buffer.from(authString).toString("base64");
+    const url = `${OBSERVABILITY_API_BASE}/sessions/${encodeURIComponent(sessionId)}/testCode`;
+    try {
+        const response = await apiClient.get({
+            url,
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Basic ${auth}`,
+            },
+            raise_error: false,
+        });
+        if (!response.ok) {
+            logger.warn(`Failed to fetch test code for session ${sessionId}: HTTP ${response.status}`);
+            return {
+                sessionId,
+                tests: [],
+                status: classifyByHttpStatus(response.status),
+                httpStatus: response.status,
+            };
+        }
+        const tests = extractTests(response.data);
+        return {
+            sessionId,
+            tests,
+            status: classifyOkResponse(tests),
+            httpStatus: response.status,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.warn(`Error fetching test code for session ${sessionId}: ${message}`);
+        return {
+            sessionId,
+            tests: [],
+            status: "error",
+            errorMessage: message,
+        };
+    }
+}
+/**
+ * Builds a directive guidance block for the calling LLM when one or more
+ * sessions did not return usable test code. Each status block contains:
+ *   - A diagnosis (what happened, per BrowserStack)
+ *   - An explicit "do NOT paraphrase this as X" constraint
+ *   - A ready-to-say phrasing the LLM can quote when replying to the user
+ *
+ * Returns empty string when every session returned `status: ok`.
+ */
+export function describeTestCodeFetchIssues(sessionTestCodes) {
+    if (sessionTestCodes.length === 0)
+        return "";
+    const byStatus = new Map();
+    for (const s of sessionTestCodes) {
+        if (!byStatus.has(s.status))
+            byStatus.set(s.status, []);
+        byStatus.get(s.status).push(s.sessionId);
+    }
+    const notes = [];
+    const nonSdk = byStatus.get("non_sdk_build");
+    if (nonSdk && nonSdk.length > 0) {
+        const ids = nonSdk.join(", ");
+        notes.push([
+            `### Non-SDK build — session(s): ${ids}`,
+            "",
+            "Diagnosis: BrowserStack's test-code API returned HTTP 200 with rows " +
+                "where `code` and `filename` are null. This is the KNOWN signature " +
+                "of a BrowserStack run that was NOT instrumented with the " +
+                "BrowserStack SDK / Observability. The API literally has no source " +
+                "code to return for these sessions — this is by design.",
+            "",
+            "DO NOT tell the user any of the following (all are wrong for this " +
+                "status): 'credentials issue', 'credentials or session issue', " +
+                "'could not fetch from the API due to auth', '401', 'unauthorized'. " +
+                "The credentials are fine; the build just isn't SDK-enabled.",
+            "",
+            "Say this (or very close to it) to the user, then wait for their reply:",
+            '  "This is a non-SDK BrowserStack build, so the test-code API has ' +
+                "no source to return for it (this is expected, not a credentials " +
+                "problem). Can you tell me the local file path where these tests live? " +
+                "Once I have the file, I'll apply the healed locators listed in the plan.\"",
+        ].join("\n"));
+    }
+    const unauthorized = byStatus.get("unauthorized");
+    if (unauthorized && unauthorized.length > 0) {
+        const ids = unauthorized.join(", ");
+        notes.push([
+            `### Unauthorized (HTTP 401) — session(s): ${ids}`,
+            "",
+            "Diagnosis: BrowserStack's test-code API rejected the credentials " +
+                "(HTTP 401). This IS an authentication problem for this specific " +
+                "API — the healing report endpoint and test-code endpoint use the " +
+                "same BrowserStack auth, so if the report fetch above succeeded " +
+                "with the same creds, suspect that the access key configured on " +
+                "the MCP server was rotated.",
+            "",
+            "DO NOT say 'credentials or session issue' (that hides the real cause). " +
+                "Name the 401 explicitly and offer the user a choice. Do NOT ask " +
+                "the user to paste a BrowserStack username or access key in chat — " +
+                "the MCP server reads credentials from its own environment.",
+            "",
+            "Say this (or very close to it) to the user, then wait for their reply:",
+            '  "The BrowserStack test-code API returned 401 Unauthorized for ' +
+                `session(s) ${ids}. Would you like to: (a) update the BrowserStack ` +
+                "username and access key on the MCP server (BROWSERSTACK_USERNAME / " +
+                "BROWSERSTACK_ACCESS_KEY) and restart it, or (b) skip the API and " +
+                'point me at the local test file so I can apply the healed locators there?"',
+        ].join("\n"));
+    }
+    const forbidden = byStatus.get("forbidden");
+    if (forbidden && forbidden.length > 0) {
+        const ids = forbidden.join(", ");
+        notes.push([
+            `### Forbidden (HTTP 403) — session(s): ${ids}`,
+            "",
+            "Diagnosis: BrowserStack's test-code API accepted the credentials " +
+                "but denied access to the session's source (HTTP 403). Typically " +
+                "the user does not own this session, or the account does not have " +
+                "Observability enabled.",
+            "",
+            "Do NOT blame the credentials broadly — say 'access denied for this " +
+                "session' and move on.",
+            "",
+            "Say this (or very close to it) to the user:",
+            `  "BrowserStack denied access (HTTP 403) to session(s) ${ids}. ` +
+                "This usually means the account does not own these sessions or " +
+                "does not have Observability enabled. Can you either share the " +
+                'local test file path, or confirm which account these sessions belong to?"',
+        ].join("\n"));
+    }
+    const notFound = byStatus.get("not_found");
+    if (notFound && notFound.length > 0) {
+        const ids = notFound.join(", ");
+        notes.push([
+            `### Not found (HTTP 404) — session(s): ${ids}`,
+            "",
+            "Diagnosis: BrowserStack returned HTTP 404 — the session id is most " +
+                "likely wrong, or the session has been purged.",
+            "",
+            "Do NOT say 'credentials'. Ask the user to verify the id.",
+            "",
+            "Say this (or very close to it) to the user:",
+            `  "I couldn't find session(s) ${ids} on BrowserStack (HTTP 404). ` +
+                "Can you double-check the session id(s), or share the local test " +
+                'file directly so I can apply the healed locators?"',
+        ].join("\n"));
+    }
+    const empty = byStatus.get("empty");
+    if (empty && empty.length > 0) {
+        const ids = empty.join(", ");
+        notes.push([
+            `### No test runs recorded — session(s): ${ids}`,
+            "",
+            "Diagnosis: HTTP 200 with an empty array — the session executed but " +
+                "no test code was captured (e.g. a raw Selenium session not linked " +
+                "to a test framework).",
+            "",
+            "Say this (or very close to it) to the user:",
+            `  "BrowserStack has no test code recorded for session(s) ${ids}. ` +
+                'Can you point me at the local test file where these locators live?"',
+        ].join("\n"));
+    }
+    const errored = byStatus.get("error");
+    if (errored && errored.length > 0) {
+        const details = sessionTestCodes
+            .filter((s) => s.status === "error")
+            .map((s) => `${s.sessionId}: ${s.errorMessage ?? "unknown error"}`)
+            .join("; ");
+        notes.push([
+            `### Transport error — session(s): ${errored.join(", ")}`,
+            "",
+            `Diagnosis: network/transport failure — ${details}. This is not an ` +
+                "auth issue.",
+            "",
+            "Say this (or very close to it) to the user:",
+            `  "I hit a transport error fetching test code from BrowserStack ` +
+                `(${details}). Want me to retry, or would you prefer to share the ` +
+                'local test file directly?"',
+        ].join("\n"));
+    }
+    return notes.join("\n\n");
+}
+/**
+ * Fetches test code for multiple sessions in parallel.
+ * Failures for individual sessions are logged and skipped (partial results).
+ */
+export async function fetchTestCodeForSessions(sessionIds, config) {
+    const results = await Promise.allSettled(sessionIds.map((id) => fetchTestCodeBySession(id, config)));
+    return results
+        .filter((r) => r.status === "fulfilled")
+        .map((r) => r.value);
+}
+/**
+ * Formats test code entries into a concise context string suitable for
+ * inclusion in an LLM prompt. Groups by file, includes code snippets.
+ */
+export function formatTestCodeAsContext(sessionTestCodes) {
+    const sections = [];
+    for (const session of sessionTestCodes) {
+        const testsWithCode = session.tests.filter((t) => t.code);
+        if (testsWithCode.length === 0)
+            continue;
+        const testLines = testsWithCode.map((t) => {
+            const fileInfo = t.filename ? `File: ${t.filename}` : "File: unknown";
+            const urlInfo = t.url ? `URL: ${t.url}` : "";
+            const header = [fileInfo, urlInfo].filter(Boolean).join("\n");
+            return `${header}\n\`\`\`\n${t.code}\n\`\`\``;
+        });
+        sections.push(`Session: ${session.sessionId}\n${testLines.join("\n\n")}`);
+    }
+    if (sections.length === 0) {
+        return "";
+    }
+    return `\n--- Test Code Context ---\n${sections.join("\n\n")}\n--- End Test Code Context ---\n`;
+}

package/dist/tools/selfheal-utils/selfheal.d.ts

@@ -1,11 +1,55 @@
 interface SelectorMapping {
     originalSelector: string;
     healedSelector: string;
+    selectorType: string;
+    healedSelectorType: string;
     context: {
         before: string;
         after: string;
     };
 }
+export interface LocatorRef {
+    type: string;
+    value: string;
+}
+export interface HealedSelectorEntry {
+    original_locator: LocatorRef;
+    healed_locator: LocatorRef;
+    timestamp?: string;
+    healing_thought?: string;
+    healed_element_screenshot_url?: string;
+}
+export interface HealingLog {
+    session_id: string;
+    session_name?: string;
+    product?: string;
+    os?: string;
+    browser?: string;
+    browser_version?: string;
+    healed_selectors: HealedSelectorEntry[];
+    healing_attempted_logs?: unknown[];
+    session_url?: string;
+}
+export interface SelfHealingReport {
+    report_meta: Record<string, unknown>;
+    healing_logs: HealingLog[];
+}
 import { BrowserStackConfig } from "../../lib/types.js";
-export declare function getSelfHealSelectors(sessionId: string, config: BrowserStackConfig): Promise<SelectorMapping[]>;
+type SessionType = "automate" | "app-automate";
+/**
+ * Fetches the self-healing report for a build via the build-scoped API.
+ *
+ * Two-step flow:
+ *   1. GET /ext/v1/builds/{buildUuid}/selfHealingReport -> { url, expiry }
+ *   2. GET <presigned S3 url> -> full report JSON
+ *
+ * Returns the full report so the caller (LLM) has rich context (metrics,
+ * screenshots, healing thoughts) when deciding which selectors to apply.
+ */
+export declare function fetchSelfHealingReportByBuild(buildUuid: string, config: BrowserStackConfig): Promise<SelfHealingReport>;
+/**
+ * Convenience: flatten all healed_selectors across sessions in a report.
+ */
+export declare function flattenHealedSelectors(report: SelfHealingReport): HealedSelectorEntry[];
+export declare function getSelfHealSelectors(sessionId: string, config: BrowserStackConfig, sessionType?: SessionType): Promise<SelectorMapping[]>;
 export {};

package/dist/tools/selfheal-utils/selfheal.js

@@ -1,10 +1,73 @@
 import { assertOkResponse } from "../../lib/utils.js";
 import { getBrowserStackAuth } from "../../lib/get-auth.js";
 import { apiClient } from "../../lib/apiClient.js";
-export async function getSelfHealSelectors(sessionId, config) {
+const SELF_HEAL_REPORT_BASE = "https://api-automation.browserstack.com/ext/v1/builds";
+/**
+ * Fetches the self-healing report for a build via the build-scoped API.
+ *
+ * Two-step flow:
+ *   1. GET /ext/v1/builds/{buildUuid}/selfHealingReport -> { url, expiry }
+ *   2. GET <presigned S3 url> -> full report JSON
+ *
+ * Returns the full report so the caller (LLM) has rich context (metrics,
+ * screenshots, healing thoughts) when deciding which selectors to apply.
+ */
+export async function fetchSelfHealingReportByBuild(buildUuid, config) {
+    if (!buildUuid) {
+        throw new Error("buildUuid is required");
+    }
     const authString = getBrowserStackAuth(config);
     const auth = Buffer.from(authString).toString("base64");
-    const url = `https://api.browserstack.com/automate/sessions/${sessionId}/logs`;
+    const presignedResp = await apiClient.get({
+        url: `${SELF_HEAL_REPORT_BASE}/${encodeURIComponent(buildUuid)}/selfHealingReport`,
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Basic ${auth}`,
+        },
+    });
+    await assertOkResponse(presignedResp, "self-healing report");
+    const presignedUrl = extractPresignedUrl(presignedResp.data);
+    if (!presignedUrl) {
+        throw new Error("Self-healing report response did not contain a presigned URL");
+    }
+    const reportResp = await apiClient.get({
+        url: presignedUrl,
+    });
+    await assertOkResponse(reportResp, "self-healing report payload");
+    return reportResp.data;
+}
+function extractPresignedUrl(payload) {
+    if (!payload || typeof payload !== "object")
+        return undefined;
+    const candidates = ["url", "presigned_url", "signed_url", "s3_url"];
+    const obj = payload;
+    for (const key of candidates) {
+        const value = obj[key];
+        if (typeof value === "string" && /^https?:\/\//.test(value)) {
+            return value;
+        }
+    }
+    // Some APIs nest the URL one level deeper (e.g. { data: { url } }).
+    for (const value of Object.values(obj)) {
+        if (value && typeof value === "object") {
+            const nested = extractPresignedUrl(value);
+            if (nested)
+                return nested;
+        }
+    }
+    return undefined;
+}
+/**
+ * Convenience: flatten all healed_selectors across sessions in a report.
+ */
+export function flattenHealedSelectors(report) {
+    return (report.healing_logs ?? []).flatMap((log) => log.healed_selectors ?? []);
+}
+export async function getSelfHealSelectors(sessionId, config, sessionType = "automate") {
+    const authString = getBrowserStackAuth(config);
+    const auth = Buffer.from(authString).toString("base64");
+    const productPath = sessionType === "app-automate" ? "app-automate" : "automate";
+    const url = `https://api.browserstack.com/${productPath}/sessions/${sessionId}/logs`;
     const response = await apiClient.get({
         url,
         headers: {
@@ -22,34 +85,67 @@ function extractHealedSelectors(logText) {
     // Split log text into lines for easier context handling
     const logLines = logText.split("\n");
     // Pattern to match successful SELFHEAL entries only
-    const selfhealPattern = /SELFHEAL\s*{\s*"status":"true",\s*"data":\s*{\s*"using":"css selector",\s*"value":"(.*?)"}/;
-    // Pattern to match preceding selector requests
-    const requestPattern = /POST \/session\/[^/]+\/element.*?"using":"css selector","value":"(.*?)"/;
+    const selfhealPattern = /SELFHEAL\s*{\s*"status":"true",\s*"data":\s*{\s*"using":"([^"]+)",\s*"value":"(.*?)"}/;
     // Find all successful healed selectors with their line numbers and context
     const healedMappings = [];
     for (let i = 0; i < logLines.length; i++) {
         const match = logLines[i].match(selfhealPattern);
-        if (match) {
-            const beforeLine = i > 0 ? logLines[i - 1] : "";
-            const afterLine = i < logLines.length - 1 ? logLines[i + 1] : "";
-            // Look backwards to find the most recent original selector request
-            let originalSelector = "UNKNOWN";
-            for (let j = i - 1; j >= 0; j--) {
-                const requestMatch = logLines[j].match(requestPattern);
-                if (requestMatch) {
-                    originalSelector = requestMatch[1];
-                    break;
-                }
-            }
-            healedMappings.push({
-                originalSelector,
-                healedSelector: match[1],
-                context: {
-                    before: beforeLine,
-                    after: afterLine,
-                },
-            });
+        if (!match) {
+            continue;
         }
+        const beforeLine = i > 0 ? logLines[i - 1] : "";
+        const afterLine = i < logLines.length - 1 ? logLines[i + 1] : "";
+        const healedSelectorType = normalizeSelectorType(match[1]);
+        const healedSelector = cleanSelectorValue(match[2]);
+        const requestLine = findClosestRequestLine(logLines, i);
+        const requestSelector = requestLine
+            ? extractSelectorFromRequest(requestLine)
+            : {
+                selector: "UNKNOWN",
+                selectorType: "unknown",
+            };
+        healedMappings.push({
+            originalSelector: requestSelector.selector,
+            healedSelector,
+            selectorType: requestSelector.selectorType,
+            healedSelectorType,
+            context: {
+                before: beforeLine,
+                after: afterLine,
+            },
+        });
     }
     return healedMappings;
 }
+function findClosestRequestLine(logLines, currentIndex) {
+    for (let i = currentIndex - 1; i >= 0; i--) {
+        const line = logLines[i];
+        if (line.includes("REQUEST") && line.includes('"using"')) {
+            return line;
+        }
+        if (line.includes("SELFHEAL")) {
+            break;
+        }
+    }
+    return undefined;
+}
+function extractSelectorFromRequest(line) {
+    const usingMatch = line.match(/"using":"([^"]+)"/);
+    const valueMatch = line.match(/"value":"(.*?)"/);
+    if (usingMatch && valueMatch) {
+        return {
+            selector: cleanSelectorValue(valueMatch[1]),
+            selectorType: normalizeSelectorType(usingMatch[1]),
+        };
+    }
+    return {
+        selector: "UNKNOWN",
+        selectorType: "unknown",
+    };
+}
+function cleanSelectorValue(value) {
+    return value.replace(/\\\\/g, "\\");
+}
+function normalizeSelectorType(value) {
+    return value ? value.toLowerCase() : "unknown";
+}

package/dist/tools/selfheal.d.ts

@@ -1,7 +1,32 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { BrowserStackConfig } from "../lib/types.js";
-export declare function fetchSelfHealSelectorTool(args: {
+type SessionType = "automate" | "app-automate";
+interface FetchArgs {
+    sessionId?: string;
+    sessionType?: SessionType;
+    buildUuid?: string;
+}
+export declare function fetchSelfHealSelectorTool(args: FetchArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+interface SessionLocator {
+    original: {
+        strategy: string;
+        value: string;
+    };
+    healed: {
+        strategy: string;
+        value: string;
+    };
+    thought?: string;
+}
+interface SessionPayload {
     sessionId: string;
-}, config: BrowserStackConfig): Promise<CallToolResult>;
+    sessionName?: string;
+    locators: SessionLocator[];
+}
+interface PlanArgs {
+    sessions: SessionPayload[];
+}
+export declare function prepareSelfHealingPlanTool(args: PlanArgs, config: BrowserStackConfig): Promise<CallToolResult>;
 export default function addSelfHealTools(server: McpServer, config: BrowserStackConfig): Record<string, any>;
+export {};