Test audio injection with Maestro on BrowserStack

Upload your app and test suite

Upload your app and your zipped Maestro test suite, then note the app_url and test_suite_url that each response returns. You need both values to start a build. For the upload commands, see Execute Maestro tests.

Upload your audio file to BrowserStack

Upload the audio file you want to play using the following cURL command:

The response returns a media_url. This value is the media ID that you pass to your flow:

Add the BrowserStack executor script to your test suite

Maestro doesn’t use the WebDriver protocol, so Maestro flows have no JavaScript executor of the kind that Appium tests use. BrowserStack provides a script that your flow calls with the runScript command instead. If you already added this script for camera image injection, reuse the same file.

At the root of your test suite’s parent folder, create a folder named bstack and save the following script as browserstack_executor.js:

Your test suite now has the following structure:

sample_parent_folder/
├── bstack/
│   └── browserstack_executor.js
├── flow1.yaml
└── flow2.yaml

Don’t edit browserstack_executor.js. The script reads the values that BrowserStack sets on the test session. Everything that varies between calls comes from the env block in your flow.

Play the audio from your flow

Audio injection uses three actions: inject_audio, play_audio, and stop_audio. To play an audio file, your flow runs the following steps in order:

1. inject_audio loads your uploaded audio file onto the device.
2. Your flow opens the screen in your app that listens to the microphone.
3. play_audio starts playing the audio into the microphone.
4. Your flow waits until your app processes the audio.

play_audio returns as soon as playback starts. It doesn’t wait for the audio to finish, so make sure your app is already listening before this step runs. Playback stops on its own at the end of the file, so you don’t need stop_audio to play the full clip.

The following flow shows each step:

The env block of each runScript step sets the following values:

• BROWSERSTACK_EXECUTOR_ACTION names the action to run: inject_audio, play_audio, or stop_audio.
• MEDIA_ID is the media_url that the media upload returns. Only the inject_audio action takes a MEDIA_ID.

Before the play_audio step, add the steps that open the microphone in your app and accept any microphone permission prompt. For more information, see Handle permission popups.

To let your app hear the full clip, add an extendedWaitUntil step after play_audio that waits for an element your app shows after it processes the audio. Set timeout, in milliseconds, longer than the length of your audio file. Maestro has no fixed-duration wait.

To cut playback short while the audio is still playing, add a stop_audio step:

To play a different audio file later in the same flow, add another inject_audio step with a different MEDIA_ID, followed by play_audio.

Run your test with audio injection

Set enableAudioInjection to true when you start the build:

The following table describes the audio injection parameter:

Check the injection result in your logs

Every call to browserstack_executor.js writes a status line to your Maestro logs. A successful call shows a line such as the following:

[EXECUTOR] action=play_audio status=200

A failed call adds a reason to the same line and stops the flow. The following reasons are the most common:

• media_not_found: BrowserStack can’t find the MEDIA_ID in your flow. Check that the media ID matches the media_url that the upload returned.
• executor_unreachable: the flow couldn’t reach the BrowserStack injection service.
• scope_denied: the build didn’t set enableAudioInjection, so the session doesn’t allow audio injection.

A stop_audio step that runs after the audio has ended fails with HTTP status 400 and the message No audio is currently playing.

To read these lines, see Maestro logs.