Class

XCUIElement

A UI element in an application.

Declaration

@interface XCUIElement : NSObject

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

- waitForExistenceWithTimeout:

Waits the specified amount of time for the element’s exists property to become YES.

exists

Determines if the element exists.

hittable

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

debugDescription

Provides debugging information about the element.

Querying Descendant Elements

- childrenMatchingType:

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

- descendantsMatchingType:

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

Typing Text

- typeText:

Types a string into the element.

Using Key Modifiers

Available on macOS only.

- typeKey:modifierFlags:

Types a single key with the specified modifier flags.

XCUIKeyboardKey

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

+ performWithKeyModifiers:block:

Executes block with the given modifier keys held down.

XCUIKeyModifierFlags

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

Moving the Cursor

Available on macOS only.

- hover

Moves the cursor over the element.

Clicking

Available on macOS only.

- click

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

- clickForDuration:thenDragToElement:

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

- doubleClick

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

- rightClick

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

Scrolling

Available on macOS only.

- scrollByDeltaX:deltaY:

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.

- tap

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

- doubleTap

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

- pressForDuration:

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

- pressForDuration:thenDragToElement:

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

Multiple Taps

Available on iOS only.

- twoFingerTap

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

- tapWithNumberOfTaps:numberOfTouches:

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

Performing Gestures

Available on iOS only.

- swipeLeft

Sends a swipe-left gesture.

- swipeRight

Sends a swipe-right gesture.

- swipeUp

Sends a swipe-up gesture.

- swipeDown

Sends a swipe-down gesture.

- pinchWithScale:velocity:

Sends a pinching gesture with two touches.

- rotate:withVelocity:

Sends a rotation gesture with two touches.

Interacting with Sliders

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

normalizedSliderPosition

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.

- adjustToNormalizedSliderPosition:

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.

- adjustToPickerWheelValue:

Changes the displayed value for the picker wheel.

Calculating Coordinates

- coordinateWithNormalizedOffset:

Creates and returns a new coordinate with a normalized offset.

Relationships

Inherits From

See Also

UI Elements

XCUIElementAttributes

Attributes exposed by UI elements.

XCUICoordinate

A location on screen relative to some UI element.