Use VoiceOver executors with Maestro

Learn how to use executors to automate VoiceOver gestures, capture spoken output, and add accessibility assertions in Maestro flows on real iOS devices.

BrowserStack App Accessibility provides three VoiceOver executors that you can call using a Maestro flow on iOS devices:

• voiceOverToggle turns VoiceOver on or off.
• voiceOverGesture performs one VoiceOver gesture, such as moving focus to the next element or activating the focused element.
• getVoiceOverElement returns the most recent phrase from VoiceOver and the element that has the VoiceOver focus.

After your Maestro flow captures the returned values, you can check them with assertTrue assertions.

Prerequisites

Before you start, make sure you have the following:

• A BrowserStack username and access key. You can obtain your username and access key from the Account & Profile section on the dashboard.
  If you haven’t created an account yet, sign up for a free trial.
• An iOS app as an .ipa file.
• A Maestro test suite inside a single parent folder. For detailed steps, see Structure your Maestro accessibility tests.

Add the helper scripts to your test suite

BrowserStack provides a helper script for each executor. Save the three scripts in the same folder as the Maestro flow that calls them. The following example shows the folder structure:

flows/
├── voiceover-flow.yaml
├── bs_executor.js
├── bs_gesture.js
└── bs_get_element.js

Don’t edit the scripts. BrowserStack sets the session values that the scripts need, such as the session ID and device ID. Your flow passes the executor’s arguments to each script, as described in Call the executors from your flow.

VoiceOver toggle script

Save the following script as bs_executor.js to run the voiceOverToggle executor:

VoiceOver gesture script

Save the following script as bs_gesture.js to run the voiceOverGesture executor:

VoiceOver element script

Save the following script as bs_get_element.js to run the getVoiceOverElement executor and store the result in output.spokenDescription and output.element:

Call the executors from your flow

Add a runScript step to your Maestro flow for each executor call. Each step uses the following parameters:

• file: the helper script file, for example, bs_executor.js.
• env: the executor’s arguments, BS_STATE for bs_executor.js or BS_GESTURE for bs_gesture.js.
• label: the step name that appears in your Maestro logs.

Turn VoiceOver on or off

Call bs_executor.js with BS_STATE set to "on" or "off":

Simulate VoiceOver gestures

Call bs_gesture.js with BS_GESTURE set to the gesture you want to perform:

Gesture values

Gesture names are case-sensitive. See the following table for a list of valid values:

Capture the focused element and spoken output

Call bs_get_element.js to capture the element that has the VoiceOver focus and the most recent phrase from VoiceOver:

The script takes no env values and always reads the element that has the VoiceOver focus.

Captured values

After the step runs, your flow can use the following captured values:

• output.element: the element object as a JSON string.
• output.spokenDescription: the spokenDescription text.

The element object and spokenDescription text come from the executor’s result, which has the following fields:

output.spokenDescription and output.element are captured separately. If the spoken output can’t be captured, output.spokenDescription holds an empty string. If the element details can’t be captured, output.element holds {}. In either case, the step still succeeds, so add assertions only for the values that your test needs.

VoiceOver reads an element’s label, value, traits, and hint as separate phrases, so output.spokenDescription might hold only one of those phrases.

Add assertions

Add assertTrue steps to your Maestro flow to check output.spokenDescription and output.element, which hold the values from the most recent getVoiceOverElement call. The following steps check the spoken text and the element’s traits:

Maestro flow example

The following flow turns VoiceOver on, moves focus through two elements, checks each one, and turns VoiceOver off:

Run your build with VoiceOver

To run your build with VoiceOver enabled, follow these steps:

1. Zip your test suite folder with the helper scripts inside. For detailed steps, see Structure your Maestro accessibility tests.
2. Upload your app and test suite. For detailed steps, see Integrate Maestro test suite with App Accessibility testing.
3. Start the build with the iOS endpoint and voiceOver set to true:

With voiceOver set to true, your Maestro flow runs on a VoiceOver-enabled iOS device and can call the VoiceOver executors. If you don’t set voiceOver, the first executor step fails and the flow stops.

Check VoiceOver output and errors in your logs

Maestro builds run on BrowserStack App Automate, so the executor output appears in the Maestro Logs tab of your session on the App Automate dashboard. Use these logs to check the VoiceOver output for each element and to troubleshoot failed executor steps. For more information on Maestro logs, see View Maestro logs for your tests.

VoiceOver output

Each bs_get_element.js call adds the following to the Maestro Logs tab:

• The focused element as JSON
• The spoken description of that element

For example:

element   {"label":"Send","value":"","hint":"Double tap to send your message","traits":["Button"],"elementClass":"AccessibilityNode","identifier":"","frame":{"x":24,"y":204,"width":345,"height":52}}
spokenDescription   Send

The spoken output doesn’t appear in the Text Logs tab.

Executor errors

If an executor call returns an HTTP error, the step fails with an error message that starts with [EXECUTOR] and includes the HTTP status and response.

For example:

[EXECUTOR] voiceOverToggle on failed: HTTP <status> <response>

Related topics

• Auto-generate screen reader accessibility reports
• Maestro builds API reference