XCUIElementQuery

public extension XCUIElementQuery

XCUIElementQuery extension contains additional methods for identifying and searching elements.

element(withLabelMatching:comparisonOperator:) returns element with label matching provided string. String matching is customizable with operators available in NSPredicate specification.

Example:

let text = app.staticTexts.element(withLabelMatching: "John*", comparisonOperator: .like)
XCTAssertTrue(text.exists)

elements(withLabelsMatching:comparisonOperator:) is a similar method but can be used when looking for an element which label can match one of many texts.

Example:

let texts = ["OK", "Done", "Go"]
let elements = app.buttons.elements(withLabelsMatching: texts, comparisonOperator: .equals)

element(withIdentifier:label:labelComparisonOperator:) can be used to find element with given identifier and label. Useful to find a cell which UILabel, with provided identifier, contains text provided by label.

Example:

let cell = app.cells.element(withIdentifier: "title", label: "Made with love")

element(withIdentifier:labels:labelComparisonOperator:) can be used to find localized element with given identifier. E.g. to find label with identifier state and label which can by localized with texts: open, otwarty, öffnen:

Example:

let label = app.staticTexts.element(withIdentifier: "state", labels: ["open", "otwarty", "öffnen"])

element(containingLabels:labelsComparisonOperator:) is an extension to previous method. Searches for element that has sub-elements matching provided identifier:label pairs. Especially useful for table views and collection views where cells will have the same identifier.

Example:

let tableView = app.tables.element
let cell = tableView.cells.element(containingLabels: ["name": "John*", "email": "*.com"], labelsComparisonOperator: .like)
XCTAssertTrue(cell.exists)

In addition shorted variants are available:

  • element(withLabelPrefixed:)
  • element(withLabelContaining:)
  • elements(withLabelsContaining:)
  • elements(withLabelsLike:)

Modifications for Locator protocol are also available:

  • element(withLabelMatchingLocator:comparisonOperator:)
  • element(withLocator:label:labelComparisonOperator:)
  • element(containingLabels:labelsComparisonOperator:)

Locator methods

  • Returns XCUIElement that matches the type and locator.

    Example:

    let button = app.buttons[Locators.ok]

    Declaration

    Swift

    subscript(locator: Locator) -> XCUIElement { get }

    Parameters

    locator

    Locator used to find element

  • Returns element with label matching provided string.

    Note

    String matching is customizable with operators available in NSPredicate specification. Check the StringComparisonOperator for available options.

    Example:

    let text = app.staticTexts.element(withLabelMatchingLocator: Locators.john, comparisonOperator: .like)
XCTAssertTrue(text.exists)

    Declaration

    Swift

    func element(withLabelMatchingLocator locator: Locator, comparisonOperator: StringComparisonOperator = .equals) -> XCUIElement

    Parameters

    locator

    Locator to search for.
    comparisonOperator

    Operation to use when performing comparison.

    Return Value

    XCUIElement that label matches given locator.

  • Returns element with identifier and label matching provided values.

    Can be used to find a cell which UILabel, with provided identifier, contains text provided by label.

    Note

    String matching is customizable with operators available in NSPredicate specification. Check the StringComparisonOperator for available options.

    Example:

    let label = app.staticTexts.element(withLocator: Locators.title, label: Locators.madeWithLove)

    Declaration

    Swift

    func element(withLocator locator: Locator, label: Locator, labelComparisonOperator: StringComparisonOperator = .equals) -> XCUIElement

    Parameters

    locator

    Identifier of element to search for.
    label

    Label of element to search for.
    labelComparisonOperator

    Operation to use when performing comparison.

    Return Value

    XCUIElement that identifier and label match to given locators.

  • Returns element with identifier and label matching provided values.

    Can be used to find a cell which UILabel, with provided identifier, contains text provided by label.

    Note

    String matching is customizable with operators available in NSPredicate specification. Check the StringComparisonOperator for available options.

    Example:

    let label = app.staticTexts.element(withLocator: Locators.title, label: "Made with love")

    Declaration

    Swift

    func element(withLocator locator: Locator, label: String, labelComparisonOperator: StringComparisonOperator = .equals) -> XCUIElement

    Parameters

    locator

    Identifier of element to search for.
    label

    Label of element to search for.
    labelComparisonOperator

    Operation to use when performing comparison.

    Return Value

    XCUIElement that identifier and label match to given locator and text.

  • Returns element with identifier and label matching one of provided values.

    Can be used to find a UILabel with given identifier and localized labels. Localized texts are provided in the labels parameter.

    Note

    String matching is customizable with operators available in NSPredicate specification. Check the StringComparisonOperator for available options.

    Example:

    let label = app.staticTexts.element(withLocator: Locators.title, labels: ["Z miłością przez", "Made with love by"])

    Declaration

    Swift

    func element(withLocator locator: Locator, labels: [String], labelComparisonOperator: StringComparisonOperator = .equals) -> XCUIElement

    Parameters

    locator

    Identifier of element to search for.
    labels

    Labels of element to search for.
    labelComparisonOperator

    Operation to use when performing comparison.

    Return Value

    XCUIElement that identifier and label match given texts.

  • Returns element that contains children matching provided locator-label dictionary.

    Searches for element that has sub-elements matching provided locator:label pairs. Especially useful for table views and collection views where cells will have the same identifier.

    Note

    String matching is customizable with operators available in NSPredicate specification. Check the StringComparisonOperator for available options.

    Note

    This method is intended to be used with table and collection views, where cells have to be identified by their contents.

    Example:

    let tableView = app.tables.element
