Skip to content

Click In Element

Summary

  • Internal name: ClickInElement
  • Category: Android UI
  • Purpose: Click (or long-click) the first element matching a selector, optionally waiting for it to appear first.
  • Task type: Normal

Compatibility

  • Minimum AndroMate version: 1.1.0
  • Maximum AndroMate version: 1.1.0
  • Minimum Android: Android 13 (API 33)
  • Maximum Android tested: Android 16 (API 36)

  • Supported manufacturers:

    • Samsung (One UI 6.x / 7.x / 8.x)
    • Other manufacturers - not supported yet (Xiaomi HyperOS and Google Pixel are being adapted)
    • Required permissions:
    • ACCESSIBILITY_SERVICE

Detailed description

The Click In Element task (formerly named "Click In Text" - renamed because it matches by more than literal text) searches the accessibility tree for the first element matching a selector and clicks it. Setting ClickInElement_timeout_ms above 0 makes the task poll every 300ms until the element appears (or the timeout expires) before clicking - the same wait behavior as Wait For Element, followed by a click.

Only elements considered "clickable" by the accessibility tree are matched (a non-clickable node's clickable parent is matched instead, if any) - this mirrors how a real tap would be routed. If your target is an editable field rather than something to click, use Fill Text instead, which does not require clickability.

Input parameters

Parameter Type Required Possible values Android Compatibility AndroMate Compatibility Default
ClickInElement_textSelector Enum / String (resolvable) Yes text, contentDescription, tooltipText, resourceId, className, hintText, anyOf Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 ""
ClickInElement_CompareType Enum / String (resolvable) Yes exactText, startWith, contain Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 ""
ClickInElement_Index Integer (resolvable) No 0-based index among matches Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 0
ClickInElement_text String (resolvable) Yes The text/description/id to match against Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 ""
ClickInElement_timeout_ms Integer (resolvable) No ≥ 0 milliseconds Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 0 (no wait)
ClickInElement_clickType Enum / String (resolvable) No click, longClick Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 click

Output parameters

This task produces no output variable. It returns a VoidResult on success.

Exceptions

Code Exception Name Description
SCREEN-AUTOMATOR-ERROR-003 Invalid Action Type ClickInElement_clickType isn't click or longClick.
SCREEN-AUTOMATOR-ERROR-006 Unsupported Text Selector ClickInElement_textSelector isn't a recognized selector value.
SCREEN-AUTOMATOR-ERROR-010 Screen Automator Service Not Connected The AndroMate accessibility service isn't enabled/connected.
SCREEN-AUTOMATOR-ERROR-011 Screen Automator Action Failed No matching (clickable) element was found before the timeout expired, or the click action itself was refused - includes the resolved selector/compare/index/text/timeout in the error detail.

Execution flowchart

flowchart TD
    Start([ClickInElement]) --> CheckConnected{Accessibility service\nconnected?}
    CheckConnected -->|No| E1[SCREEN-AUTOMATOR-ERROR-010\nSERVICE_NOT_CONNECTED]
    CheckConnected -->|Yes| Loop[Search accessibility tree\nfor a clickable match]
    Loop --> Found{Match found?}
    Found -->|Yes| Click[performAction\nCLICK or LONG_CLICK]
    Found -->|No| Timeout{Elapsed ≥\ntimeout_ms?}
    Timeout -->|No| Sleep[wait 300ms] --> Loop
    Timeout -->|Yes| E2[SCREEN-AUTOMATOR-ERROR-011\nACTION_FAILED]
    Click --> Success([VoidResult])

    E1 --> Error([Exception])
    E2 --> Error

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style Click fill:#fff9c4
    style Loop fill:#f3e5f5

How it works:

  1. Check connection: fails fast with SERVICE_NOT_CONNECTED if the accessibility service isn't enabled.
  2. Search: looks for a clickable node whose selector value matches ClickInElement_text per ClickInElement_CompareType, at ClickInElement_Index among matches.
  3. Wait if needed: if not found and timeout_ms > 0, waits 300ms and searches again, until found or the timeout elapses.
  4. Act: clicks (or long-clicks) the match; if never found in time, raises ACTION_FAILED.

Code examples

Example 1 - Click a button by its text

{
  "ClickInElement": [
    {
      "id": "1",
      "title": "Click Allow",
      "ClickInElement_textSelector": "text",
      "ClickInElement_CompareType": "exactText",
      "ClickInElement_Index": 0,
      "ClickInElement_text": "Allow",
      "ClickInElement_timeout_ms": 0,
      "ClickInElement_clickType": "click"
    }
  ]
}

Example 2 - Wait up to 5s for a button, then long-click it

{
  "ClickInElement": [
    {
      "id": "2",
      "title": "Long-click Settings icon",
      "ClickInElement_textSelector": "contentDescription",
      "ClickInElement_CompareType": "contain",
      "ClickInElement_Index": 0,
      "ClickInElement_text": "Settings",
      "ClickInElement_timeout_ms": 5000,
      "ClickInElement_clickType": "longClick"
    }
  ]
}

Input parameter details

1. Input parameter: ClickInElement_textSelector

Where the matched text is read from.

Value Description
text The element's visible text.
contentDescription Its accessibility content description.
tooltipText Its tooltip text (if any).
resourceId Its full Android view ID resource name (e.g. com.app:id/button_ok).
className Its Android view class name (e.g. android.widget.Button).
hintText Its hint/placeholder text (useful for empty editable fields).
anyOf Matches if any of text, contentDescription, or tooltipText match - not resourceId/className, which describe structure rather than displayed/spoken text.

Example

"ClickInElement_textSelector": "text"

2. Input parameter: ClickInElement_CompareType

How the comparison is performed (case-insensitive).

Value Description
exactText Exact match.
startWith The element's value starts with ClickInElement_text.
contain The element's value contains ClickInElement_text.

Example

"ClickInElement_CompareType": "contain"

3. Input parameter: ClickInElement_Index

If multiple elements match, selects the n-th one (0-based). Out-of-range falls back to the first match.

Example

"ClickInElement_Index": 0

4. Input parameter: ClickInElement_text

The value to match against, per ClickInElement_textSelector/ClickInElement_CompareType.

Example

"ClickInElement_text": "Allow"

5. Input parameter: ClickInElement_timeout_ms

How long to keep searching before giving up. 0 (default) checks once, immediately.

Example

"ClickInElement_timeout_ms": 5000

6. Input parameter: ClickInElement_clickType

Whether to perform a normal click or a long-click on the matched element.

Value Description
click AccessibilityNodeInfo.ACTION_CLICK (default).
longClick AccessibilityNodeInfo.ACTION_LONG_CLICK.

Example

"ClickInElement_clickType": "longClick"

Output parameter details

This task has no output parameters.

Complete JSON example

{
  "ClickInElement": [
    {
      "id": "1",
      "title": "Click OK",
      "ClickInElement_textSelector": "text",
      "ClickInElement_CompareType": "exactText",
      "ClickInElement_Index": 0,
      "ClickInElement_text": "OK",
      "ClickInElement_timeout_ms": 3000,
      "ClickInElement_clickType": "click"
    }
  ]
}