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
andswipeBottom
methods provided byXCTest
. 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 duringtap()
, 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 StringExample:
let textField = app.textFields.element let text = textField.text
Note
It will fail ifvalue
is not aString
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.