skip to content

With xcodebuild, how do you archive an iOS app, export it with -exportArchive, and run one test plan on a Simulator?

level: middleimportance: should knowfreq 55%

answer

  1. archive needs a scheme
  2. generic/platform=iOS as the destination
  3. -exportOptionsPlist and its method key
  4. -testPlan takes the plan's name
  5. -only-test-configuration, -enableCodeCoverage, result bundle

basics

~20 s

Run xcodebuild archive with a scheme, a generic iOS destination and -archivePath; export it with -exportArchive, -exportPath and an -exportOptionsPlist whose method says how; run tests with xcodebuild test, a Simulator destination and -testPlan naming the scheme's plan.

solid answer

~30 s

`xcodebuild archive -scheme MealKit -configuration Release -destination 'generic/platform=iOS' -archivePath build/MealKit.xcarchive` builds an `.xcarchive`; the `archive` action requires a scheme. `xcodebuild -exportArchive -archivePath ... -exportPath ... -exportOptionsPlist ExportOptions.plist` distributes it: the plist's `method` is one of `app-store-connect`, `release-testing`, `enterprise` or `debugging` (the default), `destination` chooses export or upload, and `signingStyle`, `teamID` and, for manual signing, `provisioningProfiles` control re-signing. For tests, `xcodebuild test -scheme ... -destination 'platform=iOS Simulator,name=iPhone 17' -testPlan UnitTests` runs the named `.xctestplan` once per configuration; `-showTestPlans` lists the plans, `-only-test-configuration` narrows them, `-enableCodeCoverage YES` collects coverage and `-resultBundlePath` keeps the results.

code

bash · 14 lines
bash
# Archive the Release configuration for any iOS device
xcodebuild archive -project MealKit.xcodeproj -scheme MealKit \
  -configuration Release -destination 'generic/platform=iOS' \
  -archivePath build/MealKit.xcarchive

# Export the archive using the options in ExportOptions.plist
xcodebuild -exportArchive -archivePath build/MealKit.xcarchive \
  -exportPath build/export -exportOptionsPlist ExportOptions.plist

# Run one test plan on a Simulator with coverage and a result bundle
xcodebuild test -project MealKit.xcodeproj -scheme MealKit \
  -destination 'platform=iOS Simulator,name=iPhone 17' \
  -testPlan UnitTests -enableCodeCoverage YES \
  -resultBundlePath build/UnitTests.xcresult

go deeper

for a junior

Know that xcodebuild drives the same build, test and archive actions as Xcode's Product menu, and that a scheme names what gets built.

for a middle

Write the archive, export and test commands from memory, including the generic iOS destination, the export options plist and -testPlan.

for a senior

Split build-for-testing from test-without-building, narrow test configurations, keep result bundles and coverage, and diagnose a wrong export method.

for a principal

Decide which test plans and configurations gate a merge versus a release, and what xcodebuild flags every pipeline must pass explicitly.

