Stop Maestro builds automatically with fail fast

Automatically stop a Maestro build on App Automate after a specified number of flows fail to save device time and get results faster.

Continuing a test run after a known failure wastes limited device farm capacity. Fail fast aborts the build as soon as a specified failure threshold is reached, returning results faster and freeing up hardware for other queued jobs. It works for Maestro builds on both Android and iOS.

Enable fail fast

To enable fail fast, add testOrchestrationOptions.abortBuildOnFailure to your builds REST API request. Set enabled to true and maxFailures to the number of failed flows that stops the build.

Use the following cURL request for your platform:

Replace YOUR_USERNAME and YOUR_ACCESS_KEY with your BrowserStack credentials, and the bs:// IDs with the app and test suite IDs returned when you uploaded them.

Keep the following in mind:

• maxFailures accepts an integer from 1 to 1000.
• Setting enabled to true without maxFailures fails validation.

How failures are counted

Fail fast counts a flow as failed only after all its retries are exhausted.

When automatic reruns are active, the effect depends on the platform:

• iOS: Maestro reruns each failed flow immediately, so a failure becomes final while the build is still running. Fail fast stops the remaining flows as soon as the threshold is reached.
• Android: reruns happen in a separate pass after every flow has run once. By the time a failure becomes final, all flows have already run, so fail fast saves device time by cutting the retry pass short.

What happens when a build stops

Reaching the fail-fast threshold halts the build gracefully at the next flow boundary:

• In-progress flows: Run to completion and keep their real result. BrowserStack never stops a running flow mid-execution.
• Flows not yet started: Marked as skipped rather than failed, so your failure count stays accurate.

Stop a dependent flow sequence

Some user journeys, such as sign up, verify email, then complete profile, depend on the outcome of earlier flows. In addition to fail fast, you can use the Maestro continueOnFailure option in your workspace config.yaml file to stop the rest of an ordered sequence as soon as one flow in it fails.

Add an executionOrder block with a flowsOrder list, referencing each flow by its filename, minus the .yaml extension, or by the name value set inside that flow. Maestro works through your flowsOrder list first. Any other flow in your test suite that isn’t named in the list still runs, without a guaranteed position in the build.

The continueOnFailure flag decides what happens to the rest of the queue when a flow fails:

Upload your test suite with the updated config.yaml and reference it in the config parameter of your REST API request. See Run tests using a workspace configuration file for the request format.

Related topics

• Use run failures only to start a new build that reruns only the flows that failed in a previous, completed build, instead of a build you stopped with fail fast.

• See Test orchestration on Maestro for all supported strategies.