Testing and Troubleshooting Accessibility

You can follow every rule in lesson 47 and still ship a barrier. A description can be present but meaningless, a reading order can be technically valid but confusing, and a contrast ratio can pass while the screen is still tiring to read. Accessibility has to be tested, with a mix of manual checks by a human and automated checks that catch the mechanical mistakes every time you build.

This lesson covers Test your app's accessibility, Testing for Accessibility and the Make your Android app accessible quiz of the pathway (https://developer.android.com/courses/pathways/make-your-android-app-accessible), together with the accessibility-testing guidance at https://developer.android.com/guide/topics/ui/accessibility/testing.

By the end you will be able to:

• Run a structured manual test with TalkBack, Switch Access, Voice Access, large text and grayscale.
• Use Accessibility Scanner and read its suggestions.
• Add automated accessibility checks to UI tests (for Views with Espresso, and for Compose).
• Use lint and Studio inspections to catch issues early.
• Write accessibility test cases with Compose test APIs: labels, roles, states, sizes.
• Review your app from your users' perspective, and plan user testing with people with disabilities.
• Build an accessibility checklist for your team, and answer the pathway's quiz questions.

Big idea: automated tools find roughly the mechanical problems (a missing label, a small target, low contrast). Humans find the problems that matter most: a confusing order, a useless description, a task that takes 40 swipes. You need both.

• Accessibility fundamentals and common problems (lesson 46).
• Compose accessibility features (lesson 47).
• Compose UI testing (lesson 45) and Espresso basics (lesson 20 for test folders).
• Android Studio tools (lesson 44).

   MANUAL (humans)                          AUTOMATED (machines)
 +-------------------------------+      +--------------------------------------+
 | 5. User testing with people   |      | 1. Lint + IDE inspections (build time)|
 |    who use assistive tech     |      | 2. Unit tests: contrast, strings      |
 | 4. Screen reader walkthrough  |      | 3. UI tests with accessibility checks |
 | 3. Large text / display size  |      | 4. Accessibility Scanner (semi-auto)  |
 +-------------------------------+      +--------------------------------------+
        slow, rich, subjective                fast, repeatable, shallow

A common figure quoted in the industry is that automated tools can catch only a minority of possible accessibility issues, so never treat a green automated check as proof of accessibility.

A good manual test is a script, not a feeling. For each main task in your app (say, "add an item to the order and pay"), do this:

1. Set up: a real device or an emulator image with Play Services and TalkBack (from the Android Accessibility Suite). Turn TalkBack on, and set speech rate to a speed you can follow. Start from the first screen with the screen dimmed or turned off if possible (some devices have a screen curtain option in TalkBack settings so you cannot rely on sight).
2. Linear navigation: swipe right repeatedly from the top to the end of the screen. Listen to each stop. Ask: - Does every stop make sense on its own? ("Button" alone is a failure.) - Is the order logical? Does it match the visual order? - Is anything missing that you can see? Is anything announced that you cannot see? - Are there too many stops (every word in a card is its own stop)?
3. Explore by touch: drag a finger over the screen. Does the element under your finger match what you hear?
4. Activate each control with a double tap. Does the result get announced (focus moves sensibly, a message is spoken)?
5. Forms: is each field announced with its label, hint and error? After a validation error, is the error announced and is focus placed on the problem field?
6. Dialogs, menus, bottom sheets: does focus move into them, stay inside while open, and return to the trigger on close?
7. Dynamic content: a toast, snackbar or loading finishing: does the user learn about it?
8. Headings and landmarks: use TalkBack's headings navigation mode (or reading controls) to jump between headings. If it says "no headings", mark them.
9. Lists: are item positions announced ("item 3 of 20")? Does a long list let you move quickly?
10. Time: is any step timed with no way to extend?

Then repeat a lighter test with:

• Switch Access (or a keyboard connected over USB or Bluetooth: Tab and arrow keys should move focus, Enter activates): can you reach and operate everything? Is the focus indicator visible?
• Voice Access: say "Show labels" or "Show numbers", then try to tap controls by name. Controls whose visible text and accessible name differ ("Pay now" shown, "Submit" announced) are hard to say; keep them the same.
• Largest font and display size: any clipping, overlap or hidden buttons? Landscape too.
• Grayscale and high-contrast text: can you still tell states apart?
• Remove animations: does everything still work?

Record every issue as a bug with: screen, step, expected, actual, assistive technology used and severity. Use the blocker/major/minor scale from lesson 46.

Accessibility Scanner is a free app from Google (install it from the Play Store, then enable it in Settings → Accessibility). Once enabled, a floating check-mark button appears over every app.

1. Open your app on the screen you want to check.
2. Tap the floating button, then the tick. The scanner takes a snapshot.
3. It highlights elements and lists suggestions, typically: - Touch target size: "Item's height is 32dp. Consider making the clickable area at least 48dp." - Text contrast: "Increase the contrast ratio to at least 4.5:1." - Item label: "This item may not have a label readable by screen readers." - Image contrast, Item type and others such as editable items and duplicated clickable bounds, depending on the version.
4. Each suggestion has a Learn more link and the element's details.
5. Fix, rebuild, rescan.

