Add a UI Test Target and Run Your First Test
UI tests live in their own target, next to the app target and any unit test target. This chapter adds one, writes a first test against the Tasks sign-in screen and runs it from Xcode and from the command line.
Add the target#
In Xcode, choose File > New > Target..., pick UI Testing Bundle under iOS, and set Target to be Tested to your app (here Tasks). Xcode names it TasksUITests, creates a folder with two template files and adds the target to the app's scheme under Test. That last part matters: Cmd+U and xcodebuild test run whatever the scheme's Test action lists, so a target that is not in it never runs.
The course's sample project was generated with XcodeGen rather than by clicking, which makes the structure easy to read. The UI test part of its project.yml is:
TasksUITests:
type: bundle.ui-testing
platform: iOS
sources: [TasksUITests]
dependencies:
- target: Tasks
settings:
base:
PRODUCT_BUNDLE_IDENTIFIER: com.example.TasksUITests
GENERATE_INFOPLIST_FILE: YES
TEST_TARGET_NAME: Tasks
schemes:
Tasks:
build:
targets:
Tasks: all
TasksUITests: [test]
test:
targets: [TasksUITests]
TEST_TARGET_NAME is the setting behind "Target to be Tested": it tells the runner which app to install and launch. You do not need XcodeGen; it is just a readable way to show what the Xcode dialog sets up.
The first test#
Delete the template's testExample and testLaunchPerformance and create LaunchTests.swift:
import XCTest
final class LaunchTests: XCTestCase {
override func setUpWithError() throws {
continueAfterFailure = false
}
func testLoginScreenAppears() throws {
let app = XCUIApplication()
app.launchArguments = ["-resetState"]
app.launch()
XCTAssertTrue(app.staticTexts["Sign in"].exists)
XCTAssertTrue(app.textFields["login.email"].exists)
XCTAssertFalse(app.buttons["login.submit"].isEnabled)
}
}
Line by line:
-
XCTestCaseis the same base class unit tests use. Every method whose name starts withtestand takes no arguments is a test. -
continueAfterFailure = falsestops a test at its first failed assertion. In a UI test that is almost always what you want: once the screen is not what you expected, every later step fails for the same reason and buries the first, useful message. -
XCUIApplication()is a proxy for the app under test (the "Target to be Tested").launch()installs nothing; Xcode already installed both apps. It terminates any running copy, starts a fresh one and waits until it is idle. -
launchArgumentsare passed to the app's process. The Tasks app clears its stored tasks when it sees-resetState; chapter 6 is about this technique. -
app.staticTexts["Sign in"]is a query: all static texts in the app, filtered to the one whose identifier or label is "Sign in"..existsresolves it against the current screen. Chapter 2 explains queries properly. - The last line checks a real requirement: the Sign in button must stay disabled until both fields are filled in.
Run it#
In Xcode, click the diamond next to the test method or the class, or press Cmd+U to run every test in the scheme. Xcode boots the simulator chosen in the toolbar, builds the app and the runner, and you can watch the app being driven.
From the command line, xcodebuild test does the same. Pick the simulator by name and OS version:
xcodebuild test \
-project Tasks.xcodeproj -scheme Tasks \
-destination 'platform=iOS Simulator,name=iPhone 17,OS=26.4.1' \
-only-testing:TasksUITests/LaunchTests
Test Case '-[TasksUITests.LaunchTests testLoginScreenAppears]' started.
Test Case '-[TasksUITests.LaunchTests testLoginScreenAppears]' passed (3.418 seconds).
** TEST SUCCEEDED **
-only-testing: takes Target, Target/Class or Target/Class/testMethod and can be repeated; -skip-testing: is its opposite. Use it while you work on one test, because launching the app per test makes UI suites far slower than unit tests.
If xcodebuild answers "Unable to find a device matching the provided destination specifier", the OS you passed does not match an installed runtime exactly. xcrun simctl list devices available shows what exists; you can also pass id=<UDID> from that list instead of a name.
You added a UI test file to the project, but Cmd+U reports that 0 tests ran. The file compiles. What is the most likely cause?
XCTest only runs methods named test... in targets the scheme tests. Visibility does not matter, and Xcode boots the simulator itself. continueAfterFailure only changes what happens after an assertion fails.
Reading a failure#
Change the last assertion to XCTAssertTrue(app.buttons["login.submit"].isEnabled) and run again. The test fails on that line, and the report navigator (Cmd+9) shows the failure with every step the runner took: "Tap", "Find the ... Button", "Wait for com.example.Tasks to idle". All of it, with screenshots, is stored in the result bundle (.xcresult), which you can open later in Xcode or archive from CI.
Those "Wait for ... to idle" lines are worth noticing now. Before every query and action, XCUITest waits until the app's main thread has finished its current work and animations have settled. That is why the first test needs no waits at all. Chapter 4 covers the cases where idle is not enough.
About the record button#
Xcode can record a UI test: put the cursor in a test method, press the red record button below the editor and use the app. It writes code for each tap and keystroke. It is a quick way to discover how XCUITest describes an element, but the generated code tends to use labels and positions rather than identifiers and contains no assertions. Treat it as a discovery tool, then rewrite the result the way the next chapters show.
Next: how queries find elements, and how to make them find the right one every time.