Waldo sessions now support scripting! – Learn more
App Development

An iOS Dev's Complete Guide to Test Automation With XCUITest

Ifeanyi Benedict Iheagwara
Ifeanyi Benedict Iheagwara
An iOS Dev's Complete Guide to Test Automation With XCUITest
November 8, 2022
min read

Developers occasionally need to learn a new programming language to use a particular tool whenever required to run automated tests for their applications. However, this is different for an iOS developer using XCUITest.

XCUITest offers several unique functionalities not seen in other testing suites. As Apple described, XCUITest is part of Apple's testing framework that lets its iOS developers create and run UI tests on their Xcode projects. In this post, you'll learn about XCUITest and follow an iOS dev's guide to test automation using XCUITest.

XCUITest is a testing framework developed by Apple Inc. for testing Apple applications

What Is XCUITest?

XCUITest is a testing framework developed by Apple Inc. for testing Apple applications. It uses Swift programming language and is similar to the Selenium testing framework for web applications. It allows developers to write automated tests that interact with the user interface of an iOS or tvOS application.

XCUITest has been designed to work with the Xcode development environment and includes several features, thus making it a powerful tool for testing iOS and tvOS applications. For example, XCUITest can launch and terminate applications, simulate user interaction, and take screenshots.

However, it's crucial to know that XCUITest is used for user interface (UI) testing. As a result, iOS developers can use XCUITest to test UI components like buttons, labels, and text fields, as well as UI interactions like tap gestures and swipes.

Therefore, XCUITest is a helpful tool to ensure your application's user interface is operating as expected, thus guaranteeing a great end-user experience for your users.

Which Test Framework Does XCUITest Use?

XCUITest uses the XC Test framework, an iOS automation testing framework for Xcode. It supports automated UI tests written with Swift or Objective-C programming language and works just for native iOS and macOS applications. 

Let's look at several APIs used to test the framework before discussing how to use XCUITest.

Overview of XCUITest API

XCUITest API has three major classes for testing the UI of a native iOS application:

  • XCUIApplication is used for launching, monitoring, and terminating the iOS application.
  • XCUIElement is used to interact with the application. You can test using gestures like touching, dragging, and swiping with it.
  • XCUIElementQuery is used to search for elements on the screen and perform some action.

There are, however, classes testers used like

  • XCUIScreen for screenshots during test execution;
  • XCUIRemote for simulating interactions with physical remote controls; and
  • XCUIDevice for portraying physical buttons, showing device orientation, and interacting with Siri.

When writing tests, the XCUITest API can have this structure:

XCUIApplication  > XCUIElementQuery > XCUIElement > XCUIElementQuery > XCUIApplication

This demonstrates that the application is launched, the required element is searched for, and the specific element is selected. Then, the second XCUIElementQuery acts as a validation that checks whether what happened was the expected outcome. The application is closed finally.

How Do I Run an XCUITest?

Setting up the Environment

To run an XCUITest, you need to set up your environment. You can do that by following the steps below:

  1. Download Xcode.
  2. Launch Xcode after download.
  3. To create the UITesting suite, click New > Target.
  4. Then, select iOS Template > iOS UITestingBundle.
  5. Enter the UITest target name and other required fields.
  6. Click Finish.

After setting up the default environment, an example test code is generated by Xcode, as seen below.

