Skip to main content

Automate screen readers in Appium tests

You can switch TalkBack, Android's screen reader, on and off from inside an Appium test on TestingBot. This lets an automated test check how your app behaves when a TalkBack user opens it, for example that a screen still loads and that the layout holds up while TalkBack is running.

The switch is a TestingBot command that you send with executeScript. The full list of these commands is on JavaScript Executor Commands. To try a screen reader by hand, use the Accessibility panel in a Live session instead: see Screen Reader Testing.

Where it works

Platform From an Appium test
Real Android devices TalkBack on and off. Google's TalkBack, or Samsung's own TalkBack on Galaxy devices.
Android emulators TalkBack on and off, on Android 14 and newer. Older emulator images do not include TalkBack.
iOS simulators Not available. See VoiceOver on iOS.
Real iOS devices Not available. See VoiceOver on iOS.

Required capability: disableSuppressAccessibilityService

Appium's UiAutomator2 driver normally tells Android to suppress all other accessibility services while a test runs. If you leave that default in place, the TalkBack command below still turns the TalkBack setting on, but Android never starts TalkBack, so nothing is read out and nothing changes on screen.

Add this UiAutomator2 capability to every Android test that turns TalkBack on:

'appium:disableSuppressAccessibilityService': true

Live sessions set this for you. Automated sessions do not, because it changes how UiAutomator2 runs for tests that never use a screen reader.

Commands

Script Argument Effect on Android
tb:talkBack { enabled: true } or { enabled: false } Turns TalkBack on or off. Without an argument it turns TalkBack on.
tb:voiceOverStart none Turns TalkBack on.
tb:voiceOverStop none Turns TalkBack off.

Use tb:talkBack in Android tests: its name says what it does. The tb:voiceOverStart and tb:voiceOverStop commands exist so that one command works across platforms; in a desktop browser session they start VoiceOver on macOS or NVDA on Windows (see the notes per command).

Turning TalkBack on leaves any other accessibility service that is enabled on the device, for example one from your own app, enabled.

To change display settings such as font size, display size, bold text, high-contrast text or animations from the same test, use tb:a11ySettings. Its values are listed under tb:a11ySettings.

Examples

Each example starts a session on a real Android device with the capability from above, turns TalkBack on, checks the result, and turns TalkBack off again before it continues.

import io.appium.java_client.android.AndroidDriver;
import io.appium.java_client.android.options.UiAutomator2Options;

import java.net.URL;
import java.util.HashMap;
import java.util.Map;

public class TalkBackTest {
    public static void main(String[] args) throws Exception {
        UiAutomator2Options options = new UiAutomator2Options();
        options.setPlatformName("Android");
        options.setCapability("appium:deviceName", "Pixel 8");
        options.setCapability("appium:platformVersion", "14.0");
        options.setCapability("appium:app", "https://testingbot.com/appium/sample.apk");
        // Without this, UiAutomator2 keeps TalkBack from starting
        options.setCapability("appium:disableSuppressAccessibilityService", true);

        Map<String, Object> tbOptions = new HashMap<>();
        tbOptions.put("name", "TalkBack Test");
        tbOptions.put("realDevice", true);
        options.setCapability("tb:options", tbOptions);

        AndroidDriver driver = new AndroidDriver(
            new URL("https://api_key:api_secret@hub.testingbot.com/wd/hub"),
            options);

        try {
            Object result = driver.executeScript("tb:talkBack", Map.of("enabled", true));
            if (!"ok".equals(result)) {
                throw new IllegalStateException("TalkBack did not turn on: " + result);
            }

            // ... your checks with TalkBack running ...

            driver.executeScript("tb:talkBack", Map.of("enabled", false));
        } finally {
            driver.quit();
        }
    }
}
from appium import webdriver
from appium.options.android import UiAutomator2Options

