Skip to main content

Automated Voice Assisted Accessibility Testing on iOS

Automated Voice Assisted Accessibility Testing allows you to assess how your application behaves when VoiceOver is enabled. With Appium, you can move through accessible elements, retrieve VoiceOver announcements, and validate the results in your tests.

For manual testing in Mobile Studio, refer to Voice Assisted Accessibility Testing.

Prerequisites​

  • A real iOS device running iOS 27 or later.
  • Appium-based tests. Appium 3 or later is recommended.

Enabling VoiceOver​

Enable VoiceOver from your test:

driver.executeScript("mobile: enableVoiceOver");

Check whether VoiceOver is enabled:

boolean enabled = (Boolean) driver.executeScript("mobile: isVoiceOverEnabled");
tip

Disable VoiceOver in a finally block or test teardown.

Functionality Overview​

Use mobile: voiceOverMove to change VoiceOver focus. The command returns the announcement text after the move, or null if no utterance is available.

import java.util.Map;

String speech = (String) driver.executeScript(
"mobile: voiceOverMove",
Map.of("direction", "forward")
);

System.out.println("VoiceOver: " + speech);

The following directions are available:

DirectionAction
forwardMove to the next accessible element.
backwardMove to the previous accessible element.
inMove into the current container.
outMove out of the current container.

Container navigation depends on how the application groups its accessible content. Moving out does not mean returning to the previous application screen.

info

The VoiceOver commands covered in this guide are provided by Appium’s open-source XCUITest driver. For additional operations, use Digital.ai custom commands. These keyboard commands require a device configured with a connected Bluetooth adapter.

Retrieving VoiceOver Speech​

Retrieve the current announcement without moving focus:

String speech = (String) driver.executeScript("mobile: voiceOverCurrentSpeech");

This returns a string or null. Use the result to check the announcement for the focused element. It is not an audio recording or a history of announcements during the session.

Validating Announcements​

For example, you can move to the next accessible element with VoiceOver and check whether its announcement contains the expected text.

Before adding assertions, inspect the returned announcements.

String nextSpeech = (String) driver.executeScript(
"mobile: voiceOverMove",
Map.of("direction", "forward")
);

Assert.assertTrue(
nextSpeech != null && nextSpeech.contains("Password"),
"Expected a Password announcement. Received: " + nextSpeech
);

Disabling VoiceOver​

When the test finishes, disable VoiceOver:

driver.executeScript("mobile: disableVoiceOver");

Java Example​

The following TestNG example enables VoiceOver, moves forward and backward, and prints the returned announcements. It disables VoiceOver and closes the session when finished.

import io.appium.java_client.ios.IOSDriver;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.Map;
import org.openqa.selenium.remote.DesiredCapabilities;
import org.testng.Assert;
import org.testng.annotations.AfterMethod;
import org.testng.annotations.BeforeMethod;
import org.testng.annotations.Test;

public class AccessibilityTestiOS {

private IOSDriver driver;

@BeforeMethod
public void setUp() throws MalformedURLException {
DesiredCapabilities capabilities = new DesiredCapabilities();
capabilities.setCapability("platformName", "iOS");
capabilities.setCapability("appium:automationName", "XCUITest");
capabilities.setCapability("appium:udid", "YOUR_DEVICE_UDID");
capabilities.setCapability("appium:bundleId", "YOUR_APP");
capabilities.setCapability("digitalai:accessKey", "YOUR_ACCESS_KEY");
capabilities.setCapability("digitalai:appiumVersion", "3.5.2");
capabilities.setCapability("digitalai:testName", "iOS VoiceOver Test");

driver = new IOSDriver(
new URL("https://YOUR_ENVIRONMENT/wd/hub"),
capabilities
);
}

@Test
public void navigateWithVoiceOver() {
try {
driver.executeScript("mobile: enableVoiceOver");

String nextSpeech = (String) driver.executeScript(
"mobile: voiceOverMove",
Map.of("direction", "forward")
);
System.out.println("Next element: " + nextSpeech);

Assert.assertTrue(
nextSpeech != null && nextSpeech.contains("Password"),
"Expected a Password announcement. Received: " + nextSpeech
);

String previousSpeech = (String) driver.executeScript(
"mobile: voiceOverMove",
Map.of("direction", "backward")
);
System.out.println("Previous element: " + previousSpeech);

String currentSpeech = (String) driver.executeScript(
"mobile: voiceOverCurrentSpeech"
);
System.out.println("Current announcement: " + currentSpeech);
} finally {
driver.executeScript("mobile: disableVoiceOver");
}
}

@AfterMethod(alwaysRun = true)
public void tearDown() {
if (driver != null) {
driver.quit();
}
}
}