XCUITest Tutorial: iOS UI Test Automation in Swift
Learn XCUITest from a first UI test target to a suite on real iPhones: element queries, waiting without sleeps, screen objects, launch arguments, build-for-testing and CI. Free, hands-on, Swift.
What you will learn
- XCUITest Tutorial: iOS UI Test Automation in Swift
- Add a UI Test Target and Run Your First Test
- Element Queries and Accessibility Identifiers
- Interactions and Assertions
- Waiting Without sleep(): waitForExistence and Predicates
- Screen Objects in Swift
- Launch Arguments and Environment: Control App State
- Build for Testing: The App and the Test Runner
- Run XCUITest on Real iPhones with TestingBot
- XCUITest in CI with GitHub Actions
- XCUITest Knowledge Check
On this page
Last reviewed November 2026 against Xcode 26.4.1 (iOS 26.4 simulator) and the TestingBot CLI (@testingbot/cli) 1.5.0.
XCUITest is Apple's UI testing framework for iOS, iPadOS, macOS and tvOS apps. It ships with Xcode as part of XCTest, the same framework that runs your unit tests, so there is nothing to install: you add a UI test target to your project, write tests in Swift, and run them with Cmd+U or xcodebuild test.
This course takes you from an empty UI test target to a suite that runs on real iPhones in the cloud and in CI. Here is the kind of test you will write by chapter 5:
func testSignInAndAddTwoTasks() throws {
let list = LoginScreen(app: app)
.signIn(email: "anna@example.com", password: "secret")
list.add("Buy milk").add("Call Anna").toggle("Buy milk")
XCTAssertEqual(list.rows.count, 2)
XCTAssertEqual(list.openCount, "1 open")
}
It signs in, adds two tasks, ticks one off and checks the counter. Every test in this course ran on an iPhone 17 simulator with iOS 26.4, and the finished suite ran on real iPhones on TestingBot (chapter 8 has the session IDs).
How XCUITest sees your app#
A UI test does not run inside your app. Xcode builds a second app, the test runner (TasksUITests-Runner.app in this course), installs both on the simulator or device, and the runner drives your app from the outside through the accessibility layer. Your test code talks to an XCUIApplication proxy: it can find elements, tap, type and swipe, and read what accessibility exposes (labels, values, identifiers, frames). It cannot call your app's functions or read its variables.
That is the main design decision behind everything in this course:
- You find elements the way VoiceOver does, by accessibility identifier, label or type. Chapter 2 is about making those stable.
- You set app state through the front door: launch arguments and environment variables the app reads at start-up (chapter 6), not by poking at singletons.
- XCUITest waits for the app to be idle before each action, which removes a lot of timing trouble, but not all of it. Network calls and system sheets still need explicit waits (chapter 4).
Unit tests (@testable import, calling code directly) live in a separate unit test target. This course is only about the UI test target.
XCUITest, Appium, or something else?#
There is no single right tool. The honest trade-offs:
| XCUITest | Appium (XCUITest driver) | Maestro | |
|---|---|---|---|
| Language | Swift (or Objective-C) | Any WebDriver client: Java, JavaScript, Python, ... | YAML, with JavaScript for logic |
| Platforms | Apple platforms only | iOS and Android, separate drivers | iOS and Android |
| Lives in | The app's Xcode project | A separate test project | A folder of flows |
| Speed and stability | Fast; runs next to the app with Apple's own idle detection | Extra hop through a WebDriver server on the device | Its own waiting and retries |
| Who usually writes it | iOS developers | QA engineers, cross-platform teams | QA engineers and developers |
Choose XCUITest when the people who build the iOS app also own its UI tests, when the tests should run on every pull request next to the unit tests, and when you want the fastest feedback Apple's tooling can give. Its limits are just as clear: it covers Apple platforms only, it needs a Mac and Xcode, and every change means a rebuild of the test bundle.
Appium's iOS driver is itself built on XCUITest (it drives the device through WebDriverAgent, an XCUITest-based server), so the two are not rivals so much as layers. Appium adds one API for iOS and Android and lets you write tests in any language. If that matters more than speed, the Appium and WebdriverIO course is the better start. For YAML flows that run on both platforms, see the Maestro course. The Appium vs XCUITest comparison goes deeper on the choice, and the Mobile App Testing course covers the wider picture: simulators versus real devices, frameworks, device matrices.
A UI test needs the app's shopping basket to contain three items before it starts. Which approach fits how XCUITest works?
UI tests run in a separate runner process and can only reach the app through accessibility and launch configuration. @testable import works in unit tests, where the code runs in the same process, but in a UI test the singleton you change is a copy in the runner, not the one in the app.
What you will build#
The course uses a small SwiftUI app called Tasks: a sign-in screen (the password is secret, and the "server" answers after two seconds) and a list where you add, tick off and delete tasks. It is under 200 lines of Swift; the chapters show the parts that matter for testing. You can follow along with the course's code or apply each chapter to your own app.
- Add a UI test target and run your first test
- Element queries and accessibility identifiers
- Interactions and assertions
- Waiting without
sleep() - Screen objects in Swift
- Launch arguments and environment variables
- Build for testing: the two bundles a device needs
- Run the suite on real iPhones on TestingBot
- CI with GitHub Actions
- Knowledge check
Prerequisites#
- A Mac with Xcode installed (
xcodebuild -versionshould print a version) and at least one iOS simulator (xcrun simctl list devices available). - Basic Swift: structs, closures, optionals. You do not need to know SwiftUI to follow the tests.
- For chapters 8 and 9: Node.js (for the TestingBot CLI) and a TestingBot account with access to real iOS devices.
The TestingBot XCUITest documentation is the reference for every cloud option; this course is the how-to that leads up to it.