<!--
{
  "availability" : [
    "Xcode: 16.3.0 -",
    "iOS: -",
    "iPadOS: -",
    "macCatalyst: -",
    "macOS: -",
    "tvOS: -",
    "visionOS: -",
    "watchOS: -"
  ],
  "documentType" : "symbol",
  "framework" : "XCUIAutomation",
  "identifier" : "/documentation/XCUIAutomation/XCUIElement",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "XCUIAutomation"
    ],
    "preciseIdentifier" : "c:objc(cs)XCUIElement"
  },
  "title" : "XCUIElement"
}
-->

# XCUIElement

A UI element in an application.

```
@MainActor class XCUIElement
```

## Overview

In macOS and iPadOS 15 and later, [`XCUIElement`](/documentation/XCUIAutomation/XCUIElement) provides a way to test your app with keyboard and mouse interactions, such as typing, clicking, scrolling, and moving and pausing the pointer. In iOS, [`XCUIElement`](/documentation/XCUIAutomation/XCUIElement) provides a way to test your app with gestures, such as tapping, swiping, pinching, and rotating.

> Note:
> ``doc://com.apple.xcuiautomation/documentation/XCUIAutomation/XCUIElement`` adopts the ``doc://com.apple.xcuiautomation/documentation/XCUIAutomation/XCUIElementAttributes`` protocol, which provides additional properties for querying the current state of a UI element’s attributes.

## Topics

### Querying element state

[`-  waitForExistenceWithTimeout:`](/documentation/XCUIAutomation/XCUIElement/waitForExistence(timeout:))

Waits the specified amount of time for an element to exist.

[`-  waitForNonExistenceWithTimeout:`](/documentation/XCUIAutomation/XCUIElement/waitForNonExistence(timeout:))

Waits the specified amount of time for an element to no longer exist.

[`wait(for:toEqual:timeout:)`](/documentation/XCUIAutomation/XCUIElement/wait(for:toEqual:timeout:))

Waits a specified amount of time for a property value to equal a specified value.

[`exists`](/documentation/XCUIAutomation/XCUIElement/exists)

Determines if the element exists.

[`hittable`](/documentation/XCUIAutomation/XCUIElement/isHittable)

Determines if the system can compute a hit point for the element.

[`debugDescription`](/documentation/XCUIAutomation/XCUIElement/debugDescription)

Provides debugging information about the element.

### Querying descendant elements

[`-  childrenMatchingType:`](/documentation/XCUIAutomation/XCUIElement/children(matching:))

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

[`-  descendantsMatchingType:`](/documentation/XCUIAutomation/XCUIElement/descendants(matching:))

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

### Typing text

[`-  typeText:`](/documentation/XCUIAutomation/XCUIElement/typeText(_:))

Types a string into the element.

### Combining keystrokes

[`typeKey(_:modifierFlags:)`](/documentation/XCUIAutomation/XCUIElement/typeKey(_:modifierFlags:)-6gaoi)

Types a single key from the XCUIKeyboardKey enumeration with the specified modifier flags.

[`-  typeKey:modifierFlags:`](/documentation/XCUIAutomation/XCUIElement/typeKey(_:modifierFlags:)-9ubn)

Types a single key that a string represents with the flags you specify.

[`XCUIKeyboardKey`](/documentation/XCUIAutomation/XCUIKeyboardKey)

Constants to represent keys that have no typewritten equivalent.

[`+  performWithKeyModifiers:block:`](/documentation/XCUIAutomation/XCUIElement/perform(withKeyModifiers:block:))

Executes a block of code while holding a combination keystroke.

[`KeyModifierFlags`](/documentation/XCUIAutomation/XCUIElement/KeyModifierFlags)

Flags for simulating combination keystrokes with keys, such as Control, Option, Shift, and Command.

### Moving the pointer

[`-  hover`](/documentation/XCUIAutomation/XCUIElement/hover())

Moves the pointer over the element.

### Clicking

[`-  click`](/documentation/XCUIAutomation/XCUIElement/click())

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

[`-  clickForDuration:thenDragToElement:`](/documentation/XCUIAutomation/XCUIElement/click(forDuration:thenDragTo:))

Clicks and holds an element for a duration you specify, and then drags it to another element.

[`-  clickForDuration:thenDragToElement:withVelocity:thenHoldForDuration:`](/documentation/XCUIAutomation/XCUIElement/click(forDuration:thenDragTo:withVelocity:thenHoldForDuration:))

Clicks and holds an element for a duration, drags it at a velocity, and holds it over another element for a duration, all of which you specify.

[`-  doubleClick`](/documentation/XCUIAutomation/XCUIElement/doubleClick())

Sends a double-click event to a hittable point the system computes for the element.

[`-  rightClick`](/documentation/XCUIAutomation/XCUIElement/rightClick())

Sends a Control-click event to a hittable point the system computes for the element.

### Scrolling

[`-  scrollByDeltaX:deltaY:`](/documentation/XCUIAutomation/XCUIElement/scroll(byDeltaX:deltaY:))

Scrolls the view by the number of x and y pixels you specify.

### Tapping and pressing

[`-  tap`](/documentation/XCUIAutomation/XCUIElement/tap())

Sends a tap event to a hittable point the system computes for the element.

[`-  doubleTap`](/documentation/XCUIAutomation/XCUIElement/doubleTap())

Sends a double-tap event to a hittable point the system computes for the element.

[`-  pressForDuration:`](/documentation/XCUIAutomation/XCUIElement/press(forDuration:))

Sends a press-and-hold gesture to a hittable point the system computes for the element, holding for the duration you specify.

