Skip to content

Wait For Element

Summary

  • Internal name: WaitForElement
  • Category: Android UI
  • Purpose: Poll the screen until an element matching a selector appears, or time out.
  • 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 Wait For Element task repeatedly checks the accessibility tree (every 300ms) for an element matching a selector, until found or WaitForElement_timeout_ms elapses. It does not click or otherwise act on the element it finds - chain a Click In Element or Fill Text task afterward if that's needed.

Like Fill Text, the search is not limited to clickable nodes - it can wait for a loading spinner to disappear from view, a label to appear, or any node at all, not just tappable ones.

Input parameters

Parameter Type Required Possible values Android Compatibility AndroMate Compatibility Default
WaitForElement_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 ""
WaitForElement_CompareType Enum / String (resolvable) Yes exactText, startWith, contain Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 ""
WaitForElement_Index Integer (resolvable) No 0-based index among matches Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 0
WaitForElement_matchText String (resolvable) Yes The value to match against Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 ""
WaitForElement_timeout_ms Integer (resolvable) No ≥ 0 milliseconds Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 5000

Output parameters

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

Exceptions

Code Exception Name Description
SCREEN-AUTOMATOR-ERROR-006 Unsupported Text Selector WaitForElement_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 element appeared before WaitForElement_timeout_ms elapsed - includes the resolved selector/compare/index/matchText/timeout in the error detail.

Execution flowchart

flowchart TD
    Start([WaitForElement]) --> CheckConnected{Accessibility service\nconnected?}
    CheckConnected -->|No| E1[SCREEN-AUTOMATOR-ERROR-010\nSERVICE_NOT_CONNECTED]
    CheckConnected -->|Yes| Search["Search accessibility tree\n(any node)"]
    Search --> Found{Match found?}
    Found -->|Yes| Success([VoidResult])
    Found -->|No| Timeout{Elapsed ≥\ntimeout_ms?}
    Timeout -->|No| Sleep[wait 300ms] --> Search
    Timeout -->|Yes| E2[SCREEN-AUTOMATOR-ERROR-011\nACTION_FAILED]

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

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style Search fill:#f3e5f5

How it works:

  1. Check connection: fails fast with SERVICE_NOT_CONNECTED if the accessibility service isn't enabled.
  2. Poll: checks for a match against WaitForElement_matchText; if not found, waits 300ms and checks again.
  3. Resolve: returns success as soon as a match is found; raises ACTION_FAILED once timeout_ms elapses with no match.

Code examples

Example 1 - Wait for a confirmation dialog

{
  "WaitForElement": [
    {
      "id": "1",
      "title": "Wait for confirmation dialog",
      "WaitForElement_textSelector": "text",
      "WaitForElement_CompareType": "contain",
      "WaitForElement_Index": 0,
      "WaitForElement_matchText": "Confirm",
      "WaitForElement_timeout_ms": 8000
    }
  ]
}

Input parameter details

1. Input parameter: WaitForElement_textSelector

Same 7 values as Click In Element > ClickInElement_textSelector, including anyOf.

Example

"WaitForElement_textSelector": "text"

2. Input parameter: WaitForElement_CompareType

exactText, startWith, or contain (case-insensitive).

Example

"WaitForElement_CompareType": "contain"

3. Input parameter: WaitForElement_Index

If multiple elements match, selects the n-th one (0-based).

Example

"WaitForElement_Index": 0

4. Input parameter: WaitForElement_matchText

The value to match against.

Example

"WaitForElement_matchText": "Confirm"

5. Input parameter: WaitForElement_timeout_ms

Maximum time to keep polling before raising ACTION_FAILED. Default 5000.

Example

"WaitForElement_timeout_ms": 8000

Output parameter details

This task has no output parameters.

Complete JSON example

{
  "WaitForElement": [
    {
      "id": "1",
      "title": "Wait for Login button",
      "WaitForElement_textSelector": "text",
      "WaitForElement_CompareType": "exactText",
      "WaitForElement_Index": 0,
      "WaitForElement_matchText": "Login",
      "WaitForElement_timeout_ms": 10000
    }
  ]
}