Utilities for easier interaction with XCUITest methods

What's New


  • Added pressWhenReady(forDuration:) to wait for application to become idle before starting press similarly to how tapWhenReady() works.
  • Added lastMatch extension on XCUIElementQuery to access last element that matches the query.
  • Added a way to modify assertion timeout globally (XCAppTestConfig.defaultTimeout) or per call (via timeout parameter)
  • Added assertHasTitle(_:) to assert that element has correct title property.
  • Added subscript extension on XCUIElement to access elements via index.

Full Changelog: 0.7.0...0.8.0


Utilities for easier interaction with XCUITest methods.

What's included

  • XCUIElement extensions:

    • Checking existence of elements:
      • assertExists()
      • assertExists(waitForAppToIdle: true)
      • assertNotExists()
      • assertExists(false)
    • Checking interactivity of elements:
      • assertIsHittable()
      • assertIsNotHittable()
      • assertIsHittable(false)
      • assertIsEnabled()
      • assertIsDisabled()
      • assertIsEnabled(false)
      • assertIsInteractive() (exists, isHittable, isEnabled)
    • Checking properties of elements:
      • assertHasLabel("label")
      • assertContainsText("label")
      • assertHasValue("equatable value")
      • assertHasPlaceholder("placeholder")
      • assertIsEmpty() (value == placeholderValue)
      • assertHasTitle("title")
    • Checking traits of elements:
      • assertIsSelected()
      • assertIsNotSelected()
      • assertIsSelected(false)
    • Performing actions:
      • tapWhenReady()
      • waitForInteractivity()
      • slowTypeText("text")
      • tap(withNormalizedOffset: .center)
      • drag(from: .top, to: .bottom, pressDuration: 1)
      • press(forDuration: 1, withNormalizedOffset: .center)
      • pressWhenReady(forDuration: 2)
    • Accessing properties of elements:
      • stringValue
  • XCUIApplication extensions:

    • Accessing other apps:
      • XCUIApplication.safari
      • XCUIApplication.springboard
      • XCUIApplication.messages
    • Checking foreground state:
      • assertIsInForeground()
      • assertIsNotInForeground()
      • assertIsInForeground(false)
    • Performing actions:
      • moveToBackground()
  • XCUIElementQuery extensions:

    • Checking number of elements:
      • assertHasCount(2)
      • assertNotExists()
      • assertHasCount(2...5), assertHasCount(..<3)
    • Accessing elements:
      • lastMatch
      • self[2]
  • CGVector extensions:

    • Normalized offsets:
      • CGVector.topLeft, CGVector.top, CGVector.topRight
      • CGVector.left, CGVector.center, CGVector.right
      • CGVector.bottomLeft, CGVector.bottom, CGVector.bottomRight
      • offset(x: 0.2, y: 0.5)

All of the above assertion functions have optional message as last parameter that can be used to configure what is displayed if assertion fails. For example: element.assertExists("My element should be visible"). Additionally you can configure assertion timeout globally by modifying XCAppTestTimeout.default or per call via timeout parameter. For example: XCAppTestTimeout.default = 3, element.assertExists(timeout: 3). For details see documentation.


Here is a short example from one of my apps that makes use of this library. In the test I am checking that it is possible to navigate to "Premium features" screen, verify that most important data is visible and check that it is possible to leave that screen.

Note that some of the buttons are identified by enum case instead of raw string. You can see type safe identifiers tip below to see how this is implemented.

func testOpenClosePremiumScreen() throws {
    try launch(configuration: .init(premiumUnlocked: false))

    app.buttons["Unlock Premium"].tapWhenReady()
    app.buttons[.unlockFeaturesButton].assertIsEnabled().assertContainsText("Lifetime access")
    app.buttons["Restore Purchase"].assertIsEnabled()

    app.staticTexts["Pipilo Premium"].assertNotExists()


Swift Package Manager

  1. Add the following to the dependencies array in your Package.swift file:
.package(url: "https://github.com/Tunous/XCAppTest.git", .upToNextMajor(from: "0.4.0")),
  1. Add XCAppTest as a dependency for your tests target:
.target(name: "MyAppTests", dependencies: ["XCAppTest"]),
  1. Add import XCAppTest in your tests source code.


Add https://github.com/Tunous/XCAppTest.git, to the list of Swift packages for your project in Xcode and include it as a dependency on your tests target.


  • Swift Tools 5.7.0
View More Packages from this Author


  • None
Last updated: Sat Nov 25 2023 21:26:40 GMT-1000 (Hawaii-Aleutian Standard Time)