Class

XCUIElement

A UI element in an application.

Overview

On macOS, XCUIElement provides keyboard- and mouse-like interactions such as typing, hovering, clicking, and scrolling. On iOS, XCUIElement provides gestural interactions such as tapping, pressing, swiping, pinching, and rotating.

Topics

Querying Element State

func waitForExistence(timeout: TimeInterval)

Waits the specified amount of time for the element's exists property to become true.

var exists: Bool

Determines if the element exists.

var isHittable: Bool

Determines if a hit point can be computed for the element.

var debugDescription: String

Provides debugging information about the element.

Querying Descendant Elements

func children(matching: XCUIElement.ElementType)

Returns a query for all direct children of the element matching the specified type.

func descendants(matching: XCUIElement.ElementType)

Returns a query for all descendants of the element matching the specified type.

Typing Text

func typeText(String)

Types a string into the element.

Using Key Modifiers

Available on macOS only.

func typeKey(String, modifierFlags: XCUIElement.KeyModifierFlags)

Types a single key with the specified modifier flags.

struct XCUIKeyboardKey

Constants for use with typeKey(_:modifierFlags:) to represent keys that have no textual equivalent.

struct XCUIElement.KeyModifierFlags

Flags for keyboard modifiers such as shift, control, option, and command.

Moving the Cursor

Available on macOS only.

func hover()

Moves the cursor over the element.

Clicking

Available on macOS only.

func click()

Sends a click event to a hittable point computed for the element.

func click(forDuration: TimeInterval, thenDragTo: XCUIElement)

Clicks and holds for a specified duration (generally long enough to start a drag operation) then drags to the other element.

func doubleClick()

Sends a double click event to a hittable point computed for the element.

func rightClick()

Sends a right click event to a hittable point computed for the element.

Scrolling

Available on macOS only.

func scroll(byDeltaX: CGFloat, deltaY: CGFloat)

Scrolls the view by the specified number of x and y pixels.

Tapping and Pressing

Available on iOS, and on macOS for Touch Bar interactions.

func tap()

Sends a tap event to a hittable point computed for the element.

func doubleTap()

Sends a double tap event to a hittable point computed for the element.

func press(forDuration: TimeInterval)

Sends a long press gesture to a hittable point computed for the element, holding for the specified duration.

func press(forDuration: TimeInterval, thenDragTo: XCUIElement)

Initiates a press-and-hold gesture, then drags to another element.

Multiple Taps

Available on iOS only.

func twoFingerTap()

Sends a two finger tap event to a hittable point computed for the element.

func tap(withNumberOfTaps: Int, numberOfTouches: Int)

Sends one or more taps with one or more touch points.

Performing Gestures

Available on iOS only.

func swipeLeft()

Sends a swipe-left gesture.

func swipeRight()

Sends a swipe-right gesture.

func swipeUp()

Sends a swipe-up gesture.

func swipeDown()

Sends a swipe-down gesture.

func pinch(withScale: CGFloat, velocity: CGFloat)

Sends a pinching gesture with two touches.

func rotate(CGFloat, withVelocity: CGFloat)

Sends a rotation gesture with two touches.

Interacting with Sliders

These methods provide functionality for automating interactions with UISlider and NSSlider.

var normalizedSliderPosition: CGFloat

Returns the position of the slider's indicator as a normalized value where 0 corresponds to the minimum value of the slider and 1 corresponds to its maximum value.

func adjust(toNormalizedSliderPosition: CGFloat)

Manipulates the UI to change the displayed value of the slider to a new value, based on a normalized position.

Interacting with Pickers

This method provides functionality for automating the picker wheels of UIPickerView and UIDatePicker controls.

func adjust(toPickerWheelValue: String)

Changes the displayed value for the picker wheel.

Calculating Coordinates

func coordinate(withNormalizedOffset: CGVector)

Creates and returns a new coordinate with a normalized offset.

Supporting Types

enum XCUIElement.ElementType

The types of UI element that can be located.

enum XCUIElement.SizeClass

Describes the available user interface size classes.

See Also

UI Elements

protocol XCUIElementAttributes

Attributes exposed by UI elements.

class XCUICoordinate

A location on screen relative to some UI element.