import XCTest
class UITests: XCTestCase {
    override func setupwithError() throws I
         // Put setup code here. This method is called before the invocation of each test method in the class.
         // In UI tests it is usually best to stop immediately when a failure occurs.
        continueAfterFailure = false
         // In UI tests it's important to set the initial state - such as interface orientation - required for your tests before they run. The setUp method is a good place to do this.
     override func tearDownithError() throws {
         // Put teardown code here. This method is called after the invocation of each test method in the class
Func testExample() throws{
// Ui tests must launch application that they test.
let app = XCUIApplication()

//use recording to get started writing UI test.
// Use XCTAssert and related functions to verify your tests produce the correct results.

Func testLaunchPerformance() throws{
	If #available( macOS 10.15, iOS 13.0, tvOS 13.0, *){
// This measures how long it takes to launch your application.
measure( metrics: [XCTOSSignpostMetric.applicationLaunch]){

It contains different functions, such as the

  • setUpWithError—This is used to create the state usually needed for each test method.
  • tearDownWihError—This is used to tear down the state after every test method.
  • testExample—This is an example of a test you can write in XCTest. It's used to test if the setup runs as expected. Prefixing test methods with the word "test" is the naming convention. For instance:

func testTapLikeButtons() throws {
	// Type Test case 
  • testLaunchPerformance—It measures the amount of time it takes to launch the application.

Running XCUITest After Setting Up the Environment

To run an XCUITest after setting up the environment:

  1. Create a new scheme by selecting Product > Scheme > New Scheme.
  2. Click the test > then Edit Scheme.
  3. Select Run Debug > then Executable > Select the desired application > Close.
  4. Next, click on the recording button (the red dot beside the debug area).
  5. To run the test, go to Menu > Product > Test.
  6. Package the outcome of the test.

Now that you understand how to run the test, let's look at the sample XCUITest below.

    import XCTest

    class XCUITest: XCTestCase {
    override func setUp() {
    continueAfterFailure = false
    func checkInput() {
    let app = XCUIApplication()
    app.otherElements.containing(.image,identifier:"XCUITest Trial").element.tap()
    XCTAssert(app.staticTexts["Welcome to XCUITest"].exists)

The test case is called checkInput () in this case. The code in this test case uses the XCUITest framework to carry out the following tasks:

  • Look for an image in the UI with the identifier "XCUITest Trial" and perform a tap action on it.
  • After that, locate a button with the text "Enter" on the UI and perform another tap action on it.
  • Finally, examine whether the tap action causes the text "Welcome to XCUITest" to appear on the UI.

The test mentioned above is run when the test case is executed. Then, the XCTAssert method confirms whether the final text is visible. When it does, the automated test is successful.

Major Functionalities in XCUITest

UI Recorder

Using the UI recorder, you may capture the application's flow. Xcode makes it easy to automate the testing effort on a wide range of devices, thus simplifying the creation of user-directed tests for your app.

The purpose of the record-and-play-back tools is to make the creation of a test script fast while also giving a high level of detail of the whole UI. The UI recorder shows the application's UI layers, features, element-specific details, and more information, including the names, descriptions, and even code-specific attributes. An example is XPath locators.

It also records all manual interactions and the test script of those actions. Users can modify these test scripts and run them on multiple devices simultaneously in a single invocation to reduce the chance of the code being corrupted or lost.


XCUIElement is a way to test an app with keyboard and mouse interactions. Some commonly used XCUIElement properties are:

  • var tables—shows a query with access to all table views visible (UITableView)
  • var alerts—returns a query with access to any alerts visible in the view
  • var buttons—reverts with a query containing all visible buttons (UIButton) in the view
  • var staticTexts—returns with a query containing every text label visible (UILabel) in the view
  • var textFields—returns with a query containing all text input fields that are visible (UITextField) in the view
  • var count—evaluates the query and reverts the number of matching elements
  • var element—retrieve the element that fits in a query


Developers use assertions to validate whether the actions performed in an automation test match the desired behavior. Some examples of assertion functions are:

  • XCTAssertEqual()—validates that two expressions are of the same value
  • XCTAssertFalse()—validates that a given expression is false
  • XCTAssertNil()—validates that an expression is nil
  • XCTAssertThrowsError()—appears when an error is thrown

Others are XCTAssertNoThrow, XCTUnwrap, and XCTAssertGreaterThan.

An Accessibility Inspector is ideal for checking items that enable you to develop scripts for complex circumstances

Accessibility Inspector

An Accessibility Inspector is ideal for checking items that enable you to develop scripts for complex circumstances. This differs from a UI recorder, which works better for more straightforward cases.

You can use the Accessibility Inspector by following these steps:

  1. Open Developer Tool > Accessibility Inspector.
  2. Click the "Start Inspection" button.
  3. Then, start the object inspection.

Why Should I Use XCUITest?

XCUITest is an excellent tool for iOS developers who want to create high-quality test automation for their iOS apps.

Here are some reasons you should use XCUITest:

  • Its tests are easy to maintain and can run concurrently on multiple devices.
  • Its tests can be run parallel with other tests, such as unit tests, to speed up the testing process.
  • It provides detailed reports that can be used to identify and fix issues.
  • It doesn't require additional components to be installed.
  • It's easy to collaborate with developers because iOS developers use Swift.
  • It can improve accessibility to applications.

XCUITest vs. Appium

XCUITest is one of many existing UI test automation tools. Appium, an open-source and cost-free mobile app testing framework, is another tool utilized. However, while XCUITest is only used for iOS mobile testing, Appium can be used for Android and iOS applications.

Let's take a look at how XCUITest differs from Appium.



In this post, we've learned about XCUITest and how iOS developers can use it right away without needing to learn a new framework or language. However, it's important to remember that a testing framework is only as good as the insights it provides. Without a comprehensive reporting system and data from real devices, XCUITest is only half the solution.

Now that you know what XCUITest is, you can leverage a tool like Waldo to automate the testing process without the need to write code.

Automated E2E tests for your mobile app

Waldo provides the best-in-class runtime for all your mobile testing needs.
Get true E2E testing in minutes, not months.

Reproduce, capture, and share bugs fast!

Waldo Sessions helps mobile teams reproduce bugs, while compiling detailed bug reports in real time.