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

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

@@ -0,0 +1,412 @@
+/**
+ * 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;
+    /** An iOS element's class. */
+    issue_type_ios?: string;
+    how_to_fix_desc?: string;
+    issue_details?: {
+        label?: string;
+        value?: unknown;
+        important?: boolean;
+    }[];
+    /** The rule's inputs for this element, among them what it expects (`expected_ratio`, …). */
+    rule_dynamic_meta?: Record<string, 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;
+    /**
+     * What the rule measured on the element (a contrast issue's colours and ratio, a touch
+     * target's size, a font size, the label it found) and what it expects, so a fix can be
+     * sized.
+     */
+    measured?: Record<string, unknown>;
+};
+/** 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;
+    }[];
+}
+/** An issue as a page hands it out: what is its own, with its rule and screen named. */
+export type AppIssueRow = Omit<AppAccessibilityIssue, "issue_type" | "issue_description" | "wcag" | "screenshot" | "how_to_fix" | "component"> & {
+    /** The element's id or class; an element with neither is known by its rule. */
+    component?: string;
+    /** Only when it differs from the rule's usual fix, which is under the page's rules. */
+    how_to_fix?: string;
+};
+/** What a page's issues share, said once: per rule, and each screen's screenshot. */
+export interface AppIssuePageContext {
+    rules: Record<string, {
+        issue_type: string;
+        issue_description: string;
+        wcag: string;
+        how_to_fix: string;
+    }>;
+    screens: Record<string, string>;
+}
+export interface AppBuildReport extends AppIssuePageContext {
+    records: AppIssueRow[];
+    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;
+    /** How many screens were read, when the snapshot page limit stopped short of them all. */
+    screens_read?: number;
+}
+/** A manual (Workflow Analyzer) report's issues, read inline from its scanned screens. */
+export interface AppManualReport extends AppIssuePageContext {
+    records: AppIssueRow[];
+    page_length: number;
+    /**
+     * The issues, duplicates left out as the dashboard leaves them out when `deduplicated`;
+     * else every occurrence the Manual Reports API lists, which does not mark duplicates.
+     */
+    total_issues: number;
+    /** Read from the dashboard's own screens: duplicates left out, issues with their element. */
+    deduplicated: boolean;
+    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[];
+/**
+ * An issue's name, description, WCAG criteria and fix are its rule's, and its screenshot is
+ * its screen's: two thirds of an issue's length, repeated on every one. Said once, under
+ * the page's rules and screens, a page holds about three times as many issues. An issue
+ * keeps its own fix only when it differs from its rule's usual one.
+ */
+export declare function compactAppIssues(all: AppAccessibilityIssue[]): {
+    rows: AppIssueRow[];
+    context: AppIssuePageContext;
+};
+/** The rules and screens a page's issues name, and nothing else. */
+export declare function contextOf(records: AppIssueRow[], { rules, screens }: AppIssuePageContext): AppIssuePageContext;
+/** 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. When the builds scanned a different number of screens, a screen one of
+ * them has no counterpart for is set apart: an earlier screen's leftovers were not seen
+ * again (`unconfirmed`), and a later screen's were not looked for before (`first_scanned`).
+ * With as many screens in each, they correspond, and a screen with nothing left was fixed.
+ * So new, first scanned and still open add up to the later build's issues, and resolved,
+ * unconfirmed and still open to the earlier one's.
+ */
+export declare function compareAppIssues(before: AppAccessibilityIssue[], after: AppAccessibilityIssue[], { sameScreens }?: {
+    sameScreens?: boolean;
+}): {
+    added: AppAccessibilityIssue[];
+    first_scanned: AppAccessibilityIssue[];
+    resolved: AppAccessibilityIssue[];
+    unconfirmed: 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. A failed search is an
+     * error, not an empty list, or a correct name would read as one that matches nothing.
+     */
+    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 screens as the dashboard reads them, duplicates left out and each
+     * issue with its element, fix and measurements; undefined while that route answers an
+     * access key with a login redirect, as it does until it takes one.
+     */
+    private dashboardScreens;
+    /** Every occurrence the Manual Reports API lists, and the device the report ran on. */
+    private manualApiScreens;
+    /**
+     * A manual report's issues, most severe first: from the dashboard's own screens when the
+     * route takes the access key, so the count is the dashboard's and each issue names its
+     * element; else every occurrence the Manual Reports API lists, which marks neither
+     * duplicates nor elements, with the dashboard's count stated next to it.
+     */
+    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. A page that fails is an error, not the end
+     * of the list, or a build with earlier ones would read as its project's first.
+     */
+    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, up to the page limit, how many issues the dashboard
+     * hides, and whether more screens lie past the limit.
+     */
+    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 {};