[`-  pressForDuration:thenDragToElement:`](/documentation/XCUIAutomation/XCUIElement/press(forDuration:thenDragTo:))

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

[`-  pressForDuration:thenDragToElement:withVelocity:thenHoldForDuration:`](/documentation/XCUIAutomation/XCUIElement/press(forDuration:thenDragTo:withVelocity:thenHoldForDuration:))

Initiates a press-and-hold gesture, drags to another element at a velocity, and holds for a duration, all of which you specify.

### Tapping multiple times

[`-  twoFingerTap`](/documentation/XCUIAutomation/XCUIElement/twoFingerTap())

Sends a two-finger tap event to a hittable point the system computes for the element.

[`-  tapWithNumberOfTaps:numberOfTouches:`](/documentation/XCUIAutomation/XCUIElement/tap(withNumberOfTaps:numberOfTouches:))

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

### Performing gestures

[`-  swipeLeft`](/documentation/XCUIAutomation/XCUIElement/swipeLeft())

Sends a swipe-left gesture.

[`-  swipeLeftWithVelocity:`](/documentation/XCUIAutomation/XCUIElement/swipeLeft(velocity:))

Sends a swipe-left gesture with a velocity you specify.

[`-  swipeRight`](/documentation/XCUIAutomation/XCUIElement/swipeRight())

Sends a swipe-right gesture.

[`-  swipeRightWithVelocity:`](/documentation/XCUIAutomation/XCUIElement/swipeRight(velocity:))

Sends a swipe-right gesture with a velocity you specify.

[`-  swipeUp`](/documentation/XCUIAutomation/XCUIElement/swipeUp())

Sends a swipe-up gesture.

[`-  swipeUpWithVelocity:`](/documentation/XCUIAutomation/XCUIElement/swipeUp(velocity:))

Sends a swipe-up gesture with a velocity you specify.

[`-  swipeDown`](/documentation/XCUIAutomation/XCUIElement/swipeDown())

Sends a swipe-down gesture.

[`-  swipeDownWithVelocity:`](/documentation/XCUIAutomation/XCUIElement/swipeDown(velocity:))

Sends a swipe-down gesture with a velocity you specify.

[`-  pinchWithScale:velocity:`](/documentation/XCUIAutomation/XCUIElement/pinch(withScale:velocity:))

Sends a pinching gesture with two touches.

[`-  rotate:withVelocity:`](/documentation/XCUIAutomation/XCUIElement/rotate(_:withVelocity:))

Sends a rotation gesture with two touches.

[`XCUIGestureVelocity`](/documentation/XCUIAutomation/XCUIGestureVelocity)

A value that describes how fast a gesture moves across the screen, in pixels per second.

### Interacting with sliders

[`normalizedSliderPosition`](/documentation/XCUIAutomation/XCUIElement/normalizedSliderPosition)

Returns the position of the slider’s indicator as a normalized value.

[`-  adjustToNormalizedSliderPosition:`](/documentation/XCUIAutomation/XCUIElement/adjust(toNormalizedSliderPosition:))

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

### Interacting with pickers

[`-  adjustToPickerWheelValue:`](/documentation/XCUIAutomation/XCUIElement/adjust(toPickerWheelValue:))

Changes the value that the picker wheel displays.

### Calculating coordinates

[`-  coordinateWithNormalizedOffset:`](/documentation/XCUIAutomation/XCUIElement/coordinate(withNormalizedOffset:))

Creates and returns a new coordinate with a normalized offset.

### Supporting types

[`ElementType`](/documentation/XCUIAutomation/XCUIElement/ElementType)

The types of UI elements that you find, inspect, and interact with in a UI test.

[`SizeClass`](/documentation/XCUIAutomation/XCUIElement/SizeClass)

The user interface size classes you can inspect in a UI test.

[`AttributeName`](/documentation/XCUIAutomation/XCUIElement/AttributeName)

A set of string constants that serve as keys for storing element attributes in a dictionary.

### Deprecated methods

[`swipeDown(withVelocity:)`](/documentation/XCUIAutomation/XCUIElement/swipeDown(withVelocity:))

Sends a swipe-down gesture with a velocity you specify.

[`swipeUp(withVelocity:)`](/documentation/XCUIAutomation/XCUIElement/swipeUp(withVelocity:))

Sends a swipe-up gesture with a velocity you specify.

[`swipeLeft(withVelocity:)`](/documentation/XCUIAutomation/XCUIElement/swipeLeft(withVelocity:))

Sends a swipe-left gesture with a velocity you specify.

[`swipeRight(withVelocity:)`](/documentation/XCUIAutomation/XCUIElement/swipeRight(withVelocity:))

Sends a swipe-right gesture with a velocity you specify.

## Relationships

### Conforms To

[`CVarArg`](/documentation/Swift/CVarArg)

[`XCUIElementSnapshotProviding`](/documentation/XCUIAutomation/XCUIElementSnapshotProviding)

[`Escapable`](/documentation/Swift/Escapable)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`XCUIElementAttributes`](/documentation/XCUIAutomation/XCUIElementAttributes)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`XCUIElementTypeQueryProvider`](/documentation/XCUIAutomation/XCUIElementTypeQueryProvider)

[`Sendable`](/documentation/Swift/Sendable)

[`Equatable`](/documentation/Swift/Equatable)

[`Hashable`](/documentation/Swift/Hashable)

[`Copyable`](/documentation/Swift/Copyable)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`XCUIScreenshotProviding`](/documentation/XCUIAutomation/XCUIScreenshotProviding)

### Inherited By

[`XCUIApplication`](/documentation/XCUIAutomation/XCUIApplication)

### Inherits From

[`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)