Run failures only for XCUITest tests

Start a new XCUITest build on App Automate that reruns only the tests that failed in a previous build of the same suite.

Rerunning an entire suite to chase down a handful of failures wastes device time on tests that already passed.

Run failures only starts a new build that re-executes just the tests that failed in an earlier, completed build of the same test suite, and reports everything else as not-run (retry-failures). This is a different strategy from automatic reruns, which retries a failing test within the same build. Run failures only instead reads the result of a previous, completed build and starts a new build that contains only its failed tests.

Enable run failures only

To enable run failures only, add testOrchestrationOptions.rerunPreviouslyFailed to your builds REST API request. Set enabled to true, and pass the build ID to pull failures from as sourceBuildId.

Use the following cURL request:

Replace YOUR_USERNAME and YOUR_ACCESS_KEY with your BrowserStack credentials, the bs:// IDs with the app and test suite IDs returned when you uploaded them, and <prior_build_id> with the ID of the completed build whose failures you want to rerun.

Keep the following in mind:

• sourceBuildId accepts the build ID of any completed build of the same test suite.
• Omitting sourceBuildId resolves to the most recently completed build of the same suite. Always pass sourceBuildId explicitly if more than one build of the suite can run at the same time, so BrowserStack doesn’t have to guess which one you mean.

How the failed set runs

BrowserStack translates the stored failed set into XCUITest’s own way of running an explicit subset of tests.

XCUITest receives the failed set as one -only-testing:<Target/Class/method> entry per failed test. Test identity is the Target/Class/method identifier, the same identifier automatic reruns use.

Tests that aren’t part of the failed set are not executed, and are reported with the status not-run (retry-failures) so the dashboard makes clear the build was a partial rerun rather than a full pass.

Edge cases to plan for

Keep the following edge cases in mind:

• No prior build, or an empty failed set: BrowserStack doesn’t run the full suite as a fallback. The build no-ops and returns a warning, so you don’t get a surprise full run when you expected a small one.
• Suite drift between builds: if a previously-failed test no longer exists in the current suite, BrowserStack drops it from the failed set and logs a note. Tests newly added since the source build are not run, because they have no prior failure to rerun.
• Test identity stability: the failed set is only as reliable as the test identifiers staying stable across builds. If your suite renames or restructures tests between builds, the mapping to the source build’s failures can degrade.

Related topics

• See Test orchestration on XCUITest for all supported strategies.