Get your setup working faster. Join our Discord for optimisation tips from elite testers.

Test video injection with Maestro on BrowserStack

Replace the device camera feed with your own video during a Maestro test on BrowserStack App Automate.

This feature is available only under Device Cloud Pro, Device Cloud Pro + Visual Cloud, and Enterprise Pro plans. For more details, check out our pricing page.

On BrowserStack App Automate, you can replace the live camera feed in a Maestro test with a video that you upload. Your app receives the injected video as though the camera recorded the video. Use video injection to automate flows that record a video, such as identity verification, video messages, and in-app video capture.

You choose which video to inject at each step. A single flow can use several videos in sequence.

Prerequisites

Before you start, make sure you have the following:

Your BrowserStack username and access key, available in the Account & Profile section of your dashboard.
An iOS app as an .ipa file. Video injection with Maestro doesn’t support Android apps.
A Maestro test suite zipped inside a single parent folder, as described in Prepare your Maestro test suite.
The video you want to inject, in the format listed in Upload your video to BrowserStack.

Run a Maestro test with video injection

Complete the following steps to inject a video into the camera during a Maestro test:

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 video to BrowserStack

Upload each video you want to inject using the following cURL command:

Copy

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

Copy

BrowserStack accepts video files in the .mp4 format only.
The maximum file size is 15 MB.

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:

```javascript
// BrowserStack executor for Maestro. Don't edit this file. Set the action and its values in the runScript env block.

var url = typeof BROWSERSTACK_EXECUTOR_URL !== 'undefined' ? BROWSERSTACK_EXECUTOR_URL : null;
var sessionId = typeof BROWSERSTACK_SESSION_ID !== 'undefined' ? BROWSERSTACK_SESSION_ID : null;
var action = typeof BROWSERSTACK_EXECUTOR_ACTION !== 'undefined' ? BROWSERSTACK_EXECUTOR_ACTION : null;

if (!url || !sessionId) {
  throw new Error('[EXECUTOR] session is not wired for the executor channel ' +
    '(missing BROWSERSTACK_EXECUTOR_URL / BROWSERSTACK_SESSION_ID). ' +
    'Ensure the build enables the feature and is a BrowserStack Maestro session.');
}
if (!action) {
  throw new Error('[EXECUTOR] BROWSERSTACK_EXECUTOR_ACTION is not set in the runScript env: block.');
}

var headers = { 'X-BrowserStack-Session-Id': sessionId };

var params = [];

if (typeof MEDIA_ID !== 'undefined' && MEDIA_ID) {
  params.push('mediaID=' + encodeURIComponent(MEDIA_ID));
}
if (typeof RESULT !== 'undefined' && RESULT) {
  params.push('result=' + encodeURIComponent(RESULT));
}
if (typeof DATA !== 'undefined' && DATA) {
  params.push('data=' + encodeURIComponent(DATA));
}

var query = params.join('&');

var response;
try {
  response = http.get(url + '/' + encodeURIComponent(action) + (query ? '?' + query : ''), { headers: headers });
} catch (e) {
  console.log('[EXECUTOR] action=' + action + ' status=unreachable reason=executor_unreachable');
  throw new Error('[EXECUTOR] ' + action + ' could not reach the injection service.');
}

var status = (response && typeof response.status !== 'undefined') ? response.status : 'unknown';

var reason = '';
var detail = '';
try {
  var parsed = (response && response.body) ? JSON.parse(response.body) : null;
  if (parsed) {
    reason = parsed.error_reason ? String(parsed.error_reason) : '';
    detail = parsed.message ? String(parsed.message) : '';
  }
} catch (e) { reason = ''; detail = ''; }

console.log('[EXECUTOR] action=' + action + ' status=' + status +
  (reason ? ' reason=' + reason : '') + (detail ? ' detail=' + detail : ''));

if (!response || !response.ok) {
  throw new Error('[EXECUTOR] ' + action + ' failed (HTTP ' + status + ')' +
    (reason ? ': ' + reason : '') + (detail ? ' - ' + detail : ''));
}
```

Copy

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.

Keep the bstack folder inside the parent folder that you zip, alongside your flow files. If the bstack folder sits outside the parent folder, the runScript step can’t resolve the path to the script. For the required layout, see Prepare your Maestro test suite.

Inject the video from your flow

Add a runScript step to your flow at the point where the uploaded video must replace the camera feed. Add the step before your app opens the camera, because the camera uses the video that was injected most recently:

Copy

The env block sets the following values:

BROWSERSTACK_EXECUTOR_ACTION names the action to run. Use inject_video for video injection.
MEDIA_ID is the media_url that the media upload returns. Pass a media ID that you also list in cameraInjectionMedia when you start the build.

To use a second video later in the same flow, add another runScript step with a different MEDIA_ID.

Run your test with video injection

Set enableCameraVideoInjection to true and list your uploaded videos in cameraInjectionMedia when you start the build:

Copy

The following table describes the video injection parameters:

Parameter	Type	Description
`enableCameraVideoInjection`	Boolean	Set to `true` to allow your flow to replace the device camera feed with an uploaded video. Required for video injection.
`cameraInjectionMedia`	Array of strings	Lists the media IDs that your flow can inject, as returned by the media upload. Accepts up to five media IDs. Required for video injection.

Video injection on Maestro has the following limitations:

Video injection runs on iOS real devices only, not on Android devices, simulators, or emulators.
A build must set enableCameraVideoInjection and cameraInjectionMedia together. BrowserStack rejects a build that sets one parameter without the other.
cameraInjectionMedia accepts up to five media IDs per build.
A flow can inject only the videos that you list in cameraInjectionMedia. You can’t upload a video or pass a URL during the test.

Check the injection result in your logs

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

[EXECUTOR] action=inject_video status=200

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

media_not_found: the MEDIA_ID in your flow isn’t one of the media IDs listed in cameraInjectionMedia.
executor_unreachable: the flow couldn’t reach the BrowserStack injection service.
scope_denied: the build didn’t set enableCameraVideoInjection, so the session doesn’t allow video injection.

To read these lines, see Maestro logs.

Frequently asked questions

Do I need to change my app code?

No. BrowserStack modifies the app you upload, so your source code stays unchanged.

Can I change the video partway through a flow?

Yes. Add a runScript step wherever the flow needs a new video. The camera uses the video that was injected most recently.

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Is this page helping you?

Yes

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback!

Test video injection with Maestro on BrowserStack

Prerequisites

Run a Maestro test with video injection

Upload your app and test suite

Upload your video to BrowserStack

Add the BrowserStack executor script to your test suite

Inject the video from your flow

Run your test with video injection

Check the injection result in your logs

Frequently asked questions

Do I need to change my app code?

Can I change the video partway through a flow?

Related topics

We're sorry to hear that. Please share your feedback so we can do better

We're continuously improving our docs. We'd love to know what you liked

We're sorry to hear that. Please share your feedback so we can do better

We're continuously improving our docs. We'd love to know what you liked