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

package/dist/tools/accessiblity-utils/app-report-fetcher.d.ts

@@ -0,0 +1,341 @@
+/**
+ * App Accessibility: the issues of a mobile app build run through App Automate with
+ * accessibility on. Unlike the web products there is no CSV export behind an access key,
+ * so the issues come inline, one API page per batch of scanned screens.
+ */
+export declare const APP_API_BASE = "https://api-app-accessibility.browserstack.com/automate/api/v1";
+export declare const APP_DASHBOARD = "https://app-accessibility.browserstack.com";
+/** Manual (Workflow Analyzer) reports recorded on the dashboard: a separate, older route. */
+export declare const MANUAL_API_BASE = "https://api-app-accessibility.browserstack.com/api/v1";
+export declare const MAX_SNAPSHOT_PAGES = 20;
+/** A dashboard link names a build by number; a build someone just opened is among the newest. */
+export declare const MAX_APP_BUILD_LIST_PAGES = 3;
+export declare const MAX_APP_AUTOMATE_BUILD_PAGES = 3;
+export interface AppBuildMeta {
+    /** The build's number within its project, which the dashboard link uses. */
+    build_id: number;
+    created_at?: string;
+    th_build_id: string;
+    name: string;
+    normalised_name: string;
+    project_name: string;
+    /** running | rule_processing | passed | failed | timeout | update_os_version */
+    status: string;
+    issue_summary?: {
+        total?: number;
+        scan_count?: number;
+    };
+    fup?: {
+        capped?: boolean;
+        tests_partial?: boolean;
+        tests_dropped?: boolean;
+    };
+    /** What ran the tests: an SDK framework (pytest, …) or a native one (Espresso-Junit4, …). */
+    session_data?: {
+        framework?: {
+            name?: string;
+        };
+    };
+}
+interface AppRuleIssue {
+    uid: string;
+    status?: string;
+    duplication_count?: number;
+    issue_class_android?: string;
+    issue_class_ios?: string;
+    issue_id_android?: string;
+    issue_id_ios?: string;
+    how_to_fix_desc?: string;
+    issue_details?: {
+        label?: string;
+        value?: unknown;
+    }[];
+}
+interface AppRule {
+    rule_id: string;
+    label: string;
+    description?: string;
+    severity?: string;
+    guidelines?: {
+        message?: string;
+    }[];
+    rule_issues?: AppRuleIssue[];
+}
+export interface AppSnapshot {
+    meta?: {
+        screenshot_url?: string;
+        testcase_name?: string;
+        /** A manual report's snapshot keeps its rules here. */
+        aggregated_results?: AppRule[];
+    };
+    aggregated_results?: AppRule[];
+}
+export type AppAccessibilityIssue = {
+    issue_type: string;
+    rule_id: string;
+    severity: string;
+    /** Which scanned screen of which test the element was on. */
+    screen: string;
+    /** The element's id when it has one, else its class. */
+    component: string;
+    /** The element's identifying details, as captured on the device. */
+    element: Record<string, unknown>;
+    issue_description: string;
+    how_to_fix: string;
+    /** The WCAG success criteria the rule maps to. */
+    wcag: string;
+    screenshot?: string;
+    /** How many more occurrences of this issue the report folded into it. */
+    duplicate_count?: number;
+};
+/** A report's issues counted by severity, by rule and by screen, largest first. */
+export interface AppIssueSummary {
+    by_severity: Record<string, number>;
+    by_rule: {
+        rule_id: string;
+        issue_type: string;
+        count: number;
+    }[];
+    by_screen: {
+        screen: string;
+        count: number;
+    }[];
+}
+export interface AppBuildReport {
+    records: AppAccessibilityIssue[];
+    page_length: number;
+    total_issues: number;
+    next_page: number | null;
+    /** How many issues the pages after this one hold. */
+    remaining: number;
+    summary: AppIssueSummary;
+    /** Issues hidden in the dashboard, which the API leaves out of the screens. */
+    hidden_issues: number;
+    scan_count: number;
+    status: string;
+    build_name: string;
+    dashboard_link?: string;
+    /** Whether the fair-usage cap dropped tests or scans from this build. */
+    fup_capped: boolean;
+    /** The test framework the build ran under, when the build's details name it. */
+    framework?: string;
+}
+/** A manual (Workflow Analyzer) report's issues, read inline from its scanned screens. */
+export interface AppManualReport {
+    records: AppAccessibilityIssue[];
+    page_length: number;
+    /** Every occurrence the API lists; the dashboard folds duplicates it does not mark. */
+    total_issues: number;
+    next_page: number | null;
+    /** How many issues the pages after this one hold. */
+    remaining: number;
+    summary: AppIssueSummary;
+    dashboard_count: number;
+    duplicate_occurrences: number;
+    hidden_issues: number;
+    scan_count: number;
+    /** complete | in_progress */
+    status: string;
+    report_name: string;
+    device?: string;
+    dashboard_link: string;
+}
+/** Every issue of one app build, with what a comparison needs to know of the build. */
+export interface AppBuildIssues {
+    buildId: string;
+    build_name: string;
+    build_number: number;
+    created_at?: string;
+    status: string;
+    scan_count: number;
+    /** The tests whose screens were scanned, in the order first seen. */
+    tests: string[];
+    issues: AppAccessibilityIssue[];
+}
+/** An earlier build of a project, as the build list names it. */
+export interface AppBuildRef {
+    buildId: string;
+    name?: string;
+    build_number?: number;
+    created_at?: string;
+    /** Whether it has the later build's name; a native run's builds are each named apart. */
+    same_name: boolean;
+    /**
+     * Whether the project's whole build list was read. When it was not, a build of the same
+     * name may still be further back than the newest builds read.
+     */
+    searched_all: boolean;
+}
+export interface AppProjectRow {
+    id: number;
+    name: string;
+    created_at?: string;
+}
+/** A build as the listing tool shows it: what it is, how it went, and how to read it. */
+export interface AppBuildRow {
+    buildId: string;
+    build_number?: number;
+    name: string;
+    status?: string;
+    report_status?: string;
+    created_at?: string;
+    scan_count: number;
+    issues: {
+        total: number;
+        critical: number;
+        serious: number;
+        moderate: number;
+        minor: number;
+    };
+    app?: string;
+    framework?: string;
+    dashboard_link: string;
+}
+export interface AppManualReportRow {
+    reportId: string;
+    name: string;
+    status?: string;
+    created_at?: string;
+    app?: string;
+    scan_count: number;
+    issues: {
+        total: number;
+        critical: number;
+        serious: number;
+        moderate: number;
+        minor: number;
+        duplicates: number;
+        hidden: number;
+    };
+    dashboard_link: string;
+}
+/** One row per element with an issue, most severe first. Screens are numbered in order. */
+export declare function flattenAppSnapshots(details: AppSnapshot[]): AppAccessibilityIssue[];
+/** The issues counted by severity, by rule and by screen, largest first. */
+export declare function summarizeAppIssues(rows: AppAccessibilityIssue[]): AppIssueSummary;
+/**
+ * Which issues of two builds are the same issue. Issues that look alike (one rule on
+ * elements known by neither id nor label) are paired one for one, those on the same screen
+ * and spot first, then on the same screen, then any; what is left over in either build is
+ * new or resolved. So new and still open add up to the later build's issues, and resolved
+ * and still open to the earlier one's.
+ */
+export declare function compareAppIssues(before: AppAccessibilityIssue[], after: AppAccessibilityIssue[]): {
+    added: AppAccessibilityIssue[];
+    resolved: AppAccessibilityIssue[];
+    retained: number;
+};
+/** The id a manual report's dashboard link names (`/report/{uuid}`), if it is one. */
+export declare function manualReportIdFromDashboardLink(url: URL): string | undefined;
+/** A manual report has no status of its own; it is complete once it has ended. */
+export declare function manualReportStatus(detail: {
+    meta_data?: {
+        ended_at?: string | null;
+    };
+}): string;
+export declare class AppAccessibilityApi {
+    private readonly headers;
+    constructor(headers: () => Record<string, string> | undefined);
+    /** The build's details, or undefined when the API does not know the id. */
+    buildMeta(buildId: string): Promise<AppBuildMeta | undefined>;
+    /**
+     * The id of the build an App Accessibility dashboard link points at, if it is one: the
+     * project's newest builds, by number. (The list's name filter would not do: the link
+     * carries TestHub's name for the build, which the filter does not match.)
+     */
+    buildIdFromDashboardLink(url: URL): Promise<string | undefined>;
+    /**
+     * The accessibility build of an App Automate build or session link. An SDK (Appium)
+     * session's test code carries the TestHub build id its results went to, which is the
+     * App Accessibility build when accessibility was on; a build link goes through any one
+     * of its sessions. A native (Espresso, XCUITest) build has no SDK session, and is found
+     * by name instead.
+     */
+    buildIdFromAppAutomateLink(url: URL): Promise<string | undefined>;
+    private buildOfSdkSession;
+    /** The first SDK session of an App Automate build; a native build lists none. */
+    private anySdkSession;
+    /**
+     * A native build's details name its project and when it started; App Accessibility lists
+     * the run under the same project, created as it started, and named as the App Automate
+     * build list names it ("Build #N: app vX"). The start finds it among the project's newest
+     * builds; the name, read from the account's build list, tells runs that started together
+     * apart, and finds a run older than those.
+     */
+    private buildOfNativeBuild;
+    /** A native build's project and start, from whichever framework API knows the build. */
+    private nativeBuild;
+    /** The project's builds created within moments of a run's start, newest first. */
+    private buildsStartedNear;
+    /** The build's name in the account's App Automate build list, walked newest first. */
+    private appAutomateBuildName;
+    /** The App Accessibility project of that exact name, if any. */
+    private projectId;
+    /** The projects whose name contains `name`, as the API searches it. */
+    private projectsNamed;
+    /**
+     * A listing's page. The API answers an empty list with 404 ("No builds found") for
+     * access-key callers, which is not an error here; any other failure is, a 404 from a
+     * wrong route or a missing permission included.
+     */
+    private listing;
+    /** The newest projects, as many as asked for. */
+    listAppProjects(limit: number): Promise<{
+        projects: AppProjectRow[];
+        total: number;
+    }>;
+    /**
+     * A project's newest builds, by exact project name, optionally filtered by build name.
+     * A project name that matches none exactly names the near matches, so the agent can
+     * pick rather than guess.
+     */
+    listAppBuilds(projectName: string, buildName: string | undefined, limit: number): Promise<{
+        project: {
+            id: number;
+            name: string;
+        };
+        total: number;
+        builds: AppBuildRow[];
+    }>;
+    /** The newest manual reports, optionally filtered by name. */
+    listAppManualReports(name: string | undefined, limit: number): Promise<{
+        total: number;
+        reports: AppManualReportRow[];
+    }>;
+    /** A manual report's details, or undefined when the API does not know the id. */
+    manualReport(reportId: string): Promise<any | undefined>;
+    /**
+     * A manual report's issues, every occurrence the API lists, most severe first. The
+     * dashboard's own count comes from the report's summary: it folds duplicates that the
+     * issue rows do not mark, so the two numbers are both given.
+     */
+    appReportIssues(reportId: string, cursor?: number, maxCharacterLength?: number): Promise<AppManualReport>;
+    /**
+     * The id of the project's build that `pick` accepts, newest first, within the first
+     * pages; `buildName` narrows the list to builds named like it, when the name is known
+     * to be the build's own.
+     */
+    private findBuild;
+    /**
+     * The project's builds a page at a time, newest first, within the first pages; `more`
+     * says whether the list goes on past the page.
+     */
+    private projectBuilds;
+    /**
+     * The build before this one in its project: the newest earlier build of the same name,
+     * as an SDK suite keeps its name from run to run, or else the build just before it, as
+     * each native (Espresso, XCUITest) run is named apart. None for a project's first build.
+     */
+    previousBuild(buildId: string): Promise<AppBuildRef | undefined>;
+    /** The build's page on the App Accessibility dashboard, when its project can be found. */
+    private dashboardLink;
+    /** Every scanned screen of the build, and how many issues the dashboard hides. */
+    private snapshots;
+    private requireBuildMeta;
+    /** The build's details and scanned screens; a build with no scans has none to read. */
+    private readBuild;
+    /** Every issue of the build at once, to compare it with another. */
+    buildIssues(buildId: string): Promise<AppBuildIssues>;
+    report(buildId: string, cursor?: number, maxCharacterLength?: number): Promise<AppBuildReport>;
+}
+export {};