let cell = tableView.cells.element(containingLabels: [Locators.name: "John*", Locators.email: "*.com"], labelsComparisonOperator: .like)
XCTAssertTrue(cell.exists)

    Declaration

    Swift

    func element<LocatorItem>(containingLabels dictionary: [LocatorItem : String], labelsComparisonOperator: StringComparisonOperator = .equals) -> XCUIElement where LocatorItem : Locator, LocatorItem : Hashable

    Parameters

    dictionary

    Dictionary of locators and labels to search for.
    labelsComparisonOperator

    Operation to use when performing comparison.

    Return Value

    XCUIElement that identifiers and labels match to given locators and texts.

  • Returns element that contains children matching provided locator-label dictionary.

    Searches for element that has sub-elements matching provided locator:label pairs. Especially useful for table views and collection views where cells will have the same identifier.

    Note

    String matching is customizable with operators available in NSPredicate specification. Check the StringComparisonOperator for available options.

    Note

    This method is intended to be used with table and collection views, where cells have to be identified by their contents.

    Example:

    let tableView = app.tables.element
let cell = tableView.cells.element(containingLabels: [Locators.name: ["John*", "Jan*"], Locators.email: ["Free*", "Wolny*"]], labelsComparisonOperator: .like)
XCTAssertTrue(cell.exists)

    Declaration

    Swift

    func element<LocatorItem>(containingLabels dictionary: [LocatorItem : [String]], labelsComparisonOperator: StringComparisonOperator = .equals) -> XCUIElement where LocatorItem : Locator, LocatorItem : Hashable

    Parameters

    dictionary

    Dictionary of locators and labels to search for.
    labelsComparisonOperator

    Operation to use when performing comparison.

    Return Value

    XCUIElement that identifiers and labels match to given locators and texts.

Locator shorted methods

  • Returns element with label which begins with provided Locator.

    Example:

    let text = app.staticTexts.element(withLabelPrefixed: Locators.john)
XCTAssertTrue(text.exists)

    Declaration

    Swift

    func element(withLabelPrefixed locator: Locator) -> XCUIElement

    Parameters

    locator

    Object conforming to Locator.

    Return Value

    XCUIElement that label begins with given locator.

  • Returns element with label which contains provided Locator.

    Example:

    let text = app.staticTexts.element(withLabelContaining: Locators.john)
XCTAssertTrue(text.exists)

    Declaration

    Swift

    func element(withLabelContaining locator: Locator) -> XCUIElement

    Parameters

    locator

    Object conforming to Locator.

    Return Value

    XCUIElement that label contains given locator.

Predicates

  • Returns predicate with identifier and label matching one of provided values.

    Can be used to find a UILabel with given identifier and localized labels. Localized texts are provided in the labels parameter.

    Note

    String matching is customizable with operators available in NSPredicate specification. Check the StringComparisonOperator for available options.

    Example:

    let predicate = XCUIElementQuery.predicate(withIdentifier: "title", labels: ["Z miłością przez", "Made with love by"])
let label = app.staticTexts.element(matching: predicate)

    Declaration

    Swift

    class func predicate(withIdentifier identifier: String, labels: [String], labelComparisonOperator: StringComparisonOperator = .equals) -> NSPredicate

    Parameters

    identifier

    Identifier of element to search for.
    labels

    Labels of element to search for.
    labelComparisonOperator

    Operation to use when performing comparison.

    Return Value

    An predicate which matches element which identifier and label match given texts.

Methods

  • Returns element with label matching provided string.

    Note

    String matching is customizable with operators available in NSPredicate specification. Check the StringComparisonOperator for available options.

    Example:

    let text = app.staticTexts.element(withLabelMatching: "John*", comparisonOperator: .like)
XCTAssertTrue(text.exists)

    Declaration

    Swift

    func element(withLabelMatching text: String, comparisonOperator: StringComparisonOperator = .equals) -> XCUIElement

    Parameters

    text

    String to search for.
    comparisonOperator

    Operation to use when performing comparison.

    Return Value

    XCUIElement that label matches to given text.

  • Returns array of existing elements matching given labels.

    Can be used when looking for an element which label can match to one from many texts.

    Note

    String matching is customizable with operators available in NSPredicate specification. Check the StringComparisonOperator for available options.

    Example:

    let texts = ["Ok", "Done", "Go"]
