For AI agents and LLMs: a machine-readable index is available at llms.txt. A plain-Markdown version of any documentation page is available by appending .md to its URL.
Skip to main content

AutoScan for Mobile App Accessibility

Real Device

AutoScan runs an accessibility scan automatically after every Appium command that changes the screen, so an app flow is covered end to end without a lambda-accessibility-scan call at each step. You turn it on with a single capability, and TestMu AI scans as your existing test drives the app.

Because a test usually taps several times on the same screen, AutoScan also ships with intelligent scan: before each scan the current screen is compared with every screen scanned so far in the test, and a screen that matches one of them is skipped. Intelligent scan is on by default, so the common case is one scan per distinct screen rather than one scan per tap.

AutoScan is the mobile counterpart of the web accessibility.autoscan capability described in Automating Accessibility Testing with Selenium. Both platforms are supported on real devices: Android and iOS.

When to use this​

Use AutoScan when you want accessibility coverage across everything your Appium suite already walks through, and you do not want to maintain a hook call at every screen. It is the fastest way to go from no mobile accessibility coverage to full-flow coverage, and it removes the most common cause of empty reports, which is a screen that no one remembered to scan.

Keep using the lambda-accessibility-scan hook instead when you need exact control over when each scan runs, for example on a screen with late-loading asynchronous content, or when you want a fixed, predictable number of scans per run.

The two can be combined. A session with AutoScan on can still call the hook for a one-off scan at a moment of your choosing, and the hook doubles as a pause and resume switch.

Prerequisites​

  • An Appium test project targeting TestMu AI real devices (Android or iOS).
  • LT_USERNAME / LT_ACCESS_KEY available to the process.
  • Accessibility enabled on the session with the accessibility master capability.
  • A native Android or iOS app. Hybrid apps with embedded webview content are not supported.

Capabilities reference​

CapabilityTypeDefaultDescription
accessibilitybooleanfalseMaster switch. Must be true for any accessibility capability to take effect.
accessibility.autoScanbooleanfalseScans automatically after every screen-changing command. See What triggers a scan.
accessibility.intelligentScanbooleantrueSkips a scan when the screen has not visibly changed since the last one. Pass false to scan after every triggering command.
accessibility.intelligentScanThresholdinteger, 0 to 9995Visual similarity percentage at or above which a screen counts as unchanged and the scan is skipped. Lower is more aggressive deduplication.
note

accessibility.intelligentScan and accessibility.intelligentScanThreshold only have meaning when accessibility.autoScan is true. In a session where AutoScan is off, both keys are dropped and the session runs as before, with hook-driven scans only.

These capabilities sit alongside the scan-scoping capabilities (accessibility.wcagVersion, accessibility.bestPractice, accessibility.betaRules, accessibility.aiEnabled) described in Scan Configurations via Capabilities, and the exclusion capabilities described in Rule and Category Exclusion for Mobile App Accessibility. All of them apply to every AutoScan-triggered scan exactly as they apply to a hook-triggered one.

Example: enabling AutoScan​

Enable accessibility, turn AutoScan on, target WCAG 2.1 AA, and leave intelligent scan at its default.

{
  "LT:Options": {
    "platformName": "Android",
    "deviceName": "Pixel 8",
    "platformVersion": "14",
    "isRealMobile": true,
    "app": "lt://APP1234567890",
    "accessibility": true,
    "accessibility.autoScan": true,
    "accessibility.wcagVersion": "wcag21aa"
  }
}

To scan after every triggering command, including repeated actions on the same screen, switch intelligent scan off:

{
  "accessibility": true,
  "accessibility.autoScan": true,
  "accessibility.intelligentScan": false
}

No change to your test code is required. The scan runs after the command that TestMu AI already receives from your Appium client.

What triggers a scan​

AutoScan fires after a command that can change what is on the screen, and only when that command succeeded. Read-only commands never trigger a scan, so element lookups, attribute and text reads, explicit waits, source dumps and screenshots add nothing to your scan count.

Action in your testTriggers a scan
Tap, click, long press, double tapYes
Type into a field, clear a fieldYes
Swipe, scroll, flickYes
A W3C actions sequence (performActions)Yes
Device back navigationYes
Changing device orientationYes
Navigating to a URL in a webview contextYes
findElement, findElementsNo
Reading text, attributes or element stateNo
Explicit and implicit waitsNo
Taking a screenshot, fetching page sourceNo
A command that failed or returned an errorNo

