Inherits from SLUIAElement : NSObject
Declared in SLElement.h

Overview

Instances of SLElement allow you to access and manipulate user interface elements that match criteria such as having certain accessible values or being of a particular type of control.

These criteria are specified when SLElement is constructed, in the form of a predicate. When SLElement needs to access its corresponding interface element, it evaluates the element hierarchy using that predicate. If a matching object is found, it is made available to Subliminal and to UIAutomation to access and manipulate.

The methods in the SLElement (DebugSettings) category may be useful in debugging Subliminal.

The methods in the SLElement (Subclassing) category are to be called or overridden by subclasses of SLElement. Tests should not call these methods.

Tasks

Matching Interface Elements

Gestures and Actions

Logging Element Information

Debugging Subliminal

  •   shouldDoubleCheckValidity

    Determines whether the specified element should use UIAutomation to confirm that it is valid after Subliminal has determined (to the best of its ability) that it is valid.

         property

Methods for Subclasses

Properties

shouldDoubleCheckValidity

Determines whether the specified element should use UIAutomation to confirm that it is valid after Subliminal has determined (to the best of its ability) that it is valid.

@property (nonatomic) BOOL shouldDoubleCheckValidity

Discussion

If Subliminal misidentifies an element to UIAutomation, UIAutomation will not necessarily raise an exception but instead may silently fail (e.g. it may return null from APIs like UIAElement.hitpoint(), causing Subliminal to think that an element isn’t tappable when really it’s not valid). Enabling this setting may help in diagnosing such failures.

Validity double-checking is disabled (NO) by default, because it is more likely that there is a bug in a particular test than a bug in Subliminal, and because enabling double-checking will negatively affect the performance of the tests.

Declared In

SLElement.h

Class Methods

anyElement

Creates and returns an element that matches any object in the accessibility hierarchy.

+ (instancetype)anyElement

Return Value

A newly created element that matches any object in the accessibility hierarchy.

Discussion

SLElement defines this constructor primarily for the benefit of subclasses that match a certain kind of object by default, such that a match is likely unique even without the developer specifying additional information. For instance, if your application only has one webview onscreen at a time, you could match that webview (using SLWebView) by matching “any” webview, without having to give that webview an accessibility label or identifier.

Declared In

SLElement.h

elementMatching:withDescription:

Creates and returns an element that evaluates the accessibility hierarchy using a specified block object.

+ (instancetype)elementMatching:(BOOL ( ^ ) ( NSObject *obj ))predicate withDescription:(NSString *)description

Parameters

predicate

The block used to evaluate objects within the accessibility hierarchy. The block will be evaluated on the main thread. The block should return YES if the element matches the object, otherwise NO.

description

An optional description of the element, for use in debugging. (The other SLElement constructors derive element descriptions from their arguments.)

Return Value

A newly created element that evaluates objects using predicate.

Discussion

This method allows you to apply some knowledge of the target object’s identity and/or its location in the accessibility hierarchy, where the target object’s accessibility information is not sufficient to distinguish the object.

Consider using one of the more specialized constructors before this method. It is best to identify an object using information like its accessibility label, value, and/or traits, because that information also helps users with disabilities use your application. Even when that information is not sufficient to distinguish a target object, it may be easier for your application to set a unique accessibility identifier on a target object than for your tests to define a complex predicate.

To describe the element’s location in the accessibility hierarchy, see the methods in NSObject (SLAccessibilityHierarchy).

See Also

Declared In

SLElement.h

elementWithAccessibilityIdentifier:

Creates and returns an element that matches objects in the accessibility hierarchy with the specified accessibility identifier.

+ (instancetype)elementWithAccessibilityIdentifier:(NSString *)identifier

Parameters

identifier

A string that uniquely identifies a matching object.

Return Value

A newly created element that matches objects in the accessibility hierarchy with the specified accessibility identifier.

Discussion

It is best to identify an object using information like its accessibility label, value, and/or traits, because that information also helps users with disabilities use your application. However, when that information is not sufficient to identify an object, an accessibility identifier may be set by the application. Unlike accessibility labels, identifiers are not visible to users of assistive applications.

Declared In

SLElement.h

elementWithAccessibilityLabel:

Creates and returns an element that matches objects in the accessibility hierarchy with the specified accessibility label.

+ (instancetype)elementWithAccessibilityLabel:(NSString *)label

Parameters

label

A label that identifies a matching object.

Return Value

A newly created element that matches objects in the accessibility hierarchy with the specified accessibility label.

Discussion

An accessibility label is the preferred way to identify an element to Subliminal, because accessibility labels are visible to users of assistive applications. See the UIAccessibility Protocol Reference for guidance in determining appropriate labels.

Declared In

SLElement.h

elementWithAccessibilityLabel:value:traits:

Creates and returns an element that matches objects in the accessibility hierarchy with the specified accessibility label, value, and/or traits.

+ (instancetype)elementWithAccessibilityLabel:(NSString *)label value:(NSString *)value traits:(UIAccessibilityTraits)traits

Parameters

label

A label that identifies a matching object. If this is nil, the element does not restrict matches by label.

value

The value of a matching object. If this is nil, the element does not restrict matches by value.

traits

The combination of accessibility traits that characterize a matching object. If this is SLUIAccessibilityTraitAny, the element does not restrict matches by trait.

Discussion

See the UIAccessibility Protocol Reference for guidance in determining appropriate accessibility labels, values, and traits.

Declared In

SLElement.h

Instance Methods

examineMatchingObject:

Allows the caller to interact with the actual object matched by the specified SLElement.

- (void)examineMatchingObject:(void ( ^ ) ( NSObject *object ))block

Parameters

block

A block which takes the matching object as an argument and returns void.

Discussion

The block will be executed synchronously on the main thread.

This method should be used only when UIAutomation offers no API providing equivalent functionality: as a user interface element, the object should be manipulated by the simulated user for the tests to be most accurate.

Exceptions

SLUIAElementInvalidException

Raised if the element has not matched an object by the end of the default timeout.

Declared In

SLUIAElement+Subclassing.h

logElement

Logs information about the specified element.

- (void)logElement

Discussion

SLElement overrides this method to describe the application object corresponding to the specified element, which allows SLElement to provide additional information beyond that logged by the superclass' implementation.

Exceptions

SLUIAElementInvalidException

Raised if the element is not valid by the end of the default timeout.

Declared In

SLElement.h

matchesObject:

Determines if the specified element matches the specified object.

- (BOOL)matchesObject:(NSObject *)object

Parameters

object

The object to which the instance of SLElement should be compared.

Return Value

YES if the specified element matches object, NO otherwise.

Discussion

Subclasses of SLElement can override this method to provide custom matching behavior. The default implementation evaluates the object against the predicate with which the element was constructed (i.e. the argument to elementMatching:withDescription:, or a predicate derived from the arguments to a higher-level constructor).

If you override this method, you must call super in your implementation.

Declared In

SLUIAElement+Subclassing.h

tapAtActivationPoint

Taps the specified element at its activation point.

- (void)tapAtActivationPoint

Discussion

The activation point is by default the midpoint of the accessibility element’s frame (-rect), but the activation point may be modified to direct VoiceOver to tap at a different point. See -[NSObject (UIAccessibility) accessibilityActivationPoint] for more information and examples.

This method is most useful when running against SDKs older than iOS 7, because on those platforms, -hitpoint and thus -tap ignore the value of the element’s accessibility activation point. On or above iOS 7, -hitpoint respects the value of the accessibility activation point and so -tap and this method are equivalent.

Declared In

SLElement.h