GREYInteraction

@protocol GREYInteraction <NSObject>

Represents an interaction with a UI element.

  • Data source for providing UI elements to interact with. The dataSource must adopt GREYInteractionDataSource protocol and a weak reference is held.

    Declaration

    Objective-C

    @property (readwrite, nonatomic) id<GREYInteractionDataSource> dataSource;

  • Indicates that the current interaction should be performed on a UI element contained inside another UI element that is uniquely matched by @c rootMatcher.

    Declaration

    Objective-C

    - (instancetype)inRoot:(id<GREYMatcher>)rootMatcher;

    Parameters

    rootMatcher

    Matcher used to select the container of the element the interaction will be performed on.

    Return Value

    The provided GREYInteraction instance, with an appropriate rootMatcher.

  • Performs the @c action repeatedly on the the element matching the @c matcher until the element to interact with (specified by GREYInteraction::selectElementWithMatcher:) is found or a timeout occurs. The search action is only performed when coupled with GREYInteraction::performAction:, GREYInteraction::assert:, or GREYInteraction::assertWithMatcher: APIs. This API only creates an interaction consisting of repeated executions of the search action provided. You need to call an action or assertion after this in order to interaction with the element being searched for.

    For example, this code will perform an upward scroll of 50 points until an element is found and then tap on it: @code [[[EarlGrey selectElementWithMatcher:grey_accessibilityID(@elementToFind)] usingSearchAction:grey_scrollInDirection(kGREYDirectionUp, 50.0f) onElementWithMatcher:grey_accessibilityID(@ScrollingWindow)] performAction:grey_tap()] // This should be separately called for the action. @endcode

    Declaration

    Objective-C

    - (instancetype)usingSearchAction:(id<GREYAction>)action
             onElementWithMatcher:(id<GREYMatcher>)matcher;

    Parameters

    action

    The action to be performed on the element.
    matcher

    The matcher that the element matches.

    Return Value

    The provided GREYInteraction instance, with an appropriate action and matcher.

  • Performs an @c action on the selected UI element.

    Declaration

    Objective-C

    - (instancetype)performAction:(id<GREYAction>)action;

    Parameters

    action

    The action to be performed on the @c element. @throws NSException if the action fails.

    Return Value

    The provided GREYInteraction instance with an appropriate action.

  • Performs an @c action on the selected UI element with an error set on failure.

    Declaration

    Objective-C

    - (instancetype)performAction:(id<GREYAction>)action
                        error:(NSError **)errorOrNil;

    Parameters

    action

    The action to be performed on the @c element. @param[out] errorOrNil Error populated on failure. @throws NSException on action failure if @c errorOrNil is not set.
    errorOrNil

    Return Value

    The provided GREYInteraction instance, with an action and an error that will be populated on failure.

  • Performs an @c assertion on the selected UI element.

    Declaration

    Objective-C

    - (instancetype)assert:(id<GREYAssertion>)assertion;

    Parameters

    assertion

    The assertion to be performed on the @c element. @throws NSException if the @c assertion fails.

    Return Value

    The provided GREYInteraction instance with a valid assertion.

  • Performs an @c assertion on the selected UI element with an error set on failure.

    Declaration

    Objective-C

    - (instancetype)assert:(id<GREYAssertion>)assertion
                 error:(NSError **)errorOrNil;

    Parameters

    assertion

    The assertion to be performed on the @c element. @param[out] errorOrNil Error populated on failure. @throws NSException on assertion failure if @c errorOrNil is not set.
    errorOrNil

    Return Value

    The provided GREYInteraction instance with an assertion and an error that will be populated on failure.

  • Performs an assertion that evaluates @c matcher on the selected UI element.

    Declaration

    Objective-C

    - (instancetype)assertWithMatcher:(id<GREYMatcher>)matcher;

    Parameters

    matcher

    The matcher to be evaluated on the @c element.

    Return Value

    The provided GREYInteraction instance with a matcher to be evaluated on an element.

  • Performs an assertion that evaluates @c matcher on the selected UI element.

    Declaration

    Objective-C

    - (instancetype)assertWithMatcher:(id<GREYMatcher>)matcher
                            error:(NSError **)errorOrNil;

    Parameters

    matcher

    The matcher to be evaluated on the @c element. @param[out] errorOrNil Error populated on failure. @throws NSException on assertion failure if @c errorOrNil is not set.
    errorOrNil

    Return Value

    The provided GREYInteraction instance, with a matcher to be evaluated on an element and an error that will be populated on failure.

  • In case of multiple matches, selects the element at the specified index. In case of the index being over the number of matched elements, it throws an exception. Please make sure that this is used after you’ve created the matcher. For example, in case three elements are matched, and you wish to match with the second one, then @c atIndex would be used in this manner:

    @code [[EarlGrey selectElementWithMatcher:grey_accessibilityLabel(@Generic Matcher)] atIndex:1]; @endcode

    Declaration

    Objective-C

    - (instancetype)atIndex:(NSUInteger)index;

    Swift

    func atIndex(_ index: UInt) -> Self!

    Parameters

    index

    The zero-indexed position of the element in the list of matched elements to be selected. @throws NSException if the @c index is more than the number of matched elements.

    Return Value

    An interaction (assertion or an action) to be performed on the element at the specified index in the list of matched elements.