---
title: "matching(_:)"
framework: xcuiautomation
role: symbol
role_heading: Instance Method
path: "xcuiautomation/xcuielementquery/matching(_:)"
---

# matching(_:)

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

## Declaration

```swift
func matching(_ predicate: NSPredicate) -> XCUIElementQuery
```

## Parameters

- `predicate`: The predicate used to evaluate each element.

## Return Value

Return Value A new query that defines a search that extends the search criteria of the receiver. The new search matches elements that match the original search and also meet the logical conditions of the provided predicate.

## Discussion

Discussion The predicate evaluates against objects that conform to the XCUIElementAttributes protocol. note: Where possible, use NSExpression-based or format-string-based predicates with this method in preference to block-based predicates. This enables the framework to optimize the query’s performance.

## See Also

### Creating new queries

- [children(matching:)](xcuiautomation/xcuielementquery/children(matching:).md)
- [descendants(matching:)](xcuiautomation/xcuielementquery/descendants(matching:).md)
- [containing(_:)](xcuiautomation/xcuielementquery/containing(_:).md)
- [containing(_:identifier:)](xcuiautomation/xcuielementquery/containing(_:identifier:).md)
- [matching(identifier:)](xcuiautomation/xcuielementquery/matching(identifier:).md)
- [matching(_:identifier:)](xcuiautomation/xcuielementquery/matching(_:identifier:).md)