## Why the command line matters Everything the Product menu does, a CI runner does through `xcodebuild`. The tool works on a project or workspace, a **scheme**, an optional **configuration** and one or more **destinations**, and performs **actions**: `build`, `build-for-testing`, `analyze`, `archive`, `test`, `test-without-building`, `docbuild`, `installsrc`, `install` and `clean`. `archive`, `analyze`, `build-for-testing` and `test` all require a scheme. Wiring these commands into a pipeline, or wrapping them in a fastlane lane, is covered with those tools; here the subject is the commands themselves. ## Archiving An **archive** (`.xcarchive`) is the built app together with its debug symbols, the same thing Xcode's Organizer lists after Product > Archive. - `-destination 'generic/platform=iOS'` builds for any iOS device rather than one Simulator; `generic/platform=iOS Simulator` would build a Simulator archive, which cannot be distributed. - `-configuration Release` makes the configuration explicit instead of trusting what the scheme says. - `-archivePath` says where the archive goes. - `-allowProvisioningUpdates` lets the tool create or download signing assets when the machine has an account or an App Store Connect key. ## Exporting `-exportArchive` takes `-archivePath`, `-exportPath` and `-exportOptionsPlist`. `xcodebuild -help` prints every key the plist accepts. The ones that matter most: | Key | What it decides | |---|---| | `method` | `app-store-connect`, `release-testing`, `enterprise`, `debugging` (default) and others, depending on the archive | | `destination` | `export` writes files locally, `upload` sends to Apple | | `signingStyle` | `automatic` or `manual` re-signing; defaults to how the archive was signed | | `teamID` | the team used for signing | | `provisioningProfiles` | manual signing only: a profile per executable, keyed by bundle identifier | | `manageAppVersionAndBuildNumber` | whether Xcode manages the build number on upload; defaults to YES | The older method names `app-store`, `ad-hoc` and `development` are listed by the help as deprecated in favour of `app-store-connect`, `release-testing` and `debugging`. What happens to an uploaded build in TestFlight is covered with TestFlight. ## Testing with a test plan A **test plan** (`.xctestplan`) is a document listing which tests run and under which **configurations**: environment variables, sanitizers, language and region. A scheme can hold several plans and marks one as its default; Xcode runs a plan once per configuration in it. 1. `xcodebuild -scheme MealKit -showTestPlans` lists the plans of a scheme. 2. `xcodebuild test -scheme MealKit -destination 'platform=iOS Simulator,name=iPhone 17' -testPlan UnitTests` runs one plan; pass the plan's name without the `.xctestplan` extension. 3. `-only-test-configuration NAME` or `-skip-test-configuration NAME` narrows which of the plan's configurations run. 4. `-only-testing` and `-skip-testing` narrow targets, classes or methods. 5. `-enableCodeCoverage YES` turns coverage on, and `-resultBundlePath` writes an `.xcresult` bundle with results and coverage. For split CI jobs, `build-for-testing` builds the app and tests once and writes an `.xctestrun` file; `test-without-building -xctestrun ...` then runs those compiled bundles on one or more destinations without the source. Simulators themselves are managed with `xcrun simctl`, whose subcommands include `list`, `boot`, `erase`, `install`, `launch` and `privacy`. ## Reading what a test run left behind A test run from the command line produces an Xcode test results bundle (`.xcresult`), holding the session results, code coverage when it was enabled, and logs. `-resultBundlePath` puts it at a path the job chooses, so it can be kept as an artifact. - Open the bundle in Xcode to read failures, attachments and screenshots exactly as a local run shows them. - Coverage appears only if it was collected, either through the scheme's Code Coverage option or through `-enableCodeCoverage YES`. - A single failing test can be rerun with `-only-testing Target/Type/testName`, the identifier form Apple's testing guide uses. ## Simulators from the command line `xcrun simctl` controls Simulator devices without the Simulator app: `list` shows available devices and runtimes, `create` and `delete` manage them, `boot` and `shutdown` start and stop one, `erase` resets its contents and settings, `install` and `launch` put an app on it, and `privacy` grants, revokes or resets permissions so a test run starts from a known state. Where a subcommand takes a device, `booted` picks a booted one. ## Common mistakes - Archiving with a Simulator destination, then wondering why export has nothing to sign for devices. - Expecting the scheme's default plan to be the one CI meant; name `-testPlan` explicitly. - Running a test on a destination name that does not exist on the runner; `-showdestinations` lists what the scheme can use.

  • How do you build tests once and run them on several destinations later?
    Run `xcodebuild build-for-testing` with the scheme and a destination; it builds the app and test bundles and writes an `.xctestrun` file into the build products. Then `xcodebuild test-without-building -xctestrun path.xctestrun` with one or more `-destination` arguments runs the compiled bundles without needing the source.
  • A test plan has an English and a German configuration; how do you run only German in CI?
    Pass the configuration's name: `xcodebuild test -scheme MealKit -testPlan UnitTests -only-test-configuration German`. Without it, Xcode runs the plan once for each configuration it contains; `-skip-test-configuration` does the inverse.

  • xcodebuild archive works without a scheme
  • A Simulator archive can be exported for the App Store
  • -testPlan takes the plan's file path with extension
  • The default export method is app-store-connect
  • -exportArchive needs the project source to export