The scan is taken after the command completes, so it captures the screen your app arrived at, not the one it left.

note

A command that changes the screen only after an asynchronous load, for example a tap that opens a screen whose content arrives over the network, can be scanned before that content is painted. Add an explicit wait after the command, or use the lambda-accessibility-scan hook for that screen, if the timing matters. This is the same behaviour as autoScan on web. See Accessibility FAQ.

Intelligent scan​

Intelligent scan is what keeps an interaction-heavy test from producing dozens of near-identical reports.

Before each triggered scan, TestMu AI compares the current screen with every screen scanned so far in the session and produces a visual similarity percentage. If that percentage is at or above accessibility.intelligentScanThreshold, the screen is treated as unchanged and the scan is skipped.

ThresholdEffect
95 (default)Skips repeat scans of the same screen while still catching small but real changes, such as a validation error appearing under a field.
Higher, for example 98Stricter. Almost any pixel difference counts as a new screen, so more scans run.
Lower, for example 50Aggressive. Only clearly different screens are scanned, which is useful on flows with a lot of animation or changing content.
intelligentScan: falseNo comparison at all. Every triggering command produces a scan. Expect roughly twice the scans of a default AutoScan run on an interaction-heavy flow.

Comparison is against every screen scanned so far in the session, not just the last one, so a flow that moves A → B → A scans A once and B once.

Pausing and resuming AutoScan​

Some parts of a run are not worth scanning: a login sequence, a fixture setup, or a third-party payment screen you do not own. The lambda-accessibility-scan hook doubles as a pause and resume switch for an AutoScan session.

// Stop AutoScan from scanning the next part of the flow
driver.executeScript("lambda-accessibility-scan", Map.of("scan", false));

// ... setup, login, or any flow you do not want scanned ...

// Resume automatic scanning
driver.executeScript("lambda-accessibility-scan", Map.of("scan", true));
Hook payloadIn an AutoScan sessionIn a session without AutoScan
{"scan": false}Pauses AutoScan. Triggering commands stop producing scans until it is resumed.Accepted, no effect.
{"scan": true}Resumes AutoScan from the next triggering command.Accepted, no effect.
No payloadRuns a single scan immediately, as it always has.Runs a single scan immediately.

Pausing does not end the session's accessibility coverage. Everything scanned before the pause is kept, and scanning picks up again from the command after the resume. A paused session can still take a one-off scan by calling the hook without a payload.

Android and iOS​

The scan itself, the rules evaluated and the report produced are identical on both platforms. The difference is in timing.

AndroidiOS
When the scan runsIn the background, after the Appium command has already returned to your testBefore the Appium command returns to your test
Added latency per scanned commandEffectively noneThe scan duration, up to about 90 seconds on a dense screen
Effect on your testNone. The suite runs at its normal speed.Commands that trigger a scan take noticeably longer, and total suite time grows with the number of scanned screens.

This is a platform constraint, not a setting. On iOS the accessibility scan and the Appium session share the same device-side bridge, so the scan has to complete before the session continues.

warning

Plan for longer iOS runs before enabling AutoScan on a large suite. Raise any per-command or per-test timeouts in your framework, and consider a lower accessibility.intelligentScanThreshold so fewer screens are scanned. A quick way to gauge the cost is to run one representative test with AutoScan on and compare its duration with the same test on hook-driven scans.

Capability combinations​

autoScanintelligentScanintelligentScanThresholdBehaviour
falseignoredignoredHook-driven scanning only. Identical to the behaviour before AutoScan existed.
truetrue (default)95 (default)A scan after each screen-changing command, skipped when the screen is at least 95% similar to the last scanned screen. The recommended starting point.
truetrue50Aggressive deduplication. Only clearly different screens are scanned.
truefalseignoredA scan after every screen-changing command, with no deduplication. Highest coverage and highest scan consumption.

Scan consumption​

Every scan AutoScan triggers is one accessibility scan, the same as a lambda-accessibility-scan call. A screen skipped by intelligent scan is not a scan and is not counted.

Consumption is therefore driven by the number of distinct screens your suite reaches, not by the number of commands it runs, as long as intelligent scan is on. Switching it off moves consumption back to one scan per triggering command. See How scan consumption works.