Limits: it checks what is on screen at the moment of the scan (so scan every state: empty, loading, error, filled), and it cannot judge whether a label is good. Save the scan results as part of the bug report.

Compose UI tests (lesson 45) can run accessibility checks over the rendered semantics and UI. The API for this has been evolving, and some functions carry an @ExperimentalTestApi annotation, so check the Testing your Compose layout and accessibility testing pages for the exact names in your Compose version. The general shape is:

import androidx.compose.ui.test.ExperimentalTestApi
import androidx.compose.ui.test.junit4.createComposeRule
import androidx.compose.ui.test.junit4.accessibility.enableAccessibilityChecks
import org.junit.Before
import org.junit.Rule
import org.junit.Test
class OrderScreenA11yTest {
 @get:Rule
 val rule = createComposeRule()
 @OptIn(ExperimentalTestApi::class)
 @Before
 fun enableChecks() {
 rule.enableAccessibilityChecks() // runs the Accessibility Test Framework on each action
 }
 @Test
 fun orderScreenHasNoCheckFailures() {
 rule.setContent { OrderScreen() }
 // Any action or assertion that triggers a check will fail the test with a clear message
 rule.onRoot().assertExists()
 }
}

When checks are enabled, the framework runs Google's Accessibility Test Framework (ATF) checks (touch target size, label presence, contrast of text where measurable, duplicated clickable bounds, and more) against the real rendered tree and fails the test if a check is violated. If an API in this form is not available in your version, you can still write your own explicit tests, as in the next sections.

Write your own explicit accessibility assertions

Explicit tests encode decisions your team made, and they work on any Compose version.

import androidx.compose.ui.semantics.Role
import androidx.compose.ui.semantics.SemanticsProperties
import androidx.compose.ui.test.assert
import androidx.compose.ui.test.assertHasClickAction
import androidx.compose.ui.test.assertHeightIsAtLeast
import androidx.compose.ui.test.assertWidthIsAtLeast
import androidx.compose.ui.test.hasContentDescription
import androidx.compose.ui.test.junit4.createComposeRule
import androidx.compose.ui.test.onNodeWithContentDescription
import androidx.compose.ui.test.onNodeWithText
import androidx.compose.ui.test.SemanticsMatcher
import androidx.compose.ui.unit.dp
import org.junit.Rule
import org.junit.Test
class OrderScreenSemanticsTest {
 @get:Rule
 val rule = createComposeRule()
 @Test
 fun deleteButtonIsLabelledAndBigEnough() {
 rule.setContent { OrderScreen() }
 rule.onNodeWithContentDescription("Delete Zobo")
 .assertHasClickAction()
 .assertWidthIsAtLeast(48.dp)
 .assertHeightIsAtLeast(48.dp)
 }
 @Test
 fun payIsAButton() {
 rule.setContent { OrderScreen() }
 rule.onNodeWithText("Pay now").assert(
 SemanticsMatcher.expectValue(SemanticsProperties.Role, Role.Button)
 )
 }
}

assertWidthIsAtLeast and assertHeightIsAtLeast measure the node's size in dp: this is how you check the 48 dp rule in a test. SemanticsMatcher.expectValue(SemanticsProperties.Role, Role.Button) checks the role. Define small helper matchers when you repeat a check often:

import androidx.compose.ui.semantics.SemanticsProperties
import androidx.compose.ui.test.SemanticsMatcher
fun hasHeading() = SemanticsMatcher.keyIsDefined(SemanticsProperties.Heading)
fun hasLiveRegion() = SemanticsMatcher.keyIsDefined(SemanticsProperties.LiveRegion)
fun hasStateDescription(text: String) =
 SemanticsMatcher.expectValue(SemanticsProperties.StateDescription, text)

@Test
fun titleIsAHeading() {
 rule.setContent { OrderScreen() }
 rule.onNode(hasText("Your order") and hasHeading()).assertExists()
}

Test all the font sizes

import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.test.assertIsDisplayed
import androidx.compose.ui.test.onNodeWithText
import androidx.compose.ui.unit.Density
import androidx.compose.material3.MaterialTheme
import org.junit.Test
@Test
fun payButtonStillVisibleAtLargestFont() {
 rule.setContent {
 val base = LocalDensity.current
 CompositionLocalProvider(LocalDensity provides Density(base.density, fontScale = 2f)) {
 MaterialTheme { OrderScreen() }
 }
 }
 rule.onNodeWithText("Pay now").assertIsDisplayed()
}

Unit-test your contrast

In lesson 47 you wrote contrastRatio. Put every custom colour pair of your design system into one test, so a designer's palette change that breaks accessibility fails the build:

package com.example.accessdemo
import androidx.compose.ui.graphics.Color
import org.junit.Assert.assertTrue
import org.junit.Test
class ThemeContrastTest {
 private val pairs = mapOf(
 "primary on primaryContainer" to (Color(0xFF00210D) to Color(0xFFA8F5B7)),
 "onSurface on surface" to (Color(0xFF1A1C19) to Color(0xFFFCFDF7)),
 "onError on error" to (Color(0xFFFFFFFF) to Color(0xFFBA1A1A))
 )
 @Test
 fun allTextPairsMeetAA() {
 pairs.forEach { (name, colours) ->
 val ratio = contrastRatio(colours.first, colours.second)
 assertTrue("$name has contrast $ratio, needs 4.5", ratio >= 4.5f)
 }
 }
}

