Stop XCUITest builds automatically with fail fast

Automatically stop an XCUITest build on App Automate after a specified number of tests fail, so you 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.

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 tests that stops the build.

Use the following cURL request:

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 test as failed only after all its retries are exhausted.

XCUITest resolves test retries inline during the active test execution. Fail fast evaluates failures immediately upon final invocation, eliminating any pending state or secondary retry queue.

What happens when a build stops

Reaching the fail-fast threshold triggers a coordinated shutdown across running tests and the dashboard. The following sections describe each part of that process.

Build termination behavior

Reaching a fail-fast threshold halts suite execution gracefully at the next test boundary. Active test invocations complete their execution cycle, and the system never terminates a running test mid-flight.

Queue and state handling

When a build halts, the runner cleans up active execution slots and updates pending job statuses across the pipeline:

• Active invocations: Run to completion before the suite halts.

• Unexecuted tests: Marked as skipped rather than failed to preserve accurate failure ratios.

Dashboard reporting

The execution dashboard flags the run as automatically terminated due to failure threshold limits. This distinguishes automated fail-fast cancellations from manual developer interventions in your build telemetry and audit logs.

Related topics

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

• See Test orchestration on XCUITest for all supported strategies.