Skip to content

Accessibility and performance audits

Tool What it does Platforms Needs
🚦 performanceAudit Pass/fail performance checks of an app on the current screen, against the configured thresholds 🤖 🍎 —
✅ accessibilityAudit Audit the accessibility of the current screen 🤖 🍎 —

Two tools check the current screen on demand and can fail a plan step: accessibilityAudit for accessibility and performanceAudit for UI performance and memory. Neither changes feature-flag state. Both are off by default; enable them with setToolEnabled.

accessibilityAudit

Parameter Engine Meaning
engine both wcag (host-side WCAG checks) or platform (the OS engine). Default: wcag on Android, platform on iOS
appId both App to audit (default: the foreground app)
scope.container wcag { elementId } or { text }: report only violations inside that element
baseline wcag { name, mode: "record" \| "compare" }: save violations, or report baselineDiff against them
failOn wcag error, warning or never (default): fail the call when findings reach that severity
checks platform iOS checks to run (default: all)
maxIssues platform Most issues to return, 1-500

Passing an argument of the other engine fails the call with an error naming it.

wcag (Android) checks contrast, touch targets, labels and headings. The result has violations (each with its element and fingerprint), totalViolations, truncated, summary, screenId, and failed when failOn matched.

With baseline compare, baselineDiff lists new violations, fixed fingerprints and the unchanged count, and only new violations count toward failOn. A missing baseline is an error, so record one first. A cancelled call never records a baseline.

A scope.container that matches no element is an error. The audit reads the screen on display, so an appId that is not in the foreground is an error: bring the app to the foreground first, or omit appId.

platform (iOS 17+, Simulator and physical) runs XCUITest performAccessibilityAudit. The result has issues (each with check, summary, elementId usable with tapOn, and bounds), totalIssues, truncated and unsupportedChecks. As with wcag, an appId that is not in the foreground (in the background or not running) is an error: bring the app to the foreground first, or omit appId.

errorCode is unsupported_platform for wcag on iOS and for platform on Android, which has no platform engine. It is unsupported_capability when the iOS runner predates the audit command: restart the daemon so it installs the current runner.

- tool: accessibilityAudit
  params:
    baseline: { name: checkout, mode: compare }
    failOn: error

performanceAudit

Both checks support Android and iOS Simulator. Calls on physical iOS devices fail.

Parameter Meaning
kinds performance and/or memory (default: both)
appId App to audit (default: the foreground app)
failOn error or warning fails the call when a check does not pass or cannot run; never (default) reports

performance measures UI jank and frame time of the foreground app against the configured thresholds. Touch latency is measured on Android only. On iOS Simulator, instrument the app with auto-mobile-sdk to report frame metrics. The check reports unsupported when the app is in the background or the simulator receives no fresh frame metrics. memory takes a snapshot of appId on Android and checks its RSS growth over three seconds on iOS Simulator.

Each result has passed, its metrics and its violations; failed is set when failOn matched. On Android, frame-time percentiles and jank counts both cover only the frames rendered during the check, not frames from app launch or earlier screens. When the app rendered no frames during the check (an idle screen), the frame-time percentiles p50Ms–p99Ms are null and metrics.frameTimeUnmeasured says why. AutoMobile then skips the frame-time check, so it does not fail the call. For raw captures use performanceTrace, captureTrace, measureStartup or heapDump.

heapDump

Launch the app, then pass its Android package name or iOS bundle ID as appId. The result includes the host file path, its sizeBytes, and its format.

  • Android writes an .hprof for a debuggable or profileable app. Set native: true to capture the native heap. heap_dump_not_debuggable means you need a debuggable or profileable build.
  • iOS Simulator writes a .memgraph you can open in Xcode. Leave native unset. If you get heap_dump_not_inspectable, try a debuggable Simulator build. If the app stopped, relaunch it and retry.

heapDump is unsupported on physical iPhones. For allocation profiling on a physical iPhone, attach to the running app with the Allocations template in Instruments (xctrace).