xctest-mac-desktop

Overview

XCTest is the first-party test framework bundled with Xcode, used for unit, performance, and UI tests. Per Apple's Testing with Xcode - UI Testing chapter, "UI Testing in Xcode rests on two core technologies: the XCTest framework and Accessibility," layered via three classes - XCUIApplication, XCUIElement, and XCUIElementQuery (appleuit).

This skill wraps XCTest for macOS desktop apps. iOS / iPadOS use the same APIs with different launch + simulator semantics and are out of scope here.

Strategic frame: desktop-test-strategy-reference places macOS in the three-OS landscape (UIA on Windows, XCTest on macOS, AT-SPI on Linux); the locator strategy converges on accessibility identifiers across all three.

When to use

• macOS desktop app built with Xcode (AppKit, SwiftUI, Catalyst) - XCTest is the default sanctioned path per appleuit.
• Tests need to run on the same macOS runner that builds the app (xcodebuild test).
• Mixed unit + UI + performance suites - one framework covers all three (Apple's Writing Tests chapter documents the shared XCTestCase base).

Step 1 - Create a UI test target

In Xcode: File → New → Target → UI Testing Bundle. The generated test class inherits from XCTestCase and ships with a boilerplate setUp that launches the app (appleuit):

import XCTest

final class CheckoutUITests: XCTestCase {
    override func setUpWithError() throws {
        continueAfterFailure = false   // recommended by Apple - UI steps depend on prior steps
        XCUIApplication().launch()
    }

    func testCheckoutHappyPath() throws {
        // Test body - see Step 3
    }
}

Per appleuit:

"Set continueAfterFailure to NO ensures tests stop on first failure (recommended since UI test steps are dependent)."

Step 2 - Test-method naming + lifecycle

Per applewt, a test method must "begin with the prefix test", take no parameters, and return void. Lifecycle order:

1. Class setup (+ (void)setUp) - once before all tests.
2. Per test: setUp → test method → tearDown.
3. Class teardown (+ (void)tearDown) - once after all tests.

Step 3 - Author UI tests with accessibility identifiers

The portable lesson per desktop-test-strategy-reference: prefer accessibilityIdentifier over visible labels. Set the identifier in app code:

// In app code (SwiftUI)
Button("Sign In") { … }
    .accessibilityIdentifier("signInButton")

// Or in AppKit
signInButton.setAccessibilityIdentifier("signInButton")

Then in tests:

func testCheckoutHappyPath() throws {
    let app = XCUIApplication()
    app.launch()

    // Query → Interact → Assert (the canonical XCUI pattern per [appleuit])
    app.textFields["emailField"].tap()
    app.textFields["emailField"].typeText("user@example.com")

    app.secureTextFields["passwordField"].tap()
    app.secureTextFields["passwordField"].typeText("s3cret")

    app.buttons["signInButton"].tap()

    // Wait + assert
    let welcomeHeading = app.staticTexts["welcomeHeading"]
    XCTAssertTrue(welcomeHeading.waitForExistence(timeout: 5))
    XCTAssertEqual(welcomeHeading.label, "Welcome, user@example.com")
}

Per appleuit, the canonical pattern is:

"Use an XCUIElementQuery to find an XCUIElement. Synthesize an event and send it to the XCUIElement. Use an assertion to compare the state of the XCUIElement against an expected reference state."

waitForExistence(timeout:) is the documented predicate-polling primitive used in place of fixed sleeps (stable identifier in Apple's XCUIElement reference; cited inline by name).

Step 4 - Assertion macros

Per applewt, XCTAssert macros fall into five categories:

All accept an optional format string for the failure message (applewt).

Step 5 - Performance tests with measureBlock:

Per applewt, performance tests "run a code block 10 times, collecting average execution time and standard deviation":

func testAdditionPerformance() throws {
    self.measure {
        var sum = 0
        for i in 0..<100_000 { sum += i }
        XCTAssertEqual(sum, 4_999_950_000)
    }
}

Per applewt: "Performance tests report failure on first run until a baseline is set. Baselines are stored per-device- configuration." Practical implication: the first CI run on a new Mac architecture (Intel → Apple Silicon migration) fails until the baseline is committed.

Step 6 - Recording UI tests

Per appleuit, Xcode's "UI Recording" workflow generates test code from interactive use:

1. Place the cursor in a test function.
2. Click the red "record" button in the editor.
3. The app launches automatically.
4. Exercise the app with the desired UI actions.
5. Stop recording - Xcode captures actions as source code.
6. Add XCTAssert assertions to validate behaviour.

Treat recordings as a starting point - the generated locator chain tends to rely on label paths rather than accessibilityIdentifier. Refactor to identifier-based queries (per the desktop-test-strategy-reference locator table) before checking in.

Step 7 - Run

From the command line:

# Run the full test bundle
xcodebuild test \
  -project MyApp.xcodeproj \
  -scheme MyApp \
  -destination 'platform=macOS' \
  -resultBundlePath build/result.xcresult

# Run a single test class
xcodebuild test \
  -project MyApp.xcodeproj \
  -scheme MyApp \
  -destination 'platform=macOS' \
  -only-testing:MyAppUITests/CheckoutUITests

# Run a single test method
xcodebuild test \
  -project MyApp.xcodeproj \
  -scheme MyApp \
  -destination 'platform=macOS' \
  -only-testing:MyAppUITests/CheckoutUITests/testCheckoutHappyPath

-destination 'platform=macOS' targets the host Mac. -resultBundlePath writes a .xcresult bundle that contains attachments (screenshots on failure, performance metrics, logs) - the canonical artefact for post-mortem.

Step 8 - Parsing results

Query the .xcresult bundle with xcrun xcresulttool (JSON summary, attachment extraction), then convert to JUnit XML via the open-source xcresultparser for junit-xml-analysis. Commands: references/ci-and-results.md.

Step 9 - CI integration

Hosted macOS runners are interactive, so xcodebuild test UI launches need no extra display setup; self-hosted headless Macs need an attached console or VNC session (XCTest UI cannot run under launchd alone). Full workflow: references/ci-and-results.md.

Anti-patterns

Limitations

• macOS-only. Tests run only on macOS hosts; cross-OS suites pair with Windows / Linux drivers (per the desktop-test-strategy-reference matrix).
• Apple modern docs are Cloudflare-gated. The canonical developer.apple.com/documentation/xctest SPA shell returns without body content via automated fetch; this skill cites Apple's stable library/archive testing-with-xcode chapter (appleuit, applewt) for prose and treats per-API surface (XCUIApplication, XCUIElement, XCUIElementQuery, waitForExistence(timeout:)) as stable identifiers in Apple's XCUIElement reference. Document this in the PR description if the reviewer asks for a click-through link.
• Performance baselines are per-device. A baseline committed from an Intel Mac fails on Apple Silicon CI and vice versa. Run on the same architecture you gate against.
• Cross-process drag-and-drop between two apps is partially supported via XCUICoordinate interactions; complex multi-app flows often need Apple Mac2 driver via Appium for parity with Windows / Linux test sources.
• GPU-rendered content (Metal, CALayer-only views) does not publish accessibility children - same caveat as desktop-test-strategy-reference.
• Sandbox restrictions for App-Store apps under test prevent some test-time file-system writes; use XCTestObservationCenter for in-process observation rather than out-of-process file diffs.

References

• Testing with Xcode - UI Testing chapter (appleuit).
• Testing with Xcode - Writing Tests chapter (applewt).
• Apple XCTest framework reference - stable identifier "Apple XCTest framework reference" (modern docs at developer.apple.com/documentation/xctest; SPA-shell, cite by ID).
• Apple XCUIApplication / XCUIElement / XCUIElementQuery - stable identifiers in the Apple developer documentation; cite by class name.
• Strategic frame: desktop-test-strategy-reference.
• Sibling skills: winappdriver (Windows UIA), at-spi-linux (Linux AT-SPI), qt-test-framework (Qt in-process).
• Downstream: junit-xml-analysis.