let elements = app.buttons.elements(withLabelsMatching: texts, comparisonOperator: .equals)

    Declaration

    Swift

    func elements(withLabelsMatching texts: [String], comparisonOperator: StringComparisonOperator = .equals) -> [XCUIElement]

    Parameters

    texts

    List of labels.
    comparisonOperator

    Operation to use when performing comparison.

    Return Value

    Array of XCUIElement elements.

  • Returns element with identifier and label matching provided values.

    Can be used to find a cell which UILabel, with provided identifier, contains text provided by label.

    Note

    String matching is customizable with operators available in NSPredicate specification. Check the StringComparisonOperator for available options.

    Example:

    let label = app.staticTexts.element(withIdentifier: "title", label: "Made with love")

    Declaration

    Swift

    func element(withIdentifier identifier: String, label: String, labelComparisonOperator: StringComparisonOperator = .equals) -> XCUIElement

    Parameters

    identifier

    Identifier of element to search for.
    label

    Label of element to search for.
    labelComparisonOperator

    Operation to use when performing comparison.

    Return Value

    XCUIElement that identifier and label match given texts.

  • Returns element with identifier and label matching one of provided values.

    Can be used to find a UILabel with given identifier and localized labels. Localized texts are provided in the labels parameter.

    Note

    String matching is customizable with operators available in NSPredicate specification. Check the StringComparisonOperator for available options.

    Example:

    let label = app.staticTexts.element(withIdentifier: "title", labels: ["Z miłością przez", "Made with love by"])

    Declaration

    Swift

    func element(withIdentifier identifier: String, labels: [String], labelComparisonOperator: StringComparisonOperator = .equals) -> XCUIElement

    Parameters

    identifier

    Identifier of element to search for.
    labels

    Labels of element to search for.
    labelComparisonOperator

    Operation to use when performing comparison.

    Return Value

    XCUIElement that identifier and label match given texts.

  • Returns element that contains children matching provided identifier-label dictionary.

    Searches for element that has sub-elements matching provided identifier:label pairs. Especially useful for table views and collection views where cells will have the same identifier.

    Note

    String matching is customizable with operators available in NSPredicate specification. Check the StringComparisonOperator for available options.

    Note

    This method is intended to be used with table and collection views, where cells have to be identified by their contents.

    Example:

    let tableView = app.tables.element
let cell = tableView.cells.element(containingLabels: ["name": "John*", "email": "*.com"], labelsComparisonOperator: .like)
XCTAssertTrue(cell.exists)

    Declaration

    Swift

    func element(containingLabels dictionary: [String : String], labelsComparisonOperator comparisonOperator: StringComparisonOperator = .equals) -> XCUIElement

    Parameters

    dictionary

    Dictionary of identifiers and labels to search for.
    comparisonOperator

    Operation to use when performing comparison.

    Return Value

    XCUIElement that identifiers and labels match given texts.

  • Returns element that contains children matching provided identifier-labels dictionary.

    Searches for element that has sub-elements matching provided identifier:labels pairs. Especially useful for table views and collection views where cells will have the same identifier.

    Note

    String matching is customizable with operators available in NSPredicate specification. Check the StringComparisonOperator for available options.

    Note

    This method is intended to be used with table and collection views, where cells have to be identified by their contents.

    Example:

    let tableView = app.tables.element
let cell = tableView.cells.element(containingLabels: ["name": ["John*", "Jan*"], "email": ["Free*", "Wolny*"]], labelsComparisonOperator: .like)
XCTAssertTrue(cell.exists)

    Declaration

    Swift

    func element(containingLabels dictionary: [String : [String]], labelsComparisonOperator comparisonOperator: StringComparisonOperator = .equals) -> XCUIElement

    Parameters

    dictionary

    Dictionary of identifiers and labels to search for.
    comparisonOperator

    Operation to use when performing comparison.

    Return Value

    XCUIElement that identifiers and labels match given texts.

Shorted

  • Returns element with label which begins with provided string.

    Example:

    let text = app.staticTexts.element(withLabelPrefixed: "John")
XCTAssertTrue(text.exists)

    Declaration

    Swift

    func element(withLabelPrefixed text: String) -> XCUIElement

    Parameters

    text

    String to search for.

    Return Value

    XCUIElement that label begins with given text.

  • Returns element with label which contains provided string.

    Example:

    let text = app.staticTexts.element(withLabelContaining: "John")
XCTAssertTrue(text.exists)

    Declaration

    Swift

    func element(withLabelContaining text: String) -> XCUIElement

    Parameters

    text

    String to search for.

    Return Value

    XCUIElement that label contains given text.

  • Returns array of existing elements containing given labels.

    Example:

    let texts = ["Ok", "Done", "Go"]
let elements = app.buttons.elements(withLabelsContaining: texts)

    Declaration

    Swift

    func elements(withLabelsContaining texts: [String]) -> [XCUIElement]

    Parameters

    texts

    List of labels.

    Return Value

    Array of XCUIElement elements.

  • Returns array of existing elements like given labels.

    Example:

    let texts = ["Ok", ".*Done", "Go"]
let elements = app.buttons.elements(withLabelsLike: texts)

    Declaration

    Swift

    func elements(withLabelsLike texts: [String]) -> [XCUIElement]

    Parameters

    texts

    List of labels.

    Return Value

    Array of XCUIElement elements.