EarlGreyImpl

@interface EarlGreyImpl : NSObject

Entrypoint to the EarlGrey framework. Use methods of this class to initiate interaction with any UI element on the screen.

  • Provides the file name and line number of the code that is calling into EarlGrey. In case of a failure, the information is used to tell XCTest the exact line which caused the failure so it can be highlighted in the IDE.

    Declaration

    Objective-C

    + (instancetype)invokedFromFile:(NSString *)fileName
                     lineNumber:(NSUInteger)lineNumber;

    Swift

    class func invoked(fromFile fileName: String!, lineNumber: UInt) -> Self!

    Parameters

    fileName

    The name of the file where the failing code exists.
    lineNumber

    The line number of the failing code.

    Return Value

    An EarlGreyImpl instance, with details of the code invoking EarlGrey.

  • @remark init is not an available initializer. Use the EarlGrey macro to start an interaction.

    Declaration

    Objective-C

    - (instancetype)init;

  • Creates a pending interaction with a single UI element on the screen.

    In this step, a matcher is supplied to EarlGrey which is later used to sift through the elements in the UI Hierarchy. This method only denotes that you have an intent to perform an action and packages a GREYElementInteraction object to do so. The interaction is actually started when it’s performed with a @c GREYAction or @c GREYAssertion.

    An interaction will fail when multiple elements are matched. In that case, you will have to refine the @c elementMatcher to match a single element or use GREYInteraction::atIndex: to specify the index of the element in the list of elements matched.

    By default, EarlGrey looks at all the windows from front to back and searches for the UI element. To focus on a specific window or container, use GREYElementInteraction::inRoot: method.

    For example, this code will match a UI element with accessibility identifier foo inside a custom UIWindow of type MyCustomWindow: @code [[EarlGrey selectElementWithMatcher:grey_accessibilityID(@foo)] inRoot:grey_kindOfClass([MyCustomWindow class])] @endcode

    Declaration

    Objective-C

    - (GREYElementInteraction *)selectElementWithMatcher:
    (id<GREYMatcher>)elementMatcher;

    Swift

    func selectElement(withMatcher elementMatcher: Any!) -> Any!

    Parameters

    elementMatcher

    The matcher specifying the UI element that will be targeted by the interaction.

    Return Value

    A GREYElementInteraction instance, initialized with an appropriate matcher.

  • Sets the global failure handler for all framework related failures.

    A default failure handler is provided by the framework and it is @b strongly advised to use that if you don’t need to customize error handling in your test. Passing in @c nil will revert the failure handler to default framework provided failure handler.

    Declaration

    Objective-C

    - (void)setFailureHandler:(id<GREYFailureHandler>)handler;

    Swift

    func setFailureHandler(_ handler: Any!)

    Parameters

    handler

    The failure handler to be used for all test failures.

  • Convenience wrapper to invoke GREYFailureHandler::handleException:details: on the global failure handler.

    Declaration

    Objective-C

    - (void)handleException:(GREYFrameworkException *)exception
                details:(NSString *)details;

    Swift

    func handleException(_ exception: Any!, details: String!)

    Parameters

    exception

    The exception to be handled.
    details

    Any extra details about the failure.

  • Rotate the device to a given @c deviceOrientation. All device orientations except for @c UIDeviceOrientationUnknown are supported. If a non-nil @c errorOrNil is provided, it will be populated with the failure reason if the orientation change fails, otherwise a test failure will be registered.

    Declaration

    Objective-C

    - (BOOL)rotateDeviceToOrientation:(UIDeviceOrientation)deviceOrientation
                       errorOrNil:(NSError **)errorOrNil;

    Swift

    func rotateDevice(toOrientation deviceOrientation: Any!, errorOrNil: UnsafeMutablePointer

    Parameters

    deviceOrientation

    The desired orientation of the device. @param[out] errorOrNil Error that will be populated on failure. If @c nil, a test failure will be reported if the rotation attempt fails.
    errorOrNil

    Return Value

    @c YES if the rotation was successful, @c NO otherwise.

  • Dismisses the keyboard by resigning the first responder, if any. Will populate the provided error if the first responder is not present or if the keyboard is not visible.

    @param[out] errorOrNil Error that will be populated on failure. If @c nil, a test failure will be reported if the dismissing fails.

    Declaration

    Objective-C

    - (BOOL)dismissKeyboardWithError:(NSError **)errorOrNil;

    Swift

    func dismissKeyboardWithError(_ errorOrNil: UnsafeMutablePointer

    Parameters

    errorOrNil

    Return Value

    @c YES if the dismissing of the keyboard was successful, @c NO otherwise.