Test Plans (XCTestPlan)

WHY IT EXISTS Before Test Plans, execution settings lived in the scheme, so testing under multiple languages, sanitizers, or randomized orders meant duplicating schemes or hand-editing settings between runs. Test Plans, introduced with Xcode 11, exist to separate what you test from how you test it, making complex matrix testing repeatable and reviewable in version control.

THE MENTAL MODEL Think of a Test Plan as a recipe with shared ingredients plus named variations. There is one set of shared settings and a list of configurations, each able to override the shared settings. The scheme simply points at one or more plans, so the same scheme can run a fast smoke configuration locally and an exhaustive multi-locale, sanitizer-enabled matrix in CI.

HOW IT WORKS The file is stored as JSON with a .xctestplan extension and tracked in source control. It lists which test targets and individual tests are enabled or skipped, then defines configurations. Per-configuration options include app language and region, code coverage gathering, the address, thread, and undefined-behavior sanitizers, the main thread checker, randomized test execution order, and repetition counts for flaky-test detection. Running the plan executes every configuration in turn.

WHEN IT MATTERS It matters when you must prove correctness across locales, surface data races with the thread sanitizer, gate merges on coverage, or hunt intermittent failures by repeating tests. It also keeps CI and local runs identical because both consume the same versioned plan.

ONE CONCRETE EXAMPLE A banking app supports English, Arabic, and Japanese. One Test Plan defines three configurations, one per locale, with the Arabic configuration also catching right-to-left layout regressions. A fourth configuration enables the thread sanitizer and repeats each test five times. CI runs the full plan on every pull request, while developers locally run only the English configuration for speed, all from the same file.