GREYMatchers

@interface GREYMatchers : NSObject

EarlGrey matchers for UI elements.

  • Matcher for application’s key window.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForKeyWindow;

    Return Value

    A matcher for the application’s key window.

  • Matcher for UI element with the provided accessibility @c label.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForAccessibilityLabel:
    (nonnull NSString *)label;

    Parameters

    label

    The accessibility label to be matched.

    Return Value

    A matcher for the accessibility label of an accessible element.

  • Matcher for UI element with the provided accessibility ID @c accessibilityID.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForAccessibilityID:
    (nonnull NSString *)accessibilityID;

    Parameters

    accessibilityID

    The accessibility ID to be matched.

    Return Value

    A matcher for the accessibility ID of an accessible element.

  • Matcher for UI element with the provided accessibility @c value.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForAccessibilityValue:
    (nonnull NSString *)value;

    Parameters

    value

    The accessibility value to be matched.

    Return Value

    A matcher for the accessibility value of an accessible element.

  • Matcher for UI element with the provided accessibility @c traits.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForAccessibilityTraits:
    (UIAccessibilityTraits)traits;

    Parameters

    traits

    The accessibility traits to be matched.

    Return Value

    A matcher for the accessibility traits of an accessible element.

  • Matcher for UI element with the provided accessiblity @c hint.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForAccessibilityHint:(nonnull NSString *)hint;

    Parameters

    hint

    The accessibility hint to be matched.

    Return Value

    A matcher for the accessibility hint of an accessible element.

  • Matcher for UI element with accessiblity focus.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForAccessibilityElementIsFocused;

    Return Value

    A matcher for the accessibility focus of an accessible element.

  • Matcher for UI elements of type UIButton, UILabel, UITextField or UITextView displaying the provided @c inputText.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForText:(nonnull NSString *)text;

    Parameters

    text

    The text to be matched in the UI elements.

    Return Value

    A matcher to check for any UI elements with a text field containing the given text.

  • Matcher for element that is the first responder.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForFirstResponder;

    Return Value

    A matcher that verifies if a UI element is the first responder.

  • Matcher to check if system alert view is shown.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForSystemAlertViewShown;

    Return Value

    A matcher to check if a system alert view is being shown.

  • Matcher for UI element whose percent visible area (of its accessibility frame) exceeds the given @c percent.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForMinimumVisiblePercent:(CGFloat)percent;

    Parameters

    percent

    The percent visible area that the UI element being matched has to be visible. Allowed values for @c percent are [0,1] inclusive.

    Return Value

    A matcher that checks if a UI element has a visible area at least equal to a minimum value.

  • Matcher for UI element that is sufficiently visible to the user. EarlGrey considers elements that are more than @c kElementSufficientlyVisiblePercentage (75 %) visible areawise to be sufficiently visible.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForSufficientlyVisible;

    Return Value

    A matcher intialized with a visibility percentage that confirms an element is sufficiently visible.

  • Matcher for UI element that is not visible to the user at all i.e. it has a zero visible area.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForNotVisible;

    Return Value

    A matcher for verifying if an element is not visible.

    • Matcher for UI element that matches EarlGrey’s criteria for user interaction. Currently it must
    • satisfy at least the following criteria:
    • 1) At least a few pixels of the element are visible to the user.
    • 2) The element’s accessibility activation point OR the center of the element’s visible area
    • is completely visible.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForInteractable;

    Return Value

    A matcher that checks if a UI element is interactable.

  • Matcher to check if a UI element is accessible.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForAccessibilityElement;

    Return Value

    A matcher that checks if a UI element is accessible.

  • Matcher for elements that are instances of the provided @c klass or any class that inherits from it.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForKindOfClass:(nonnull Class)klass;

    Parameters

    klass

    A class.

    Return Value

    A matcher that checks if the given element’s class is the provided @c klass or any of its derived classes.

  • Matcher for matching UIProgressView’s values. Use greaterThan, greaterThanOrEqualTo, lessThan etc to create @c comparisonMatcher. For example, to match the UIProgressView elements that have progress value greater than 50.2, use @code [GREYMatchers matcherForProgress:grey_greaterThan(@(50.2))] @endcode. In case if an unimplemented matcher is required, please implement it similar to @c grey_closeTo.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForProgress:
    (nonnull id<GREYMatcher>)comparisonMatcher;

    Parameters

    comparisonMatcher

    The matcher with the value to check the progress against.

    Return Value

    A matcher for checking a UIProgessView’s value.

  • Matcher for UI element that respond to the provided @c sel.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForRespondsToSelector:(nonnull SEL)sel;

    Parameters

    sel

    The selector to be responded to.

    Return Value

    A matcher to check if a UI element’s class responds to a particular selector.

  • Matcher for UI element that conform to the provided @c protocol.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForConformsToProtocol:
    (nonnull Protocol *)protocol;

    Parameters

    protocol

    The protocol that the UI element must conform to.

    Return Value

    A matcher to check if a UI element’s class confirms to a particular protocol.

  • Matcher that matches UI element based on the presence of an ancestor in its hierarchy. The given matcher is used to match decendants.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForAncestor:
    (nonnull id<GREYMatcher>)ancestorMatcher;

    Parameters

    ancestorMatcher

    The ancestor UI element whose descendants are to be matched.

    Return Value

    A matcher to check if a UI element is the descendant of another.

  • Matcher that matches any UI element with a descendant matching the given matcher.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForDescendant:
    (nonnull id<GREYMatcher>)descendantMatcher;

    Parameters

    descendantMatcher

    A matcher being checked to be a descendant of the UI element being checked.

    Return Value

    A matcher to check if a the specified element is in a descendant of another UI element.

  • Matcher that matches UIButton that has title label as @c text.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForButtonTitle:(nonnull NSString *)title;

    Parameters

    title

    The title to be checked on the UIButtons being matched.

    Return Value

    A matcher to confirm UIButton titles.

  • Matcher that matches UIScrollView that has contentOffset as @c offset.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForScrollViewContentOffset:(CGPoint)offset;

    Parameters

    offset

    The content offset to be checked on the UIScrollView being matched.

    Return Value

    A matcher to confirm UIScrollView content offset.

  • Matcher that matches UIStepper with value as @c value.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForStepperValue:(double)value;

    Parameters

    value

    A value that the UIStepper should be checked for.

    Return Value

    A matcher for checking UIStepper values.

  • Matcher that matches a UISlider’s value.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForSliderValueMatcher:
    (nonnull id<GREYMatcher>)valueMatcher;

    Parameters

    valueMatcher

    A matcher for the UISlider’s value. You must provide a valid @c valueMatcher for the floating point value comparison. The @c valueMatcher should be of the type @c closeTo, @c greaterThan, @c lessThan, @c lessThanOrEqualTo, @c greaterThanOrEqualTo. The value matchers should account for any loss in precision for the given floating point value. If you are using @c grey_closeTo, use delta diff as @c kGREYAcceptableFloatDifference. In case if an unimplemented matcher is required, please implement it similar to @c grey_closeTo.

    Return Value

    A matcher for checking a UISlider’s value.

  • Matcher that matches UIPickerView that has a column set to @c value.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForPickerColumn:(NSInteger)column
                                       setToValue:(nonnull NSString *)value;

    Parameters

    column

    The column of the UIPickerView to be matched.
    value

    The value that should be set in the column of the UIPickerView.

    Return Value

    A matcher to check the value in a particular column of a UIPickerView.

  • Matcher that matches UIDatePicker that is set to @c value.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForDatePickerValue:(nonnull NSDate *)value;

    Parameters

    value

    The date value that should be present in the UIDatePicker

    Return Value

    A matcher for a date in a UIDatePicker.

  • Matcher that verifies whether an element, that is a UIControl, is enabled.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForEnabledElement;

    Return Value

    A matcher for checking whether a UI element is an enabled UIControl.

  • Matcher that verifies whether an element, that is a UIControl, is selected.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForSelectedElement;

    Return Value

    A matcher for checking whether a UI element is a selected UIControl.

  • Matcher that verifies whether a view has its userInteractionEnabled property set to @c YES.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForUserInteractionEnabled;

    Return Value

    A matcher for checking whether a view’ userInteractionEnabled property is set to @c YES.

  • Matcher that verifies that the selected element satisfies the given constraints to the reference element. Usage: @code GREYLayoutConstraint *constraint1 = [GREYLayoutConstraint layoutConstraintWithAttribute … ]; GREYLayoutConstraint *constraint2 = [GREYLayoutConstraint layoutConstraintForDirection … ]; id *matcher = [GREYMatcher matcherForConstraints:@[ constraint1, constraint2 ] toReferenceElementMatching:aReferenceElementMatcher]; [EarlGrey selectElementWithMatcher …] assertWithMatcher:matcher]; @endcode

    @remark Constraints are often represented using floating point numbers. Floating point arithmetic can often induce errors based on the way the numbers are represented in hardware; hence, floating point comparisons use a margin value @c kGREYAcceptableFloatDifference that is used for adding accuracy to such arithmetic.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForConstraints:(nonnull NSArray *)constraints
                      toReferenceElementMatching:
                          (nonnull id<GREYMatcher>)referenceElementMatcher;

    Parameters

    constraints

    The constraints to be matched.
    referenceElementMatcher

    The reference element with the correct constraints.

    Return Value

    A matcher to verify the GREYLayoutConstraints on a UI element.

  • Matcher primarily for asserting that the element is @c nil or not found.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForNil;

    Return Value

    A matcher to check if a specified element is @c nil or not found.

  • Matcher for asserting that the element exists in the UI hierarchy (i.e. not @c nil).

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForNotNil;

    Return Value

    A matcher to check if a specified element is not @c nil.

  • Matcher for toggling the switch control.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForSwitchWithOnState:(BOOL)on;

    Parameters

    on

    The state of the switch control. The switch control is in ON state if @c on is @c YES or OFF state if @c on is NO.

    Return Value

    A matcher to check if a UISwitch is on or off.

  • A Matcher for NSNumbers that matches when the examined number is within a specified @c delta from the specified value.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForCloseTo:(double)value delta:(double)delta;

    Parameters

    value

    The expected value of the number being matched.
    delta

    The delta within which matches are allowed

    Return Value

    A matcher that checks if a number is close to a specified @c value.

  • A Matcher that matches against any object, including @c nils.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForAnything;

    Return Value

    A matcher that matches any object.

  • A Matcher that checks if a provided object is equal to the specified @c value. The equality is determined by calling the @c isEqual: method of the object being examined. In case the @c value is @c nil, then the object itself is checked to be @c nil.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForEqualTo:(nonnull id)value;

    Parameters

    value

    The value to be checked for equality. Please ensure that scalar types are passed in as boxed (object) values.

    Return Value

    A matcher that checks if an object is equal to the provided one.

  • A Matcher that checks if a provided object is less than a specified @c value. The comparison is made by calling the @c compare: method of the object being examined.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForLessThan:(nonnull id)value;

    Parameters

    value

    The value to be compared, which should return @c NSOrderedDescending. Please ensure that scalar values are passed in as boxed (object) values.

    Return Value

    A matcher that checks an object is lesser than another provided @c value.

  • A Matcher that checks if a provided object is greater than a specified @c value. The comparison is made by calling the @c compare: method of the object being examined.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForGreaterThan:(nonnull id)value;

    Parameters

    value

    The value to be compared, which should return @c NSOrderedAscending. Please ensure that scalar values are passed in as boxed (object) values.

    Return Value

    A matcher that checks an object is greater than another provided @c value.

  • Matcher that matches a UIScrollView scrolled to content @c edge.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForScrolledToContentEdge:
    (GREYContentEdge)edge;

    Parameters

    edge

    The content edge UIScrollView should be scrolled to.

    Return Value

    A matcher that matches a UIScrollView scrolled to content @c edge.

  • Matcher that matches a UITextField’s content.

    Declaration

    Objective-C

    + (nonnull id<GREYMatcher>)matcherForTextFieldValue:(nonnull NSString *)value;

    Parameters

    value

    The text string contained inside the UITextField.

    Return Value

    A matcher that matches the value inside a UITextField.