XCUIElement

class XCUIElement : NSObject, XCUIElementAttributes, XCUIElementTypeQueryProvider

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()
  • Default number of swipes.

    Declaration

    Swift

    public class var defaultSwipesCount: Int
  • 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))
    

    Declaration

    Swift

    public func swipe(from startVector: CGVector, to stopVector: CGVector)

    Parameters

    startVector

    Relative point from which to start swipe.

    stopVector

    Relative point to end swipe.

  • 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.

    Declaration

    Swift

    public func swipe(to element: XCUIElement, avoid viewsToAvoid: [AvoidableElement] = [.keyboard, .navigationBar], from app: XCUIApplication = XCUIApplication(), orientation: UIDeviceOrientation = XCUIDevice.shared.orientation)

    Parameters

    element

    Element to scroll to.

    avoid

    Table of AvoidableElement that should be avoid while swiping, by default keyboard and navigation bar are passed.

    app

    Application instance to use when searching for keyboard to avoid.

    orientation

    Device orientation.

  • 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)
    

    Declaration

    Swift

    public func swipe(to direction: SwipeDirection,
                      times: Int = XCUIElement.defaultSwipesCount,
                      avoid viewsToAvoid: [AvoidableElement] = [.keyboard, .navigationBar],
                      from app: XCUIApplication = XCUIApplication(),
                      orientation: UIDeviceOrientation = XCUIDevice.shared.orientation,
                      until condition: @autoclosure () -> Bool)

    Parameters

    direction

    Swipe direction.

    times

    Maximum number of swipes (by default 10).

    viewsToAvoid

    Table of AvoidableElement that should be avoid while swiping, by default keyboard and navigation bar are passed.

    app

    Application instance to use when searching for keyboard to avoid.

    orientation

    Device orientation.

    condition

    The condition to satisfy.

  • 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.

    Declaration

    Swift

    public func swipe(to direction: SwipeDirection, untilExist element: XCUIElement, times: Int = XCUIElement.defaultSwipesCount, avoid viewsToAvoid: [AvoidableElement] = [.keyboard, .navigationBar], from app: XCUIApplication = XCUIApplication())

    Parameters

    direction

    Swipe direction.

    element

    Element to swipe to.

    times

    Maximum number of swipes (by default 10).

    viewsToAvoid

    Table of AvoidableElement that should be avoid while swiping, by default keyboard and navigation bar are passed.

    app

    Application instance to use when searching for keyboard to avoid.

  • 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.

    Declaration

    Swift

    public func swipe(to direction: SwipeDirection, untilVisible element: XCUIElement, times: Int = XCUIElement.defaultSwipesCount, avoid viewsToAvoid: [AvoidableElement] = [.keyboard, .navigationBar], from app: XCUIApplication = XCUIApplication())

    Parameters

    direction

    Swipe direction.

    element

    Element to swipe to.

    times

    Maximum number of swipes (by default 10).

    viewsToAvoid

    Table of AvoidableElement that should be avoid while swiping, by default keyboard and navigation bar are passed.

    app

    Application instance to use when searching for keyboard to avoid.

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

    Example:

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

    Declaration

    Swift

    public var isVisible: Bool
  • 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

    public var text: String
  • Remove text from textField or secureTextField.

    Example:

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

    Declaration

    Swift

    public func 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")
    

    Declaration

    Swift

    public func clear(andType text: String)

    Parameters

    text

    Text to type after clearing old value.