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

# XCUIElementQuery

An object that defines the search criteria a test uses to identify UI elements.

```
@MainActor class XCUIElementQuery
```

## Discussion

Use element queries to find UI elements in your app that you interact with in the tests, to test for the presence of expected elements, or to discover elements to test their values.

For example, this test uses an element query to find the “Add Book” button, and after clicking the button, checks that there’s one button in an outline view cell titled “Untitled Book”.
If the test can’t find the “Add Book” button, or there isn’t one “Untitled Book” cell, then the test fails.

```swift
@MainActor
func testClickingAddCreatesAnUntitledBook() throws {
    let app = XCUIApplication()
    app.launch()
    let list = app.windows["Reading Journal"]
    list.toolbars.children(matching: .button)["Add Book"].click()
    XCTAssertEqual(list.outlines["Sidebar"].cells.containing(.button, identifier:"Untitled Book").count, 1)
}
```

## Topics

### Creating new queries

[`children(matching:)`](/documentation/XCUIAutomation/XCUIElementQuery/children(matching:))

Returns a new query that matches all direct children of the requested type.

[`descendants(matching:)`](/documentation/XCUIAutomation/XCUIElementQuery/descendants(matching:))

Returns a new query that matches all descendants of the requested type.

[`containing(_:)`](/documentation/XCUIAutomation/XCUIElementQuery/containing(_:))

Returns a new query that matches elements containing a descendant that meets the logical conditions of the provided predicate.

[`containing(_:identifier:)`](/documentation/XCUIAutomation/XCUIElementQuery/containing(_:identifier:))

Returns a new query that matches elements that contain a descendant of the requested type and an identifying property that matches a provided identifier.

[`matching(identifier:)`](/documentation/XCUIAutomation/XCUIElementQuery/matching(identifier:))

Returns a new query that matches elements that have an identifying property that matches a provided identifier.

[`matching(_:)`](/documentation/XCUIAutomation/XCUIElementQuery/matching(_:))

Returns a new query that matches elements that meet the logical conditions of the provided predicate.

[`matching(_:identifier:)`](/documentation/XCUIAutomation/XCUIElementQuery/matching(_:identifier:))

Returns a new query that matches elements of the requested type and have an identifying property that matches a provided identifier.

### Accessing matched elements

[`allElementsBoundByAccessibilityElement`](/documentation/XCUIAutomation/XCUIElementQuery/allElementsBoundByAccessibilityElement)

Immediately evaluates the query and returns an array of elements bound to the resulting accessibility elements.

[`allElementsBoundByIndex`](/documentation/XCUIAutomation/XCUIElementQuery/allElementsBoundByIndex)

Immediately evaluates the query and returns an array of elements bound by the index of each result.

[`count`](/documentation/XCUIAutomation/XCUIElementQuery/count)

Evaluates the query and returns the number of elements that match.

[`element`](/documentation/XCUIAutomation/XCUIElementQuery/element)

The query’s single matching element.

[`element(boundBy:)`](/documentation/XCUIAutomation/XCUIElementQuery/element(boundBy:))

Uses an index into the query’s results to determine which underlying accessibility element to use.

[`element(matching:)`](/documentation/XCUIAutomation/XCUIElementQuery/element(matching:))

Matches the predicate.

[`element(matching:identifier:)`](/documentation/XCUIAutomation/XCUIElementQuery/element(matching:identifier:))

Matches the provided element type and identifier.

[`subscript(_:)`](/documentation/XCUIAutomation/XCUIElementQuery/subscript(_:))

Returns a descendant element that matches a provided identifier.

[`element(at:)`](/documentation/XCUIAutomation/XCUIElementQuery/element(at:))

Returns an element that resolves to the index into the query’s result set.

### Debugging element queries

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

Provides debugging information about the query.

### Identifying window buttons

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

The identifier for a window’s close button.

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

The identifier for a window’s full-screen button.

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

The identifier for a window’s minimize button.

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

The identifier for a window’s zoom button.


---

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)