XCUIElement

extension XCUIElement

XCUIElement extension contains additional methods for handling swipes, tapping on elements or clearing text fields.

The isVisible property indicates if the element exists and is hittable. There are cases where checking only hittable property is not working as expected.

The text property can be used to retrieve value from text field as String.

swipe(from:to:) is an alternative to swipeUp, swipeDown, swipeLeft and swipeBottom methods provided by XCTest. It lets you specify coordinates on the screen (relative to the view on which the method is called).

Example:

let scroll = app.scrollViews.element
scroll.swipe(from: CGVector(dx: 0, dy: 0), to: CGVector(dx: 1, dy: 1))

swipe(to:avoid:from:) variation scrolls the screen until given element becomes visible. Note that XCTest automatically does the scrolling during tap(), but the method is still useful in some situations, for example to reveal element from behind keyboard.

Example:

let scroll = app.scrollViews.element
let button = scroll.buttons.element
scroll.swipe(to: button)

swipe(to:times:avoid:from:until:), and two specialized method swipe(to:untilExist:times:avoid:from:) and swipe(to:untilVisible:times:avoid:from:), swipes scroll view to given direction until condition will be satisfied or in case of specialised methods element would exist or will be visible. It is a useful method to scroll collection view to reveal an element. In collection view, only a few cells are available in the hierarchy. To scroll to given element you have to provide swipe direction. It is not possible to detect when the end of the scroll was reached, that is why the maximum number of swipes is required (by default 10). The method will stop when the maximum number of swipes is reached or when the condition will be satisfied.

Example:

let collectionView = app.collectionViews.element
let element = collectionView.staticTexts["More"]
collectionView.swipe(to: .down, untilVisible: element)

clearTextField() and clear(andType:) provides straightforward method to delete text from text field and then type the provided string.

tap(withOffset:app:orientation:) performs tap() on given coordinates (relative to the receiving element). Can be used to test view where position of the tap matters. It’s also possible to tap a subview (like table view cell), without actually queuing that subview.

smartCoordinate(withNormalizedOffset:app:orientation:) is an replacement of the coordinate(withNormalizedOffset:) from XCUIElement. XCUICoordinate has an open issue. Coordinates works correctly only in portrait orientation. This method and SmartXCUICoordinate was implemented as a workaround based on glebon gist.

let element = app.tableViews.element
element.smartCoordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap()

Properties

  • Default number of swipes.

    Declaration

    Swift

    public class var defaultSwipesCount: Int { get }

Methods

  • Perform swipe gesture on this view by swiping between provided points.

    It is an alternative to swipeUp, swipeDown, swipeLeft and swipeBottom methods provided by XCTest. It lets you specify coordinates on the screen (relative to the view on which the method is called).

    Example:

    let scroll = app.scrollViews.element
scroll.swipe(from: CGVector(dx: 0, dy: 0), to: CGVector(dx: 1, dy: 1))

  • Swipes scroll view to reveal given element.

    Example:

    let scroll = app.scrollViews.element
let button = scroll.buttons.element
scroll.swipe(to: button)

    Note

    XCTest automatically does the scrolling during tap(), but the method is still useful in some situations, for example to reveal element from behind keyboard, navigation bar or user defined element.

    Note

    This method assumes that element is scrollable and at least partially visible on the screen.

  • Swipes scroll view to given direction until condition will be satisfied.

    A useful method to scroll collection view to reveal an element. In collection view, only a few cells are available in the hierarchy. To scroll to given element you have to provide swipe direction. It is not possible to detect when the end of the scroll was reached, that is why the maximum number of swipes is required (by default 10). The method will stop when the maximum number of swipes is reached or when the condition will be satisfied.

    Example:

    let collectionView = app.collectionViews.element
let element = collectionView.staticTexts["More"]
collectionView.swipe(to: .down, until: element.exists)

  • Swipes scroll view to given direction until element would exist.

    A useful method to scroll collection view to reveal an element. In collection view, only a few cells are available in the hierarchy. To scroll to given element you have to provide swipe direction. It is not possible to detect when the end of the scroll was reached, that is why the maximum number of swipes is required (by default 10). The method will stop when the maximum number of swipes is reached or when the given element will appear in the view hierarchy.

    Example:

    let collectionView = app.collectionViews.element
let element = collectionView.staticTexts["More"]
collectionView.swipe(to: .down, untilExist: element)

    Note

    This method will not scroll until the view will be visible. To do this call swipe(to:untilVisible:times:avoid:app:) after this method.

  • Swipes scroll view to given direction until element would be visible.

    A useful method to scroll collection view to reveal an element. In collection view, only a few cells are available in the hierarchy. To scroll to given element you have to provide swipe direction. It is not possible to detect when the end of the scroll was reached, that is why the maximum number of swipes is required (by default 10). The method will stop when the maximum number of swipes is reached or when the given element will be visible.

    Example:

    let collectionView = app.collectionViews.element
let element = collectionView.staticTexts["More"]
collectionView.swipe(to: .down, untilVisible: element)

    Note

    This method will not scroll until the view will be visible. To do this call swipe(to:avoid:from:) after this method.

Properties

  • Indicates if the element is currently visible on the screen.

    Example:

    let button = app.buttons.element
button.tap()
XCTAssertTrue(button.isVisible)

    Declaration

    Swift

    var isVisible: Bool { get }

  • Returns value as a String

    Example:

    let textField = app.textFields.element
let text = textField.text

    Note

    It will fail if value is not a String type.

    Declaration

    Swift

    var text: String { get }

Methods

  • Remove text from textField or secureTextField.

    Example:

    let textField = app.textFields.element
textField.clearTextField()

  • Remove text from textField and enter new value.

    Useful if there is chance that the element contains text already. This helper method will execute clearTextField and then type the provided string.

    Example:

    let textField = app.textFields.element
textField.clear(andType: "text")