XCUITest in CI with GitHub Actions
On this page
UI tests that only run on a developer's Mac are run when someone remembers. This chapter puts the suite into a GitHub Actions workflow with two jobs: a fast simulator run on every pull request, and a real-device run on TestingBot once the simulator job is green. The same steps work in any CI system with macOS machines (Bitrise, CircleCI, Jenkins with a Mac agent, Xcode Cloud for the simulator half).
The workflow#
.github/workflows/ui-tests.yml:
name: UI tests
on:
pull_request:
push:
branches: [main]
jobs:
simulator:
runs-on: macos-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@v4
- name: Show Xcode
run: xcodebuild -version
- name: Build for testing
run: |
xcodebuild build-for-testing \
-project Tasks.xcodeproj -scheme Tasks \
-destination 'generic/platform=iOS Simulator' \
-derivedDataPath build-sim
- name: Run UI tests on a simulator
run: |
UDID=$(xcrun simctl list devices available --json | python3 -c 'import json,sys; d=json.load(sys.stdin)["devices"]; print(next(x["udid"] for r in sorted(d, reverse=True) if ".iOS-" in r for x in d[r] if x["name"].startswith("iPhone")))')
echo "Using simulator $UDID"
xcodebuild test-without-building \
-xctestrun "$(ls build-sim/Build/Products/*.xctestrun)" \
-destination "id=$UDID" \
-resultBundlePath TestResults.xcresult
- uses: actions/upload-artifact@v4
if: always()
with:
name: simulator-results
path: TestResults.xcresult
real-devices:
needs: simulator
runs-on: macos-latest
timeout-minutes: 60
steps:
- uses: actions/checkout@v4
- name: Build for real devices (unsigned)
run: |
xcodebuild build-for-testing \
-project Tasks.xcodeproj -scheme Tasks \
-destination 'generic/platform=iOS' \
-derivedDataPath build-device \
CODE_SIGNING_ALLOWED=NO
- name: Package app and test runner
run: |
cd build-device/Build/Products/Debug-iphoneos
mkdir Payload
cp -R Tasks.app Payload/
zip -qry "$GITHUB_WORKSPACE/Tasks.ipa" Payload
zip -qry --symlinks "$GITHUB_WORKSPACE/TasksUITests.zip" TasksUITests-Runner.app
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Run on TestingBot
env:
TB_KEY: ${{ secrets.TB_KEY }}
TB_SECRET: ${{ secrets.TB_SECRET }}
run: |
npx @testingbot/cli@1.5.0 xcuitest Tasks.ipa TasksUITests.zip \
--device "iPhone 16" --real-device \
--name "Tasks UI tests" \
--build "tasks-ci-${{ github.run_number }}" \
--report junit --report-output-dir reports
- uses: actions/upload-artifact@v4
if: always()
with:
name: testingbot-reports
path: reports
How this was checked: the file passes actionlint, and every run: step was executed on a Mac with Xcode 26.4.1, in order. The simulator job's two steps ran the whole suite through test-without-building (the device-picking one-liner chose an iPhone 17 Pro simulator), and the real-device job's build, packaging and CLI steps are the ones that produced the TestingBot runs in chapter 8. What could not be checked from here is GitHub's own macOS image: which Xcode and simulators it carries changes over time, which is exactly why the workflow prints the Xcode version and picks a simulator instead of naming one.
Decisions worth understanding#
Two jobs, cheap one first. The simulator job catches most failures in a few minutes. The real-device job only runs when it passed (needs: simulator), so a broken pull request does not use device minutes.
Do not hard-code a simulator name. -destination 'platform=iOS Simulator,name=iPhone 17' works on your Mac and breaks the day the CI image ships a different set of simulators. The one-liner asks simctl for available devices and takes an iPhone from the newest iOS runtime. If you need a specific OS, pin the Xcode version as well; on GitHub-hosted runners several Xcode versions are installed side by side and sudo xcode-select -s (or a setup action) switches between them.
Build once, run from the products. build-for-testing plus test-without-building (chapter 7) separates "does it compile" from "do the tests pass" in the log, and the same products can feed several test jobs if you later shard the suite.
Keep the result bundle. -resultBundlePath TestResults.xcresult writes the result bundle to a known place, and upload-artifact with if: always() keeps it when the job fails, which is the only time you need it. Download it and open it in Xcode to see each step and screenshot of the failed test.
Unsigned device builds. CODE_SIGNING_ALLOWED=NO means the CI machine needs no certificates or provisioning profiles; TestingBot re-signs the bundles for its devices (chapter 7).
Credentials from secrets. The TestingBot CLI reads TB_KEY and TB_SECRET from the environment. Add them as repository secrets (Settings > Secrets and variables > Actions); never paste them into the workflow.
A build name per CI run. --build "tasks-ci-${{ github.run_number }}" groups the devices of one workflow run under one build in the TestingBot dashboard, so a failure in run 214 is easy to find next to its siblings. --report junit saves a JUnit XML file that the artifact step keeps and that test-report actions can turn into annotations.
Pin the CLI version (@testingbot/cli@1.5.0) so a new release cannot change your pipeline without a commit.
The workflow used -destination 'platform=iOS Simulator,name=iPhone 15' and started failing one morning with "Unable to find a device matching the provided destination specifier", with no code change. What happened?
Hosted runner images change their Xcode versions and simulators over time. Pick a device from simctl list devices available, or pin both the Xcode version and the simulator, so the job does not depend on what the image happened to contain.
Running only part of the suite#
As the suite grows, not every test needs to run on every pull request. Three options, all standard xcodebuild:
-
-only-testing:/-skip-testing:on the command line, for example a smoke class on pull requests and everything on the main branch. -
Test plans (
.xctestplan, Product > Test Plan in Xcode) store which tests run with which launch arguments, environment and languages.xcodebuild test -testPlan Smokeselects one. They are the tidy way to run the same suite in several configurations, for example once in English and once in German. -
Parallel testing:
-parallel-testing-enabled YESruns test classes on several clones of the simulator at once. It only helps when tests are independent (chapter 6), and it multiplies the memory the CI machine needs.
A UI test fails in CI but you cannot reproduce it locally. What gives you the most information with the least effort?
The result bundle already contains every step, the failure and screenshots, and a TestingBot run adds a video of the device. Re-running hides the problem, prints need another cycle, and blanket timeouts slow everything without explaining anything.
Where to go next#
- The XCUITest documentation lists every cloud option: localisation, network throttling, geolocation, orientation and test reports.
- The Mobile App Testing course puts XCUITest next to Espresso, Appium and Maestro and covers device matrices for a whole mobile team.
- The Flaky Tests course goes deeper on finding and fixing tests that pass and fail without code changes.
The last chapter is a knowledge check across the whole course.