---
title: Add a UI Test Target and Run Your First Test | TestingBot
description: 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…
source_url:
  html: https://testingbot.com/resources/courses/xcuitest/add-a-ui-test-target
  md: https://testingbot.com/resources/courses/xcuitest/add-a-ui-test-target.md
---

Course

[XCUITest Tutorial: iOS UI Testing in Swift](https://testingbot.com/resources/courses/xcuitest)

Chapter 2 of 11

1. [1 XCUITest Tutorial: iOS UI Test Automation in Swift](https://testingbot.com/resources/courses/xcuitest)
2. [2 Add a UI Test Target and Run Your First Test](https://testingbot.com/resources/courses/xcuitest/add-a-ui-test-target)
3. [3 Element Queries and Accessibility Identifiers](https://testingbot.com/resources/courses/xcuitest/queries-and-accessibility-identifiers)
4. [4 Interactions and Assertions](https://testingbot.com/resources/courses/xcuitest/interactions-and-assertions)
5. [5 Waiting Without sleep(): waitForExistence and Predicates](https://testingbot.com/resources/courses/xcuitest/waiting-without-sleep)
6. [6 Screen Objects in Swift](https://testingbot.com/resources/courses/xcuitest/screen-objects)
7. [7 Launch Arguments and Environment: Control App State](https://testingbot.com/resources/courses/xcuitest/launch-arguments-and-environment)
8. [8 Build for Testing: The App and the Test Runner](https://testingbot.com/resources/courses/xcuitest/build-for-testing)
9. [9 Run XCUITest on Real iPhones with TestingBot](https://testingbot.com/resources/courses/xcuitest/run-on-testingbot)
10. [10 XCUITest in CI with GitHub Actions](https://testingbot.com/resources/courses/xcuitest/ci-github-actions)
11. [11 XCUITest Knowledge Check](https://testingbot.com/resources/courses/xcuitest/knowledge-check)

[Exit course](https://testingbot.com/resources/courses)

 Chapter 2 of 11 Intermediate 5 min read 1 quick check Updated Nov 2026 

# Add a UI Test Target and Run Your First Test
On this page
1. [Add the target](https://testingbot.com#add-the-target)
2. [The first test](https://testingbot.com#the-first-test)
3. [Run it](https://testingbot.com#run-it)
4. [Reading a failure](https://testingbot.com#reading-a-failure)
5. [About the record button](https://testingbot.com#about-the-record-button)

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[#](https://testingbot.com#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](https://github.com/yonaskolb/XcodeGen) rather than by clicking, which makes the structure easy to read. The UI test part of its `project.yml` is:

```yaml
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[#](https://testingbot.com#the-first-test)

Delete the template's `testExample` and `testLaunchPerformance` and create `LaunchTests.swift`:

```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:

- **`XCTestCase`** is the same base class unit tests use. Every method whose name starts with `test` and takes no arguments is a test.
- **`continueAfterFailure = false`** stops 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.
- **`launchArguments`** are 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". `.exists` resolves 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[#](https://testingbot.com#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:

```bash
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?

 The test class is not marked `public` The simulator is not booted yet The file belongs to a target that is not in the scheme's Test action, or the methods do not start with `test` `continueAfterFailure` is set to `false`

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[#](https://testingbot.com#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[#](https://testingbot.com#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.

[Previous · Chapter 1 XCUITest Tutorial: iOS UI Test Automation in Swift](https://testingbot.com/resources/courses/xcuitest) [Next · Chapter 3 Element Queries and Accessibility Identifiers](https://testingbot.com/resources/courses/xcuitest/queries-and-accessibility-identifiers)

On this page

1. [Add the target](https://testingbot.com#add-the-target)
2. [The first test](https://testingbot.com#the-first-test)
3. [Run it](https://testingbot.com#run-it)
4. [Reading a failure](https://testingbot.com#reading-a-failure)
5. [About the record button](https://testingbot.com#about-the-record-button)

Certification

Earn the free, resume-worthy TestingBot XCUITest Certification for this course.

[How it works](https://testingbot.com/resources/courses/xcuitest/certification)