options = UiAutomator2Options()
options.platform_name = 'Android'
options.set_capability('appium:deviceName', 'Pixel 8')
options.set_capability('appium:platformVersion', '14.0')
options.set_capability('appium:app', 'https://testingbot.com/appium/sample.apk')
# Without this, UiAutomator2 keeps TalkBack from starting
options.set_capability('appium:disableSuppressAccessibilityService', True)
options.set_capability('tb:options', {
    'name': 'TalkBack Test',
    'realDevice': True
})

driver = webdriver.Remote(
    'https://api_key:api_secret@hub.testingbot.com/wd/hub',
    options=options
)

try:
    result = driver.execute_script('tb:talkBack', {'enabled': True})
    assert result == 'ok', f'TalkBack did not turn on: {result}'

    # ... your checks with TalkBack running ...

    driver.execute_script('tb:talkBack', {'enabled': False})
finally:
    driver.quit()
const { remote } = require('webdriverio');

const capabilities = {
  'platformName': 'Android',
  'appium:app': 'https://testingbot.com/appium/sample.apk',
  'appium:deviceName': 'Pixel 8',
  'appium:platformVersion': '14.0',
  'appium:automationName': 'UiAutomator2',
  // Without this, UiAutomator2 keeps TalkBack from starting
  'appium:disableSuppressAccessibilityService': true,
  'tb:options': {
    'name': 'TalkBack Test',
    'realDevice': true
  }
};

(async () => {
  const driver = await remote({
    hostname: 'hub.testingbot.com',
    port: 443,
    protocol: 'https',
    path: '/wd/hub',
    connectionRetryTimeout: 420000, // real devices can queue for up to ~390s
    connectionRetryCount: 0,        // a retry would queue a second device request
    user: 'api_key',
    key: 'api_secret',
    capabilities
  });

  try {
    const result = await driver.executeScript('tb:talkBack', [{ enabled: true }]);
    if (result !== 'ok') {
      throw new Error(`TalkBack did not turn on: ${result}`);
    }

    // ... your checks with TalkBack running ...

    await driver.executeScript('tb:talkBack', [{ enabled: false }]);
  } finally {
    await driver.deleteSession();
  }
})();

For an Android emulator, leave out realDevice and pick an emulator on Android 14 or newer.

Check the result

The command does not raise an error when it fails. It returns a value instead:

  • "ok" when TalkBack is now on (or off, when you asked for off). TestingBot reads the device's accessibility settings back after the change to confirm this.
  • A message saying what went wrong in every other case, for example TalkBack is not installed on this device on an emulator older than Android 14, or an error message when you send tb:talkBack in a session that is not on Android.

Compare the return value with "ok", as the examples do, so a failed toggle fails your test instead of passing silently.

The value only confirms the setting. Whether TalkBack actually starts depends on the capability above: without it the command can return "ok" while TalkBack stays silent.

Things to know

  • Taps work differently while TalkBack is on. TalkBack turns on explore by touch: a single tap moves TalkBack's focus to an element instead of activating it. Steps of your test that tap or click elements can therefore stop doing what they did without TalkBack. Turn TalkBack off before steps that need ordinary taps, as the examples do.
  • Notification permission. On Android 13 and newer, TalkBack's first start can ask for permission to post notifications. TestingBot grants TalkBack that permission when it turns TalkBack on, so the dialog does not cover your app.

After the session

  • Android emulators and real Android devices: if your test turned TalkBack on, TestingBot turns it off again when the session ends, even when your test did not do so itself.
  • Real Android devices: the cleanup between sessions also switches off every accessibility service that is still enabled, including one your app or test turned on another way. The next session starts with no screen reader running.
  • Display settings changed with tb:a11ySettings are put back to the device's own values at the end of the session.

VoiceOver on iOS

VoiceOver cannot be switched on from an automated test on TestingBot:

  • On real iOS devices, tb:voiceOverStart and tb:voiceOverStop return a message that no screen reader is available on this platform.
  • In an iOS simulator session they do not control VoiceOver inside the simulator. Do not use them there.

To check your iOS app with VoiceOver, start a Live session on an iOS simulator and turn VoiceOver on in its Accessibility panel. See VoiceOver on iOS simulators.

Was this page helpful?
Last updated