@browserstack/mcp-server 2.2.5-beta.1 → 2.2.5-beta.3

package/dist/tools/accessiblity-utils/report-parser.d.ts

@@ -11,12 +11,32 @@ type SimplifiedAccessibilityIssue = {
     source_test?: string;
     /** Grouped reports only: how many duplicate rows point at this issue. */
     duplicate_count?: number;
+    /** Read for one page: how many times the issue occurs on that page. */
+    occurrences_on_page?: number;
+    /** Read for one page: the page the issue was first found on, when another one. */
+    first_found_on?: string;
+};
+/** One page of a report, counted as the dashboard's page view counts it. */
+type PageSummary = {
+    url: string;
+    /** Every occurrence on the page, repeats of issues first found elsewhere included. */
+    occurrences: number;
+    /** The issues those occurrences are of. */
+    distinct_issues: number;
+    /** Of those, the ones first found on this page. */
+    first_found_here: number;
+    /** Occurrences by severity. */
+    by_severity: Record<string, number>;
+    /** When nothing is on the page: report pages whose address looks like it. */
+    similar_pages?: string[];
 };
 type PaginationOptions = {
     /** How many JSON-chars max per “page” (default 10000) */
     maxCharacterLength?: number;
     /** Character offset to start from (default 0) */
     nextPage?: number;
+    /** Only the issues on this page. */
+    pageUrl?: string;
 };
 type PaginatedResult = {
     records: SimplifiedAccessibilityIssue[];
@@ -25,12 +45,32 @@ type PaginatedResult = {
     /** Main issues only when the report is grouped, so it matches the run's issue count. */
     total_issues: number;
     next_page: number | null;
+    /** How many issues the pages after this one hold. */
+    remaining: number;
     /** Duplicate rows left out of `records`; null when the report is not grouped. */
     duplicate_issues: number | null;
     /** Of those, the ones whose main issue could not be identified (counted only here). */
     unlinked_duplicates: number;
     /** Issues hidden in the dashboard and left out; null when the export has no Issue status. */
     hidden_issues: number | null;
+    /** Set when the report was read for one page. */
+    page?: PageSummary;
+};
+/** A main issue as two runs are matched on: the rule, the element and the page. */
+export type RunIssue = {
+    key: string;
+    issue_type: string;
+    severity: string;
+    component: string;
+    affected_page: string;
+};
+/** A report's main issues that the dashboard counts (not hidden), keyed for comparing runs. */
+export declare function loadMainIssues(reportLink: string): Promise<RunIssue[]>;
+/** Which issues of `current` are new since `base`, which of `base` are gone, and how many remain. */
+export declare function compareIssues(base: RunIssue[], current: RunIssue[]): {
+    added: RunIssue[];
+    resolved: RunIssue[];
+    retained: number;
 };
-export declare function parseAccessibilityReportFromCSV(reportLink: string, { maxCharacterLength, nextPage }?: PaginationOptions): Promise<PaginatedResult>;
+export declare function parseAccessibilityReportFromCSV(reportLink: string, { maxCharacterLength, nextPage, pageUrl }?: PaginationOptions): Promise<PaginatedResult>;
 export {};

package/dist/tools/accessiblity-utils/report-parser.js

@@ -1,6 +1,7 @@
 import { apiClient } from "../../lib/apiClient.js";
 import { parse } from "csv-parse/sync";
 import logger from "../../logger.js";
+import { pageOf, sortBySeverity } from "./paginate.js";
 const SOURCE_TEST_COLUMN = "Source test";
 const DUPLICATE_COLUMN = "Duplicate Issue of";
 const ISSUE_LINK_COLUMN = "Issue link";
@@ -14,8 +15,29 @@ function isMainIssue(row) {
     const value = (row[DUPLICATE_COLUMN] ?? "").trim();
     return value === "" || value.toUpperCase() === "NA";
 }
-export async function parseAccessibilityReportFromCSV(reportLink, { maxCharacterLength = 5000, nextPage = 0 } = {}) {
-    // 1) Download & parse
+/** A page address as the report writes it, give or take host case, trailing slash and hash. */
+function samePage(url) {
+    try {
+        const u = new URL(url.trim());
+        return `${u.protocol}//${u.host.toLowerCase()}${u.pathname.replace(/\/+$/, "")}${u.search}`;
+    }
+    catch {
+        return url.trim().replace(/\/+$/, "");
+    }
+}
+function recordOfRow(row, hasSourceTest) {
+    return {
+        issue_type: row["Issue type"],
+        component: row["Component"],
+        issue_description: row["Issue description"],
+        HTML_snippet: row["HTML snippet"],
+        how_to_fix: row["How to fix this issue"],
+        severity: (row["Severity"] || "unknown").trim(),
+        affected_page: row["Affected page"],
+        ...(hasSourceTest ? { source_test: row[SOURCE_TEST_COLUMN] } : {}),
+    };
+}
+async function loadReport(reportLink) {
     const res = await apiClient.get({ url: reportLink });
     if (!res.ok)
         throw new Error(`Failed to download report: ${res.statusText}`);
@@ -36,6 +58,119 @@ export async function parseAccessibilityReportFromCSV(reportLink, { maxCharacter
         logger.error(`[AccessibilityReport] CSV parse failed (${text.length} chars): ${err instanceof Error ? err.message : String(err)}`);
         throw err;
     }
+    return { parsed, columns };
+}
+/**
+ * One page of a report: every occurrence on it, as the dashboard's page view counts, with
+ * each issue listed once. A grouped report records a repeat under the page it occurs on but
+ * points it at its main issue, which may be on another page; those count here too.
+ */
+function pageIssues(parsed, columns, pageUrl) {
+    const grouped = columns.includes(DUPLICATE_COLUMN);
+    const hasSourceTest = columns.includes(SOURCE_TEST_COLUMN);
+    const target = samePage(pageUrl);
+    const visible = parsed.filter((row) => !isHidden(row));
+    const onPage = visible.filter((row) => samePage(row["Affected page"] ?? "") === target);
+    const mainByLink = new Map();
+    for (const row of visible) {
+        if (!grouped || isMainIssue(row)) {
+            mainByLink.set((row[ISSUE_LINK_COLUMN] ?? "").trim(), row);
+        }
+    }
+    const issues = new Map();
+    const bySeverity = {};
+    onPage.forEach((row, i) => {
+        const severity = (row["Severity"] || "unknown").trim();
+        bySeverity[severity] = (bySeverity[severity] ?? 0) + 1;
+        const mainLink = grouped && !isMainIssue(row)
+            ? (row[DUPLICATE_COLUMN] ?? "").trim()
+            : (row[ISSUE_LINK_COLUMN] ?? "").trim();
+        const key = mainLink || `row-${i}`;
+        let issue = issues.get(key);
+        if (!issue) {
+            const main = mainByLink.get(mainLink) ?? row;
+            issue = {
+                ...recordOfRow(main, hasSourceTest),
+                affected_page: row["Affected page"],
+                occurrences_on_page: 0,
+            };
+            if (samePage(main["Affected page"] ?? "") !== target) {
+                issue.first_found_on = main["Affected page"];
+            }
+            issues.set(key, issue);
+        }
+        issue.occurrences_on_page = (issue.occurrences_on_page ?? 0) + 1;
+    });
+    const all = [...issues.values()];
+    const page = {
+        url: pageUrl,
+        occurrences: onPage.length,
+        distinct_issues: all.length,
+        first_found_here: all.filter((issue) => !issue.first_found_on).length,
+        by_severity: bySeverity,
+    };
+    if (onPage.length === 0) {
+        const tail = new URL(target, "https://x").pathname.split("/").filter(Boolean).pop() ??
+            "";
+        const stem = tail.split("-").slice(0, 2).join("-");
+        // A short row may have no Affected page at all.
+        const pages = [
+            ...new Set(visible
+                .map((row) => row["Affected page"])
+                .filter((p) => Boolean(p))),
+        ];
+        page.similar_pages = pages
+            .filter((p) => stem && samePage(p).includes(stem))
+            .slice(0, 5);
+    }
+    return { all, page };
+}
+/** A report's main issues that the dashboard counts (not hidden), keyed for comparing runs. */
+export async function loadMainIssues(reportLink) {
+    const { parsed, columns } = await loadReport(reportLink);
+    const grouped = columns.includes(DUPLICATE_COLUMN);
+    return parsed
+        .filter((row) => (!grouped || isMainIssue(row)) && !isHidden(row))
+        .map((row) => {
+        const element = (row["CSS selector"] || row["Component"] || "").trim();
+        return {
+            key: [
+                row["Issue type"],
+                element,
+                samePage(row["Affected page"] ?? ""),
+            ].join("|"),
+            issue_type: row["Issue type"],
+            severity: (row["Severity"] || "unknown").trim(),
+            component: row["Component"],
+            affected_page: row["Affected page"],
+        };
+    });
+}
+/** Which issues of `current` are new since `base`, which of `base` are gone, and how many remain. */
+export function compareIssues(base, current) {
+    const before = new Set(base.map((issue) => issue.key));
+    const after = new Set(current.map((issue) => issue.key));
+    return {
+        added: sortBySeverity(current.filter((issue) => !before.has(issue.key))),
+        resolved: sortBySeverity(base.filter((issue) => !after.has(issue.key))),
+        retained: current.filter((issue) => before.has(issue.key)).length,
+    };
+}
+export async function parseAccessibilityReportFromCSV(reportLink, { maxCharacterLength = 5000, nextPage = 0, pageUrl } = {}) {
+    // 1) Download & parse
+    const { parsed, columns } = await loadReport(reportLink);
+    if (pageUrl) {
+        const { all, page } = pageIssues(parsed, columns, pageUrl);
+        const slice = pageOf(sortBySeverity(all), { maxCharacterLength, nextPage });
+        return {
+            ...slice,
+            total_issues: all.length,
+            duplicate_issues: null,
+            unlinked_duplicates: 0,
+            hidden_issues: null,
+            page,
+        };
+    }
     // 2) Leave out hidden issues and fold duplicates into their main issue, as the
     // dashboard's count does.
     //
@@ -55,14 +190,7 @@ export async function parseAccessibilityReportFromCSV(reportLink, { maxCharacter
     const recordOf = new Map();
     const all = visibleMainRows.map((row) => {
         const record = {
-            issue_type: row["Issue type"],
-            component: row["Component"],
-            issue_description: row["Issue description"],
-            HTML_snippet: row["HTML snippet"],
-            how_to_fix: row["How to fix this issue"],
-            severity: (row["Severity"] || "unknown").trim(),
-            affected_page: row["Affected page"],
-            ...(hasSourceTest ? { source_test: row[SOURCE_TEST_COLUMN] } : {}),
+            ...recordOfRow(row, hasSourceTest),
             ...(linkable ? { duplicate_count: 0 } : {}),
         };
         recordOf.set(row, record);
@@ -91,40 +219,11 @@ export async function parseAccessibilityReportFromCSV(reportLink, { maxCharacter
         else
             unlinkedDuplicates++;
     }
-    const totalIssues = all.length;
-    // 3) Sort by severity
-    const order = {
-        critical: 0,
-        serious: 1,
-        moderate: 2,
-        minor: 3,
-    };
-    all.sort((a, b) => (order[a.severity] ?? 99) - (order[b.severity] ?? 99));
-    // 4) Walk to the starting offset
-    let charCursor = 0;
-    let idx = 0;
-    for (; idx < all.length; idx++) {
-        const len = JSON.stringify(all[idx]).length;
-        if (charCursor + len > nextPage)
-            break;
-        charCursor += len;
-    }
-    // 5) Collect up to maxCharacterLength
-    const page = [];
-    for (let i = idx; i < all.length; i++) {
-        const recStr = JSON.stringify(all[i]);
-        if (charCursor - nextPage + recStr.length > maxCharacterLength)
-            break;
-        page.push(all[i]);
-        charCursor += recStr.length;
-    }
-    const pageLength = page.length;
-    const hasMore = idx + pageLength < totalIssues;
+    // 3) Most severe first, in pages by JSON length
+    const page = pageOf(sortBySeverity(all), { maxCharacterLength, nextPage });
     return {
-        records: page,
-        next_page: hasMore ? charCursor : null,
-        page_length: pageLength,
-        total_issues: totalIssues,
+        ...page,
+        total_issues: all.length,
         duplicate_issues: grouped ? duplicates : null,
         unlinked_duplicates: unlinkedDuplicates,
         hidden_issues: columns.includes(STATUS_COLUMN)

package/dist/tools/appautomate-utils/appium-sdk/config-generator.d.ts

@@ -4,4 +4,6 @@ export declare function generateAppBrowserStackYMLInstructions(config: {
     platforms?: string[];
     testingFramework?: string;
     projectName?: string;
+    /** Run App Accessibility checks during the tests. */
+    accessibility?: boolean;
 }, appPath?: string): string;

package/dist/tools/appautomate-utils/appium-sdk/config-generator.js

@@ -1,4 +1,12 @@
 import { APP_DEVICE_CONFIGS, AppSDKSupportedTestingFrameworkEnum, DEFAULT_APP_PATH, USERNAME_PLACEHOLDER, ACCESS_KEY_PLACEHOLDER, createStep, } from "./index.js";
+/**
+ * The App Accessibility settings written when checks are on. Only the WCAG version is
+ * spelled out, as the one most often changed; the SDK's other defaults apply.
+ */
+const ACCESSIBILITY_OPTIONS = `accessibilityOptions:
+  wcagVersion: wcag22aa
+  includeIssueType:
+    bestPractice: true`;
 export function generateAppBrowserStackYMLInstructions(config, appPath = DEFAULT_APP_PATH) {
     if (config.testingFramework ===
         AppSDKSupportedTestingFrameworkEnum.nightwatch ||
@@ -12,6 +20,7 @@ export function generateAppBrowserStackYMLInstructions(config, appPath = DEFAULT
     const buildName = config.projectName
         ? `${config.projectName}-AppAutomate-Build`
         : "bstack-demo";
+    // A YAML comment, not "//": YAML reads a "//" line as a key.
     const configContent = `\`\`\`yaml
 userName: ${USERNAME_PLACEHOLDER}
 accessKey: ${ACCESS_KEY_PLACEHOLDER}
@@ -19,21 +28,22 @@ app: ${appPath}
 platforms:
 ${platformConfigs}
 parallelsPerPlatform: 1
-browserstackLocal: true
-// TODO: replace projectName and buildName according to actual project
+browserstackLocal: false
+# Replace projectName and buildName according to the actual project
 projectName: ${projectName}
 buildName: ${buildName}
 debug: true
 networkLogs: true
 percy: false
 percyCaptureMode: auto
-accessibility: false
+accessibility: ${config.accessibility ? "true" : "false"}${config.accessibility ? `\n${ACCESSIBILITY_OPTIONS}` : ""}
 \`\`\`
 
 **Important notes:**
 - Replace \`app: ${appPath}\` with the path to your actual app file (e.g., \`./SampleApp.apk\` for Android or \`./SampleApp.ipa\` for iOS)
 - You can upload your app using BrowserStack's App Upload API or manually through the dashboard
 - Set \`browserstackLocal: true\` if you need to test with local/staging servers
+- Keep \`osVersion\` unquoted: the SDK parses it as a number, and its App Accessibility module reads that key (not \`platformVersion\`)
 - Adjust \`parallelsPerPlatform\` based on your subscription limits`;
     const stepTitle = "Update browserstack.yml file with App Automate configuration:";
     const stepDescription = `Create or update the browserstack.yml file in your project root with the following content:
@@ -47,7 +57,7 @@ function generatePlatformConfigs(config) {
             .map((env) => {
             return `  - platformName: ${env.platform}
     deviceName: "${env.deviceName}"
-    platformVersion: "${env.osVersion}"`;
+    osVersion: ${env.osVersion}`;
         })
             .join("\n");
     }
@@ -60,7 +70,7 @@ function generatePlatformConfigs(config) {
             return devices
                 .map((device) => `  - platformName: ${platform}
     deviceName: ${device.deviceName}
-    platformVersion: "${device.platformVersion}"`)
+    osVersion: ${device.platformVersion}`)
                 .join("\n");
         })
             .filter(Boolean)

package/dist/tools/appautomate-utils/appium-sdk/constants.d.ts

@@ -21,7 +21,7 @@ export declare const MobileDeviceSchema: z.ZodObject<{
     deviceName: z.ZodString;
     osVersion: z.ZodString;
 }, z.core.$strip>;
-export declare const SETUP_APP_AUTOMATE_DESCRIPTION = "Set up BrowserStack App Automate SDK integration for Appium-based mobile app testing. ONLY for Appium based framework . This tool configures SDK for various languages with appium. For pre-built Espresso or XCUITest test suites, use 'runAppTestsOnBrowserStack' instead.";
+export declare const SETUP_APP_AUTOMATE_DESCRIPTION = "Set up BrowserStack App Automate SDK integration for Appium-based mobile app testing. ONLY for Appium based framework . This tool configures SDK for various languages with appium. For pre-built Espresso or XCUITest test suites, use 'runAppTestsOnBrowserStack' instead. Set accessibility: true to also run App Accessibility (WCAG) checks on the screens the tests interact with; the issues are then read with fetchAccessibilityIssues.";
 export declare const SETUP_APP_AUTOMATE_SCHEMA: {
     detectedFramework: z.ZodEnum<typeof AppSDKSupportedFrameworkEnum>;
     detectedTestingFramework: z.ZodEnum<typeof AppSDKSupportedTestingFrameworkEnum>;
@@ -36,4 +36,5 @@ export declare const SETUP_APP_AUTOMATE_SCHEMA: {
     }, z.core.$strip>>>;
     appPath: z.ZodString;
     project: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    accessibility: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 };

package/dist/tools/appautomate-utils/appium-sdk/constants.js

@@ -31,7 +31,7 @@ export const MobileDeviceSchema = z.object({
     osVersion: z.string().describe("OS version, e.g. '14', '16', '17', 'latest'"),
 });
 // Tool description and schema for setupBrowserStackAppAutomateTests
-export const SETUP_APP_AUTOMATE_DESCRIPTION = "Set up BrowserStack App Automate SDK integration for Appium-based mobile app testing. ONLY for Appium based framework . This tool configures SDK for various languages with appium. For pre-built Espresso or XCUITest test suites, use 'runAppTestsOnBrowserStack' instead.";
+export const SETUP_APP_AUTOMATE_DESCRIPTION = "Set up BrowserStack App Automate SDK integration for Appium-based mobile app testing. ONLY for Appium based framework . This tool configures SDK for various languages with appium. For pre-built Espresso or XCUITest test suites, use 'runAppTestsOnBrowserStack' instead. Set accessibility: true to also run App Accessibility (WCAG) checks on the screens the tests interact with; the issues are then read with fetchAccessibilityIssues.";
 export const SETUP_APP_AUTOMATE_SCHEMA = {
     detectedFramework: z
         .nativeEnum(AppSDKSupportedFrameworkEnum)
@@ -55,4 +55,9 @@ export const SETUP_APP_AUTOMATE_SCHEMA = {
         .optional()
         .default("BStack-AppAutomate-Suite")
         .describe("Project name for organizing test runs on BrowserStack."),
+    accessibility: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Run App Accessibility (WCAG) checks on the screens the tests touch; Android 11+ or iOS 14+."),
 };

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

@@ -4,6 +4,7 @@ import { validateAppAutomateDevices } from "../../sdk-utils/common/device-valida
 import { CREDENTIALS_SUBSTITUTION_NOTE } from "../../sdk-utils/common/credentials.js";
 import { getAppUploadInstruction, validateSupportforAppAutomate, } from "./utils.js";
 import { getAppSDKPrefixCommand, generateAppBrowserStackYMLInstructions, } from "./index.js";
+import { getAppAccessibilityChecksInstructions } from "./languages/accessibility.js";
 import { createStep, formatAppInstructionsWithNumbers, getAppInstructionsForProjectConfiguration, SETUP_APP_AUTOMATE_SCHEMA, } from "./index.js";
 export async function setupAppAutomateHandler(rawInput, config) {
     const input = z.object(SETUP_APP_AUTOMATE_SCHEMA).parse(rawInput);
@@ -25,6 +26,7 @@ export async function setupAppAutomateHandler(rawInput, config) {
     ]) ?? [];
     const appPath = input.appPath;
     const framework = input.detectedFramework;
+    const accessibility = input.accessibility === true;
     //Validating if supported framework or not
     validateSupportforAppAutomate(framework, language, testingFramework);
     // Use default mobile devices when array is empty
@@ -36,7 +38,7 @@ export async function setupAppAutomateHandler(rawInput, config) {
     // Extract platforms for backward compatibility (if needed)
     const platforms = validatedEnvironments.map((env) => env.platform);
     // Step 1: Generate SDK setup command
-    const sdkCommand = getAppSDKPrefixCommand(language, testingFramework, appPath);
+    const sdkCommand = getAppSDKPrefixCommand(language, testingFramework, appPath, { accessibility });
     if (sdkCommand) {
         instructions.push({ content: sdkCommand, type: "setup" });
     }
@@ -46,6 +48,7 @@ export async function setupAppAutomateHandler(rawInput, config) {
         platforms,
         testingFramework,
         projectName: input.project,
+        accessibility,
     }, appPath);
     if (configInstructions) {
         instructions.push({ content: configInstructions, type: "config" });
@@ -60,6 +63,13 @@ export async function setupAppAutomateHandler(rawInput, config) {
     if (projectInstructions) {
         instructions.push({ content: projectInstructions, type: "run" });
     }
+    // Step 5: What makes an accessibility scan happen, and how to read the issues
+    if (accessibility) {
+        instructions.push({
+            content: getAppAccessibilityChecksInstructions(language, testingFramework),
+            type: "run",
+        });
+    }
     const combinedInstructions = instructions
         .map((instruction) => instruction.content)
         .join("\n\n");

package/dist/tools/appautomate-utils/appium-sdk/instructions.d.ts

@@ -1,3 +1,5 @@
 import { AppSDKSupportedLanguage, AppSDKSupportedTestingFramework } from "./index.js";
 export declare function getAppInstructionsForProjectConfiguration(framework: string, testingFramework: AppSDKSupportedTestingFramework, language: AppSDKSupportedLanguage): string;
-export declare function getAppSDKPrefixCommand(language: AppSDKSupportedLanguage, testingFramework: string, appPath?: string): string;
+export declare function getAppSDKPrefixCommand(language: AppSDKSupportedLanguage, testingFramework: string, appPath?: string, options?: {
+    accessibility?: boolean;
+}): string;

package/dist/tools/appautomate-utils/appium-sdk/instructions.js

@@ -29,14 +29,14 @@ export function getAppInstructionsForProjectConfiguration(framework, testingFram
             return "";
     }
 }
-export function getAppSDKPrefixCommand(language, testingFramework, appPath) {
+export function getAppSDKPrefixCommand(language, testingFramework, appPath, options = {}) {
     switch (language) {
         case "csharp":
             return getCSharpSDKCommand();
         case "java":
             return getJavaSDKCommand(testingFramework, appPath);
         case "nodejs":
-            return getNodejsSDKCommand(testingFramework);
+            return getNodejsSDKCommand(testingFramework, options);
         case "python":
             return getPythonSDKCommand(testingFramework);
         case "ruby":

package/dist/tools/appautomate-utils/appium-sdk/languages/accessibility.d.ts

@@ -0,0 +1,2 @@
+import { AppSDKSupportedLanguage, AppSDKSupportedTestingFramework } from "../index.js";
+export declare function getAppAccessibilityChecksInstructions(language: AppSDKSupportedLanguage, testingFramework: AppSDKSupportedTestingFramework): string;

package/dist/tools/appautomate-utils/appium-sdk/languages/accessibility.js

@@ -0,0 +1,32 @@
+// What an App Automate run needs for App Accessibility checks to happen, and how the
+// issues are read afterwards. Each point here cost a run that finished green with no
+// scans and no warning; the SDK says nothing when it decides not to scan.
+import { AppSDKSupportedTestingFrameworkEnum, createStep, } from "../index.js";
+const PYTEST_FIXTURE = `For pytest, create the driver in a fixture (\`conftest.py\`):
+\`\`\`python
+import pytest
+from appium import webdriver
+from appium.options.android import UiAutomator2Options  # XCUITestOptions for iOS
+
+
+@pytest.fixture
+def driver():
+    options = UiAutomator2Options()
+    drv = webdriver.Remote("https://hub.browserstack.com/wd/hub", options=options)
+    yield drv
+    drv.quit()
+\`\`\``;
+function driverAdvice(language, testingFramework) {
+    if (language === "python" &&
+        testingFramework === AppSDKSupportedTestingFrameworkEnum.pytest) {
+        return PYTEST_FIXTURE;
+    }
+    return "Create the driver in your framework's setup hook (a fixture, `@BeforeMethod`, `@BeforeEach`, `SetUp`, `before`), not inside the test body.";
+}
+export function getAppAccessibilityChecksInstructions(language, testingFramework) {
+    return createStep("App Accessibility checks: what makes a scan happen, and how to read the issues", `- The SDK decides per test, at the test's start, whether to scan, from the drivers that exist at that moment. A driver created inside the test body is never scanned. ${driverAdvice(language, testingFramework)}
+- Scans run on interaction commands: click/tap, send keys, actions and navigation (such as back). Reads like \`find_elements\` or \`page_source\` do not scan. Interact with every screen state you want scanned.
+- Android 11 or newer, or iOS 14 or newer, is required; older devices are skipped without an error.
+- Under \`platforms\` write the OS version as \`osVersion\`, unquoted (\`osVersion: 14.0\`; not \`platformVersion\`, not \`"14.0"\`): with any other spelling the SDK still runs the tests but App Accessibility records no scans, without a message.
+- When the run ends, the SDK prints the build id as \`testhub id: <id>\` (also the id in its automation.browserstack.com/builds/<id> link). Read the issues with \`fetchAccessibilityIssues\`, \`buildId: <id>\`; it waits while the report is still processing and links the report on the App Accessibility dashboard (https://app-accessibility.browserstack.com/automated-tests). If it reports no scans, it lists the likely causes.`);
+}

package/dist/tools/appautomate-utils/appium-sdk/languages/nodejs.d.ts

@@ -1,3 +1,5 @@
 import { AppSDKSupportedTestingFramework } from "../index.js";
-export declare function getNodejsSDKCommand(testingFramework: string): string;
+export declare function getNodejsSDKCommand(testingFramework: string, options?: {
+    accessibility?: boolean;
+}): string;
 export declare function getNodejsAppInstructions(testingFramework: AppSDKSupportedTestingFramework): string;

package/dist/tools/appautomate-utils/appium-sdk/languages/nodejs.js

@@ -1,9 +1,9 @@
 // Node.js instructions and commands for App SDK utilities
 import { AppSDKSupportedTestingFrameworkEnum, createStep, combineInstructions, } from "../index.js";
-export function getNodejsSDKCommand(testingFramework) {
+export function getNodejsSDKCommand(testingFramework, options = {}) {
     switch (testingFramework) {
         case "webdriverio":
-            return getWebDriverIOCommand();
+            return getWebDriverIOCommand(options);
         case "nightwatch":
             return getNightwatchCommand();
         case "jest":
@@ -39,7 +39,14 @@ export function getNodejsAppInstructions(testingFramework) {
             return "";
     }
 }
-function getWebDriverIOCommand() {
+function getWebDriverIOCommand({ accessibility = false, } = {}) {
+    const accessibilityConfig = accessibility
+        ? `accessibility: true,
+        accessibilityOptions: {
+          wcagVersion: 'wcag22aa',
+          includeIssueType: { bestPractice: true },
+        },`
+        : "accessibility: false,";
     const prerequisiteStep = createStep("Prerequisite Setup:", `a. Ensure you do not modify or replace any existing local driver code, 
     as it will be automatically managed and overwritten by the BrowserStack SDK/Driver.
     b. Do not create any YML file in this integration as it is not required.
@@ -48,7 +55,13 @@ function getWebDriverIOCommand() {
 export BROWSERSTACK_USERNAME="<your_browserstack_username>"
 export BROWSERSTACK_ACCESS_KEY="<your_browserstack_access_key>"
 \`\`\``);
-    const installStep = createStep("Install BrowserStack WDIO service:", `\`\`\`bash
+    // App Accessibility needs @wdio/browserstack-service 8.42.0+ on WDIO v8, or 9.6.0+ on v9.
+    const installStep = createStep("Install BrowserStack WDIO service:", accessibility
+        ? `\`\`\`bash
+npm install @wdio/browserstack-service@^9.6.0 --save-dev
+\`\`\`
+App Accessibility needs WebdriverIO v8 or v9: on WebdriverIO v8, install @wdio/browserstack-service@^8.42.0 instead.`
+        : `\`\`\`bash
 npm install @wdio/browserstack-service@^7 --save-dev
 \`\`\``);
     const configStep = createStep("Update your WebdriverIO config file (e.g., \\`wdio.conf.js\\`) to add the BrowserStack service and capabilities:", `\`\`\`js
@@ -62,7 +75,7 @@ exports.config = {
       {
         app: 'bs://sample.app',
         browserstackLocal: true,
-        accessibility: false,
+        ${accessibilityConfig}
         testObservabilityOptions: {
           buildName: "bstack-demo",
           projectName: "BrowserStack Sample",
@@ -74,7 +87,7 @@ exports.config = {
   capabilities: [{
     'bstack:options': {
       deviceName: 'Samsung Galaxy S22 Ultra',
-      platformVersion: '12.0',
+      ${accessibility ? "osVersion" : "platformVersion"}: '12.0',
       platformName: 'android',
     }
   }],

package/dist/tools/appautomate-utils/native-execution/appautomate.d.ts

@@ -38,6 +38,11 @@ export declare function uploadEspressoApp(appPath: string, config: BrowserStackC
 export declare function uploadEspressoTestSuite(testSuitePath: string, config: BrowserStackConfig): Promise<string>;
 export declare function uploadXcuiApp(appPath: string, config: BrowserStackConfig): Promise<string>;
 export declare function uploadXcuiTestSuite(testSuitePath: string, config: BrowserStackConfig): Promise<string>;
-export declare function triggerEspressoBuild(app_url: string, test_suite_url: string, devices: string[], project: string, config: BrowserStackConfig): Promise<string>;
-export declare function triggerXcuiBuild(app_url: string, test_suite_url: string, devices: string[], project: string, config: BrowserStackConfig): Promise<string>;
+/** What a native build run can be asked for beyond app, suite, devices and project. */
+export interface NativeBuildOptions {
+    /** Run App Accessibility checks during the tests (the build API's `accessibility` flag). */
+    accessibility?: boolean;
+}
+export declare function triggerEspressoBuild(app_url: string, test_suite_url: string, devices: string[], project: string, config: BrowserStackConfig, options?: NativeBuildOptions): Promise<string>;
+export declare function triggerXcuiBuild(app_url: string, test_suite_url: string, devices: string[], project: string, config: BrowserStackConfig, options?: NativeBuildOptions): Promise<string>;
 export {};

package/dist/tools/appautomate-utils/native-execution/appautomate.js

@@ -138,8 +138,17 @@ export async function uploadXcuiApp(appPath, config) {
 export async function uploadXcuiTestSuite(testSuitePath, config) {
     return uploadFileToBrowserStack(testSuitePath, "https://api-cloud.browserstack.com/app-automate/xcuitest/v2/test-suite", "test_suite_url", config, { allowedExtensions: [".zip"] });
 }
+function buildRequestBody(app_url, test_suite_url, devices, project, options) {
+    return {
+        app: app_url,
+        testSuite: test_suite_url,
+        devices,
+        project,
+        ...(options.accessibility ? { accessibility: true } : {}),
+    };
+}
 // Triggers an Espresso test run on BrowserStack and returns the build_id
-export async function triggerEspressoBuild(app_url, test_suite_url, devices, project, config) {
+export async function triggerEspressoBuild(app_url, test_suite_url, devices, project, config, options = {}) {
     const authHeader = "Basic " + Buffer.from(getBrowserStackAuth(config)).toString("base64");
     const response = await apiClient.post({
         url: "https://api-cloud.browserstack.com/app-automate/espresso/v2/build",
@@ -148,10 +157,9 @@ export async function triggerEspressoBuild(app_url, test_suite_url, devices, pro
             "Content-Type": "application/json",
         },
         body: {
-            app: app_url,
-            testSuite: test_suite_url,
-            devices,
-            project,
+            ...buildRequestBody(app_url, test_suite_url, devices, project, options),
+            // An Espresso build's App Accessibility report is generated through Test Observability.
+            ...(options.accessibility ? { testObservability: true } : {}),
         },
     });
     if (response.data.build_id) {
@@ -160,7 +168,7 @@ export async function triggerEspressoBuild(app_url, test_suite_url, devices, pro
     throw new Error(`Failed to trigger Espresso build: ${JSON.stringify(response.data)}`);
 }
 // Triggers an XCUITest run on BrowserStack and returns the build_id
-export async function triggerXcuiBuild(app_url, test_suite_url, devices, project, config) {
+export async function triggerXcuiBuild(app_url, test_suite_url, devices, project, config, options = {}) {
     const auth = {
         username: config["browserstack-username"],
         password: config["browserstack-access-key"],
@@ -172,12 +180,7 @@ export async function triggerXcuiBuild(app_url, test_suite_url, devices, project
                 Buffer.from(`${auth.username}:${auth.password}`).toString("base64"),
             "Content-Type": "application/json",
         },
-        body: {
-            app: app_url,
-            testSuite: test_suite_url,
-            devices,
-            project,
-        },
+        body: buildRequestBody(app_url, test_suite_url, devices, project, options),
     });
     if (response.data.build_id) {
         return response.data.build_id;