Your First XCUITest: Building a Basic iOS UI Test

Your First XCUITest is the point where iOS test automation moves from theory into a real executable workflow. Instead of validating only individual functions or business logic, you create a test that launches an iOS application, finds UI elements, performs user-like interactions, and verifies the resulting application state. Apple continues to use XCTest for UI testing, with XCUIAutomation providing the APIs that control the application interface. (Apple Developer)

For an SDET coming from Selenium, Playwright, Cypress, or Appium, the first native iOS UI test introduces several new concepts: XCTestCase, XCUIApplication, XCUIElement, element queries, accessibility identifiers, simulator destinations, and Xcode test targets.

The goal of this article is simple: build a small but realistic UI test from scratch and understand why every part of the test exists.

What is Your First XCUITest?

A basic XCUITest is an automated test written with XCTest and XCUIAutomation that launches an iOS application, identifies UI elements, performs interactions, and verifies expected behavior.

Apple describes XCUIAutomation as a framework for replicating interaction sequences and checking that an application’s user interface behaves as intended. XCTest provides the testing infrastructure, assertions, test cases, and execution workflow around those UI interactions. (Apple Developer)

A simple test follows this model:

Launch Application
       ↓
Find UI Element
       ↓
Wait for Element
       ↓
Perform Action
       ↓
Validate Result

This is the fundamental pattern behind much larger iOS automation frameworks.

Definition

Your First XCUITest is a native iOS UI automation test that uses XCTest and XCUIAutomation to launch an application, interact with its visible interface, and verify an expected result.

Key Points

• XCTestCase provides the test case structure.
• XCUIApplication represents the application under test.
• XCUIElement represents an individual UI element.
• XCUIElementQuery defines how elements are located.
• app.launch() starts the application.
• Actions such as tap() simulate user interactions.
• Assertions verify expected behavior.
• waitForExistence() helps synchronize tests with UI state.
• Accessibility identifiers provide stable element references.
• Tests normally execute through Xcode on a simulator or physical device.

Why Build a Basic XCUITest First?

A large automation framework can hide the fundamentals.

When you create Your First XCUITest, every line is visible. You can see how Xcode launches the application, how the test identifies a button, how the button is tapped, and how an assertion determines whether the test passes.

That makes a basic test more valuable than immediately creating dozens of page objects.

The first test should answer five questions:

1. How does the test start?
2. How does it identify the application?
3. How does it find an element?
4. How does it interact with that element?
5. How does it determine success or failure?

Once those answers are clear, framework design becomes much easier.

XCTest and XCUIAutomation: How They Work Together

A common beginner misunderstanding is treating XCTest and XCUIAutomation as completely separate automation frameworks.

They work together.

XCTest supplies the test infrastructure:

XCTestCase
XCTAssertTrue(...)
XCTAssertEqual(...)

XCUIAutomation supplies UI interaction:

XCUIApplication()
XCUIElement
XCUIElementQuery

Apple explicitly states that XCTest works with XCUIAutomation to interact with an application’s UI and validate user interaction flows. (Apple Developer)

The relationship can be represented as:

XCTest
   │
   ├── Test Case
   ├── Assertions
   ├── Setup / Teardown
   │
   ▼
XCUIAutomation
   │
   ├── Application
   ├── Element Queries
   ├── UI Elements
   └── User Interactions

This distinction becomes important later when comparing UI automation with unit and integration testing.

What You Need Before Creating the Test

Before writing Your First XCUITest, make sure you have:

You do not need a third-party automation server for a basic native XCUITest workflow.

---

👉 Continue reading the full article on skakarh.com →

Originally published at skakarh.com/your-first-xcuitest-basic-ios-ui-test.
Subscribe to QA Pulse by SK —
weekly signal for QA, Test Automation and AI in Software Engineering.