Skip to content

Scroll To Element

Summary

  • Internal name: ScrollToElement
  • Category: Android UI
  • Purpose: Repeat a swipe in a direction until an element matching a selector is found, or a maximum number of attempts is exhausted.
  • 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 Scroll To Element task combines Scroll and an element search into a single loop: it checks whether the element is already visible, and if not, swipes once in ScrollToElement_direction, waits ~400ms for the UI to settle, and checks again - up to ScrollToElement_maxAttempts swipes. Like Scroll, it does not click the element once found - chain a Click In Element task afterward if that's needed. Keeping this single-responsibility split (scroll-until-found vs. click) mirrors the intentional split of the old combined ScreenAutomator task.

Input parameters

Parameter Type Required Possible values Android Compatibility AndroMate Compatibility Default
ScrollToElement_direction Enum / String (resolvable) Yes Up, Down, Left, Right Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 ""
ScrollToElement_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 ""
ScrollToElement_CompareType Enum / String (resolvable) Yes exactText, startWith, contain Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 ""
ScrollToElement_Index Integer (resolvable) No 0-based index among matches Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 0
ScrollToElement_matchText String (resolvable) Yes The value to match against Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 ""
ScrollToElement_maxAttempts Integer (resolvable) No ≥ 0 swipes Android 13 (API 33) -> Android 16 (API 36) 1.1.0 -> 1.1.0 10

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 ScrollToElement_direction isn't Up, Down, Left, or Right.
SCREEN-AUTOMATOR-ERROR-006 Unsupported Text Selector ScrollToElement_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 The element never appeared within ScrollToElement_maxAttempts swipes - includes the resolved direction/selector/compare/index/matchText/maxAttempts in the error detail.

Execution flowchart

flowchart TD
    Start([ScrollToElement]) --> CheckConnected{Accessibility service\nconnected?}
    CheckConnected -->|No| E1[SCREEN-AUTOMATOR-ERROR-010\nSERVICE_NOT_CONNECTED]
    CheckConnected -->|Yes| Check[Check for match]
    Check --> Found{Found?}
    Found -->|Yes| Success([VoidResult])
    Found -->|No| Attempts{attempt ==\nmaxAttempts?}
    Attempts -->|Yes| E2[SCREEN-AUTOMATOR-ERROR-011\nACTION_FAILED]
    Attempts -->|No| Swipe[Scroll one step\nin direction] --> Wait[wait 400ms] --> Check

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

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style Swipe fill:#fff9c4
    style Check fill:#f3e5f5

How it works:

  1. Check connection: fails fast with SERVICE_NOT_CONNECTED if the accessibility service isn't enabled.
  2. Check first: looks for a match against ScrollToElement_matchText before scrolling at all - succeeds immediately if already visible.
  3. Scroll and retry: if not found and attempts remain, swipes once in ScrollToElement_direction, waits ~400ms, and checks again.
  4. Give up: raises ACTION_FAILED once maxAttempts swipes have been made with no match.

Code examples

{
  "ScrollToElement": [
    {
      "id": "1",
      "title": "Find Terms of Service link",
      "ScrollToElement_direction": "Down",
      "ScrollToElement_textSelector": "text",
      "ScrollToElement_CompareType": "contain",
      "ScrollToElement_Index": 0,
      "ScrollToElement_matchText": "Terms of Service",
      "ScrollToElement_maxAttempts": 15
    }
  ]
}

Input parameter details

1. Input parameter: ScrollToElement_direction

Same values as Scroll > Scroll_direction: Up, Down, Left, Right.

Example

"ScrollToElement_direction": "Down"

2. Input parameter: ScrollToElement_textSelector

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

Example

"ScrollToElement_textSelector": "text"

3. Input parameter: ScrollToElement_CompareType

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

Example

"ScrollToElement_CompareType": "contain"

4. Input parameter: ScrollToElement_Index

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

Example

"ScrollToElement_Index": 0

5. Input parameter: ScrollToElement_matchText

The value to match against.

Example

"ScrollToElement_matchText": "Terms of Service"

6. Input parameter: ScrollToElement_maxAttempts

Maximum number of scroll swipes to attempt before raising ACTION_FAILED. Default 10.

Example

"ScrollToElement_maxAttempts": 15

Output parameter details

This task has no output parameters.

Complete JSON example

{
  "ScrollToElement": [
    {
      "id": "1",
      "title": "Scroll to Submit button",
      "ScrollToElement_direction": "Down",
      "ScrollToElement_textSelector": "text",
      "ScrollToElement_CompareType": "exactText",
      "ScrollToElement_Index": 0,
      "ScrollToElement_matchText": "Submit",
      "ScrollToElement_maxAttempts": 10
    }
  ]
}