mobile-a11y-test-author

Extends the core AccessibilityChecks.enable() example in ../SKILL.md (opens in new window). Checks run automatically on any ViewActions action and cover the acted-on view plus all descendant views (atf (opens in new window)).

Add the dependency

// app/build.gradle
dependencies {
    androidTestImplementation 'androidx.test.espresso:espresso-accessibility:3.6.1'
}

Enable checks from the root view

import androidx.test.espresso.accessibility.AccessibilityChecks

@RunWith(AndroidJUnit4::class)
class CheckoutAccessibilityTest {
    init {
        AccessibilityChecks.enable().setRunChecksFromRootView(true)
    }

    @Test
    fun applyPromoCode() {
        onView(withId(R.id.promo_field)).perform(typeText("WELCOME10"), closeSoftKeyboard())
        onView(withId(R.id.apply_button)).perform(click())
        // checks fire automatically on every perform()
    }
}

setRunChecksFromRootView(true) evaluates the whole hierarchy, not just the interacted view (atf (opens in new window)).

Suppress known issues

AccessibilityChecks.enable().apply {
    setSuppressingResultMatcher(
        allOf(
            matchesCheck(TextContrastCheck::class.java),
            matchesViews(withId(R.id.decorative_watermark))
        )
    )
}

The matcher must satisfy both the check type and the specific view (atf (opens in new window)).

Touch target size (48dp minimum)

Each interactive UI element should have a focusable area of at least 48dp x 48dp (atgt (opens in new window)). AccessibilityChecks validates this on every perform() call.

Contrast thresholds

AccessibilityChecks (via the Accessibility Test Framework) checks these on every perform() call (contrast (opens in new window)):

• Text smaller than 18sp, or bold text smaller than 14sp: minimum contrast ratio 4.5:1.
• All other text: minimum contrast ratio 3:1.

contentDescription labelling

Convey purpose, not visual detail (cd (opens in new window)):

// Icon-only button: set contentDescription
Icon(
    imageVector = Icons.Filled.Share,
    contentDescription = stringResource(R.string.label_share)
)

// Decorative image: suppress from accessibility
Icon(
    imageVector = Icons.Filled.Decoration,
    contentDescription = null   // TalkBack skips this element
)

• Text composables need no contentDescription; TalkBack reads text content automatically.
• List items need distinct descriptions so a screen reader does not repeat the same label.

Verify with Espresso:

onView(withId(R.id.share_button))
    .check(matches(withContentDescription(R.string.label_share)))

TalkBack manual workflow

Enable via Settings > Accessibility > TalkBack > On, then (at (opens in new window)):

1. Linear navigation: swipe right/left through elements in order; double-tap to activate.
2. Explore by touch: drag to hear elements under your finger.

Manual checklist:

• All interactive elements are reachable via swipe.
• Each element announces its purpose clearly and without redundancy.
• Alert messages are announced when they appear.
• Focus traversal order matches the visual reading order.

References

• Espresso accessibility checking (opens in new window) - AccessibilityChecks.enable(), setRunChecksFromRootView(true), setSuppressingResultMatcher(), per-action firing.
• Large controls (opens in new window) - 48dp x 48dp minimum touch target.
• Text visibility (opens in new window) - 4.5:1 for text <18sp or bold <14sp; 3:1 for all other text.
• Describe UI elements (opens in new window) - contentDescription: purpose not visual detail, null for decorative, unique labels in lists.
• Accessibility testing (opens in new window) - TalkBack enable, linear navigation, explore-by-touch, manual checklist.

Extends the core performAccessibilityAudit() example in ../SKILL.md (opens in new window). The audit is available from iOS 17 and fails the test automatically when it finds an issue, so no explicit assertion is needed (wwdc23 (opens in new window)).

Scope the audit to specific categories

try app.performAccessibilityAudit(for: [.dynamicType, .contrast])

Pass an XCUIAccessibilityAuditType option set. Documented audit types include .dynamicType and .contrast; passing no argument runs all available checks (wwdc23 (opens in new window)).

Suppress known false positives

try app.performAccessibilityAudit(for: [.contrast]) { issue in
    // Ignore the decorative watermark label (no contrast fix planned)
    if let element = issue.element,
       element.label == "WatermarkLabel",
       issue.auditType == .contrast {
        return true   // suppress this issue
    }
    return false
}

The closure receives an XCUIAccessibilityAuditIssue; return true to suppress. Narrow suppressions by both auditType and element.label so real regressions still fail (wwdc23 (opens in new window)).

Cover each screen

Each call inspects only the currently visible elements. Navigate to every distinct screen and re-run the audit:

func testCheckoutFlowAudit() throws {
    let app = XCUIApplication()
    app.launch()
    try app.performAccessibilityAudit()          // Screen 1
    app.buttons["place-order-button"].tap()
    try app.performAccessibilityAudit()          // Screen 2
}

VoiceOver label, trait, and hint checks

accessibilityLabel is the localized string VoiceOver reads to identify an element, accessibilityHint describes the action result, and accessibilityTraits communicates purpose - common values are .button, .link, .header, .image, .staticText, .adjustable (uia (opens in new window)). Production code sets them; XCUITest verifies via XCUIElement.label:

// Production (UIKit)
let submitButton = UIButton()
submitButton.accessibilityLabel = "Submit order"
submitButton.accessibilityHint  = "Places your order and charges the saved card"
submitButton.accessibilityTraits = [.button]

// Test
func testSubmitButtonLabel() {
    let btn = XCUIApplication().buttons["Submit order"]
    XCTAssertTrue(btn.exists, "VoiceOver cannot find the Submit button")
    XCTAssertEqual(btn.label, "Submit order")
}

Touch target size (44pt minimum)

The minimum control size on iOS and iPadOS is 44x44 pt (hig (opens in new window)). Assert via XCUIElement.frame:

func testSubmitButtonTouchTarget() {
    let frame = XCUIApplication().buttons["Submit order"].frame
    XCTAssertGreaterThanOrEqual(frame.width,  44, "Touch target width below 44pt")
    XCTAssertGreaterThanOrEqual(frame.height, 44, "Touch target height below 44pt")
}

Accessibility Inspector (manual complement)

Open it from Xcode menu > Open Developer Tool > Accessibility Inspector. It runs the same checks as performAccessibilityAudit() interactively on real devices and simulators - use it to diagnose an audit failure before writing a suppression (wwdc23 (opens in new window)).

References

• Perform accessibility audits for your app (opens in new window) - performAccessibilityAudit(), XCUIAccessibilityAuditType, per-screen guidance, continueAfterFailure = true recommendation, suppression closure.
• UIAccessibilityElement (opens in new window) - accessibilityLabel, accessibilityHint, accessibilityTraits.
• Human Interface Guidelines: Accessibility (opens in new window) - 44x44 pt minimum control size.