selector.md

Selector API Usage

This doc is showing how Snippet UiAutomator implement the BySelector to specify criteria for matching UI elements.

Search by Criteria

Selector supports multiple parameters for matching.

• Boolean

  checkable, checked, clickable, enabled, focusable, focused, longClickable, scrollable, selected

• Integer

  depth, displayId

Important: Not support index and instance as parameters because these search criteria are for UiSelector.

• String

  clazz, desc, descContains, descEndsWith, descStartsWith, hint, hintContains, hintEndsWith, hintStartsWith, pkg, res, text, textContains, textEndsWith, textStartsWith

• Regular Expression

  clazzMatches, descMatches, hintMatches, pkgMatches, resMatches, textMatches

Tip: BySelector uses some abbreviations to name Criteria, but Selector still supports to use their full names.

Abbreviation	Full Name
clazz	className
desc	description
pkg	packageName
res	resourceId

Example Usage

ad.ui(text='Example', enabled=True, depth=3)

Search by Kinship

Selector supports to narrow down the search scope to objects that are related to itself.

• Ancestor

  Find the ancestor directly above present Selector.

  ad.ui(...).ancestor(...)

• Child

  Find the child under present Selector.

  ad.ui(...).child(...)

  [!TIP] The child selector now supports index search, and it's recommended to pair it with depth search to pinpoint the specific child element you're looking for.

  # Find the second object directly under present Selector.
  ad.ui(...).child(depth=1, index=2)

• Parent

  Find the parent of present Selector, or null if it has no parent.

  ad.ui(...).parent

• Sibling

  Find the sibling or the child of the sibling, relative to the present Selector.

  ad.ui(...).sibling(...)

Example Usage

ad.ui(res='com.android.settings:id/settings_homepage_container')\
    .child(res='com.android.settings:id/search_bar')\
    .child(res='com.android.settings:id/search_action_bar')\
    .sibling(clazz='android.widget.ImageView').click()

Search by Relative Position

Selector supports to narrow down the search scope to the object corresponding to its own location.

• Bottom

  Find the closest object that is below present Selector.

  ad.ui(...).bottom(...)

• Left

  Find the closest object that is to the left of present Selector.

  ad.ui(...).left(...)

• Right

  Find the closest object that is to the right of present Selector.

  ad.ui(...).right(...)

• Top

  Find the closest object that is above present Selector.

  ad.ui(...).top(...)

Example Usage

ad.ui(text='Airplane mode').right(clazz='android.widget.Switch').click()