Working with other accessibility features​

  • Scan configuration. accessibility.wcagVersion, accessibility.bestPractice, accessibility.betaRules and accessibility.aiEnabled apply to every AutoScan-triggered scan in the session, exactly as they do to hook-triggered scans.
  • Rule and category exclusion. accessibility.excludeRules and accessibility.excludeRuleCategories are honoured on every AutoScan trigger. See Rule and Category Exclusion for Mobile App Accessibility.
  • AI-powered rules. Independent of how the scan was triggered. With accessibility.aiEnabled on, AI analysis runs for AutoScan scans as well.
  • Screen Reader Automation. AutoScan and Screen Reader Auto Report are mutually exclusive in a session. A session running the screen reader does not trigger AutoScan rule scans. Run them as two tests if you need both.
  • Tags. Tags applied to the session apply to every scan it produces. See Tag Support for Accessibility Scans.

What to expect in reports​

AutoScan scans land in exactly the same place as hook-driven scans, in the Accessibility dashboard under the same build and test. There is no separate AutoScan report type to learn.

  • Per screen. Each scan that ran is a screen entry in the report, with its screenshot, issues and score, in the order your test reached them.
  • Skipped screens. A screen skipped by intelligent scan does not produce an entry. If your report has fewer screens than you expected, that is usually why.
  • AutoScan pill. A test that ran with the AutoScan capability shows an AutoScan pill in the report, so an AutoScan run can be told apart from a hook-driven one.
  • Configuration recorded. The WCAG target, group toggles and any exclusions are stored with the test, as they are for hook-driven scans.

Individual scans within a session are not currently labelled with the trigger that produced them, so a session that mixes AutoScan with explicit hook calls shows both kinds of scan in one list.

Troubleshooting​

SymptomWhat to check
No scans at all in an AutoScan sessionaccessibility must be true in the same options block as accessibility.autoScan. On its own, accessibility.autoScan is ignored.
Fewer screens in the report than the test visitsIntelligent scan skipped screens it judged unchanged. Lower accessibility.intelligentScanThreshold is more aggressive, so raise it, or set accessibility.intelligentScan to false to confirm.
More scans than expectedIntelligent scan is off, or the screens genuinely differ, for example because of an animation, a carousel or a live timestamp. Lower the threshold.
A screen is scanned before its content loadsThe triggering command returned before the asynchronous content painted. Add an explicit wait, or scan that screen with the lambda-accessibility-scan hook instead.
iOS tests much slower after enabling AutoScanExpected. On iOS the scan completes before the command returns. See Android and iOS. Raise framework timeouts, or lower the threshold so fewer screens are scanned.
A setup or login flow appears in the reportPause AutoScan around it with {"scan": false} and resume after. See Pausing and resuming AutoScan.
Scans stopped part way through the runAutoScan was paused with {"scan": false} and never resumed. Send {"scan": true}.
No screen reader results in an AutoScan sessionAutoScan and Screen Reader Auto Report are mutually exclusive. Run the screen reader as a separate test.

FAQ​

Do I have to remove my existing lambda-accessibility-scan calls? No. Hook calls keep working in an AutoScan session and run a scan immediately. Leave them where you want a guaranteed scan at a precise moment, and remove the ones that only existed to get coverage.

Is AutoScan supported on emulators and simulators? No. AutoScan is a real-device capability, the same as the rest of mobile app accessibility scanning.

Does AutoScan work with hybrid apps? No. Accessibility scanning supports native Android and iOS apps only. To check embedded web content, test the web application directly with web Automation or Manual Testing (DevTools).

Can I set the threshold per screen? No. accessibility.intelligentScanThreshold is a session-level setting. To force a scan on a specific screen regardless of similarity, call the lambda-accessibility-scan hook there.

What happens if the triggering command fails? No scan is taken. AutoScan only fires after a command that succeeded.

Does AutoScan change what a scan checks? No. The rules, the WCAG scoping and the exclusions are the same regardless of what triggered the scan. Only the trigger differs.

Last updated on

Terminal First Testing With Kane CLI

Natural language browser & mobile app tests right from terminal.

×
Schedule Your Personal Demo
Kane CLI terminal

Help and Support

Related Articles