If your app still has View screens (lesson 42), Espresso can run the same ATF checks. Add the dependency androidx.test.espresso:espresso-accessibility as androidTestImplementation (use the version that matches your Espresso version) and enable checks once:

package com.example.classregister
import androidx.test.espresso.accessibility.AccessibilityChecks
import org.junit.BeforeClass
class AccessibleScreenTest {
 companion object {
 @JvmStatic
 @BeforeClass
 fun enableAccessibilityChecks() {
 AccessibilityChecks.enable().setRunChecksFromRootView(true)
 }
 }
 // Every ViewAction (click, typeText ...) now runs the checks on the views involved.
}

With setRunChecksFromRootView(true) the checks run against the whole screen, not just the view you touched. When a check fails, the exception message names the view, the check and the problem. You can suppress a known issue deliberately with setSuppressingResultMatcher, but record why, and fix it later.

Lint checks run on your source without launching the app:

• Run: Analyze → Inspect Code in Studio, or in a terminal: ./gradlew lint (the HTML report is in app/build/reports/lint-results-debug.html).
• For Views, lint flags ImageView and ImageButton without contentDescription (ContentDescription), touch targets smaller than 48 dp (TouchTargetSizeCheck), editable text without labels (LabelFor), colour contrast issues (TextContrastCheck), and hard-coded strings.
• For Compose, lint has checks for common mistakes in modifiers and state, and some accessibility-related rules; the available checks vary by library version.
• Treat accessibility warnings as errors in CI by adding a lint configuration:

android {
 lint {
 warningsAsErrors = false
 error += setOf("ContentDescription", "LabelFor")
 abortOnError = true
 }
}

The error += setOf(...) line raises the severity of those two checks so the build fails if they appear. Be careful with warningsAsErrors = true: it can fail builds on unrelated warnings.

Tools check rules. People check reality. A practical review has four steps.

1. Write user stories with assistive technology

"As a blind student, I want to add my order and pay using TalkBack alone so that I do not need someone to help me." Write one per major task and per kind of need (screen reader, switch, voice, low vision, motor, hearing, cognitive).

2. Walk the stories

Do each task with only the assistive tech in question. Time it. If a sighted person needs 5 taps and a TalkBack user needs 40 swipes, the design needs shortcuts (headings, grouped items, fewer stops).

3. Check the content, not only the controls

• Plain language. Short sentences, no jargon, one idea per instruction.
• Errors that help: "Phone number must have 11 digits" is better than "Invalid input".
• Consistency: the same icon and word always mean the same thing; navigation stays in the same place.
• Forgiveness: confirmation before destructive actions; an undo.
• No time pressure without a way to extend it.
• No flashing more than three times per second.
• Not only sound and not only colour.

4. Involve real users

Nothing replaces testing with people who use assistive technology daily. Reach out to local disability organisations, schools for the blind and deaf, or university disability services; offer fair payment or a clear benefit; explain what you will record; let them use their own device and settings; observe, do not coach; and treat every difficulty as a bug in the app, not a problem with the person. Always get consent and protect their privacy.

Even without participants, you can invite team members to use a "day without a screen" or one-handed constraints for an hour, as a start (but this builds empathy and does not replace real user research).

Mistake #1: Relying only on Accessibility Scanner. Fix: add a TalkBack script and automated tests.

Mistake #2: Testing only one state. Fix: scan empty, loading, error and filled states.

Mistake #3: Suppressing checks without a note. Fix: record the reason and a ticket to fix it.

Mistake #4: Running TalkBack only in English with default speed. Fix: also test with your users' languages and a realistic speed.

Mistake #5: Letting designers change colours without contrast tests. Fix: a palette unit test.

Mistake #6: Testing with the developer's own phone settings only. Fix: test with large display size and font on a mid-range device.

Mistake #7: "Fixed" without re-testing in assistive tech. Fix: re-run the script after each fix.

Mistake #8: Recruiting no real users and calling it done. Fix: plan a session with real users before major releases.

Mistake #9: Treating accessibility bugs as low priority polish. Fix: triage by who is blocked.

Mistake #10: Not including accessibility in the definition of done. Fix: add the checklist to every feature.

These five questions mirror the style of the pathway's final quiz.

Question 1. Which tool can scan a running app and suggest fixes for touch target size and contrast?

Question 2. Why can automated checks not guarantee that an app is accessible?

Question 3. How can a Compose test check the 48 dp touch target rule?

Question 4. What should you do after finding an accessibility bug with TalkBack?

Question 5. Why test with real users who use assistive technology?

Go deeper: official resources

• Make your Android app accessible pathway
• Testing your app's accessibility
• Starting with Android accessibility codelab
• Android Basics with Compose, Unit 3 (accessibility content)