Selectors & Nodes

Overview

This chapter covers selector usage and the node info class.

Selector Objects

Selector objects support cascading selection. When an element cannot be selected directly, select a parent first, then a child.
Selectors partially support regex matching. See Java regex syntax in this tutorial.

XPath Selection

XPath selector; see : https://www.jianshu.com/p/c205334122b3 and https://www.runoob.com/xpath/xpath-syntax.html
Use the IDE node panel to inspect xpath attributes and test xpath
Requires EC 10.12.0+
@param value e.g. //node[@text=‘Sample’] selects nodes with that text

1
function main() {
2
    // Get selector object
3
    var selector = xpath("//node[@clz='android.widget.TextView']");
4
    let n = selector.getNodeInfo(1000);
5
    logd(JSON.stringify(n))
6
}
7

8
main();

text Attribute Selection

Full Text Match

1
function main() {
2
    // Get selector object
3
    var selector = text("Settings");
4
    click(selector);
5
}
6

7
main();

Regex Match

1
function main() {
2
    // Get selector object
3
    var selector = textMatch(".*Settings.*");
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

id Attribute Selection

Full Match

1
function main() {
2
    // Get selector object
3
    var selector = id("com.xx:id/a1");
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

Regex Match

1
function main() {
2
    // Get selector object
3
    var selector = idMatch(".*id8.*");
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

clz Attribute Selection

Full Match

1
function main() {
2
    // Get selector object
3
    var selector = clz("android.widget.TextView");
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

Regex Match

1
function main() {
2
    // Get selector object
3
    var selector = clzMatch(".*TextView.*");
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

pkg Attribute Selection

Full Match

1
function main() {
2
    // Get selector object
3
    var selector = pkg("com.xx");
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

Regex Match

1
function main() {
2
    // Get selector object
3
    var selector = pkgMatch(".*tencent.*");
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

desc Text Attribute Selection

Full Match

1
function main() {
2
    // Get selector object
3
    var selector = desc("My description");
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

Regex Match

1
function main() {
2
    // Get selector object
3
    var selector = descMatch(".*Description.*");
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main()

Depth and Drawing Order Matching

drawingOrder

1
function main() {
2
    // Get selector object
3
    var selector = drawingOrder(1);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

depth

1
function main() {
2
    // Get selector object
3
    var selector = depth(1);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

other Matching Rules

visible Visible Attribute Match

Match on visible attribute
@param value string
@return {Selector} node selector

1
function main() {
2
    var node = visible(true).getOneNodeInfo(1000);
3
    logd("node " + node);
4
}
5

6
main();

bounds Bounds Match

Match on bounds region
@param left Left bound
@param top Top bound
@param right Right bound
@param bottom Bottom bound
@return {Selector} node selector

1
function main() {
2
    // Get selector object controls within bounds 0–800
3
    var selector = bounds(0, 0, 800, 800);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

checkable

1
function main() {
2
    // Get selector object
3
    var selector = checkable(true);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

checked

1
function main() {
2
    // Get selector object
3
    var selector = checked(true);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

clickable

1
function main() {
2
    // Get selector object
3
    var selector = clickable(true);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

longClickable

1
function main() {
2
    // Get selector object
3
    var selector = longClickable(true);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

scrollable

1
function main() {
2
    // Get selector object
3
    var selector = scrollable(true);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

focusable

1
function main() {
2
    // Get selector object
3
    var selector = focusable(true);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

enabled

1
function main() {
2
    // Get selector object
3
    var selector = enabled(true);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

focused

1
function main() {
2
    // Get selector object
3
    var selector = focused(true);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

selected

1
function main() {
2
    // Get selector object
3
    var selector = selected(true);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

index

1
function main() {
2
    // Get selector object
3
    var selector = index(1);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

childCount

1
function main() {
2
    // Get selector object
3
    var selector = childCount(1);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

row

1
function main() {
2
    // Get selector object
3
    var selector = row(1);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

column

1
function main() {
2
    // Get selector object
3
    var selector = column(1);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

rowSpan

1
function main() {
2
    // Get selector object
3
    var selector = rowSpan(1);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

columnSpan

1
function main() {
2
    // Get selector object
3
    var selector = columnSpan(1);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

rowCount

1
function main() {
2
    // Get selector object
3
    var selector = rowCount(1);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

columnCount

1
function main() {
2
    // Get selector object
3
    var selector = columnCount(1);
4
    var result = click(selector);
5
    if (result) {
6
        toast("Click succeeded");
7
    } else {
8
        toast("Click failed");
9
    }
10
}
11

12
main();

Cascading Matching

1
function main() {
2
    // Get selector object
3
    // Select children under ScrollView parentclz=android.widget.CheckBox all nodes
4
    var selector = clz("android.widget.ScrollView")
5
        .child()
6
        .clz("android.widget.CheckBox");
7
    var result = click(selector);
8
    if (result) {
9
        toast("Click succeeded");
10
    } else {
11
        toast("Click failed");
12
    }
13
}
14

15
main();

Multi-attribute Matching

1
function main() {
2
    // Get selector object,
3
    // Select CheckBox elements containing "Selector" with checked=true
4
    var selector = textMatch(".*Selector.*")
5
        .checked(true)
6
        .clz("android.widget.CheckBox");
7
    var result = click(selector);
8
    if (result) {
9
        toast("Click succeeded");
10
    } else {
11
        toast("Click failed");
12
    }
13
}
14

15
main();

Node Info Class

Overview

NodeInfo objects are returned as arrays from getNodeInfo; node fields include:

id: string — resource ID
clz: string — view class name, e.g. android.widget.TextView
pkg: string — package name, e.g. com.xx
desc: string — content description
text: string — text content
checkable: Boolean — whether checkable
checked: Boolean — whether checked
clickable: Boolean — whether clickable
enabled: Boolean — whether enabled
focusable: Boolean — whether focusable
focused: Boolean — whether focused
longClickable: Boolean — whether long-clickable
scrollable: Boolean — whether scrollable
selected: Boolean — whether selected
childCount: int — number of child nodes
index: int — node index
depth: int — node depth
drawingOrder: int — drawing order
bounds: Rect — bounds object
top: int — top position
bottom: int — bottom position
left: int — left position
right: int — right position
visibleBounds: Rect — visible bounds object
top: int — top position
bottom: int — bottom position
left: int — left position
right: int — right position

Get one node with selector getOneNodeInfo

Get the first node via selector
@param timeout Wait time in ms; 0 = no wait
@return {NodeInfo} object or null

1
function main() {
2
    // Get selector object
3
    // Select all CheckBox nodes: clz=android.widget.CheckBox
4
    var node = clz("android.widget.CheckBox").getOneNodeInfo(10000);
5

6
    if (node) {
7
        var x = node.click();
8
        logd(x);
9
    } else {
10
        toast("No node");
11
    }
12
}
13

14
main();

Get multiple nodes with selector getNodeInfo

Get node information
@param timeout Wait time in ms; 0 = no wait
@return {array} Collection of NodeInfo nodes

1
function main() {
2
    // Get selector object
3
    // Select all CheckBox nodes: clz=android.widget.CheckBox
4
    var node = clz("android.widget.CheckBox").getNodeInfo(10000);
5
    // This is an array
6
    for (let i = 0; i < node.length; i++) {
7
        logd(JSON.stringify(node[i]))
8
    }
9
}
10

11
main();

Cascade get one child node getOneNodeInfo

Get the first node via selector
@param timeout Wait time in ms; 0 = no wait
@return {NodeInfo} object or null

1
function main() {
2
    // Get selector object
3
    // Select all ViewGroup nodes: clz=android.widget.ViewGroup
4
    var node = clz("android.widget.ViewGroup").getOneNodeInfo(10000);
5
    if (node) {
6
        // Get child nodes
7
        node = node.getOneNodeInfo(text("Ad"), 10000);
8
        if (!node) {
9
            toast("No child nodes");
10
            return;
11
        }
12
        var x = node.click();
13
        logd(x);
14
    } else {
15
        toast("No node");
16
    }
17
}
18

19
main();

Cascade get multiple child nodes getNodeInfo

Get node information
@param timeout Wait time in ms; 0 = no wait
@return {array} Collection of NodeInfo nodes

1
function main() {
2
    // Get selector object
3
    // Select all ViewGroup nodes: clz=android.widget.ViewGroup
4
    var node = clz("android.widget.ViewGroup").getNodeInfo(10000);
5
    if (node) {
6
        // Get child nodes
7
        node = node.getNodeInfo(text("Ad").clz("android.widget.TextView"), 10000);
8
        if (!node) {
9
            toast("No child nodes");
10
            return;
11
        }
12
        var x = node.click();
13
        logd(x);
14
    } else {
15
        toast("No node");
16
    }
17
}
18

19
main();

Get parent node

Parent node of this node
@return {NodeInfo} object or null

1
function main() {
2
    // Get selector object
3
    // Select all CheckBox nodes: clz=android.widget.CheckBox
4
    var node = clz("android.widget.CheckBox").getOneNodeInfo(10000);
5
    if (node) {
6
        var x = node.parent();
7
        logd(x);
8
    } else {
9
        toast("No node");
10
    }
11
}
12

13
main();

Get child node

Get a single child node
@param index child node index
@return {NodeInfo} object or null

1
function main() {
2
    // Select all ViewGroup nodes: clz=android.widget.ViewGroup
3
    var node = clz("android.widget.ViewGroup").getOneNodeInfo(10000);
4
    if (node) {
5
        var x = node.child(0);
6
        logd(x);
7
    } else {
8
        toast("No node");
9
    }
10
}
11

12
main();

Get all child nodes

Get all child nodes
@return {NodeInfo} node collection

1
function main() {
2
    // Select all ViewGroup nodes: clz=android.widget.ViewGroup
3
    var node = clz("android.widget.ViewGroup").getOneNodeInfo(10000);
4
    if (node) {
5
        var x = node.allChildren();
6
        // This is an array
7
        for (let i = 0; i < x.length; i++) {
8
            logd(x[i])
9
        }
10
    } else {
11
        toast("No node");
12
    }
13
}
14

15
main();

All sibling nodes

All sibling nodes of the current node
@return {NodeInfo} node collection

1
function main() {
2
    // Select all ViewGroup nodes: clz=android.widget.ViewGroup
3
    var node = clz("android.widget.ViewGroup").getOneNodeInfo(10000);
4
    if (node) {
5
        var x = node.siblings();
6
        // This is an array
7
        for (let i = 0; i < x.length; i++) {
8
            logd(x[i])
9
        }
10
    } else {
11
        toast("No node");
12
    }
13
}
14

15
main();

Previous sibling nodes previousSiblings

Sibling nodes before the current node
@return {NodeInfo} node collection

1
function main() {
2
    // Select all ViewGroup nodes: clz=android.widget.ViewGroup
3
    var node = clz("android.widget.ViewGroup").getOneNodeInfo(10000);
4
    if (node != null) {
5
        let x = node.previousSiblings();
6
        // This is an array
7
        for (let i = 0; i < x.length; i++) {
8
            logd(x[i])
9
        }
10
    } else {
11
        toast("No node");
12
    }
13
}
14

15
main();

Next sibling nodes nextSiblings

Sibling nodes after the current node
@return {NodeInfo} node collection

1
function main() {
2
    // Select all ViewGroup nodes: clz=android.widget.ViewGroup
3
    var node = clz("android.widget.ViewGroup").getOneNodeInfo(10000);
4
    if (node) {
5
        let x = node.nextSiblings();
6
        // This is an array
7
        for (let i = 0; i < x.length; i++) {
8
            logd(x[i])
9
        }
10
    } else {
11
        toast("No node");
12
    }
13
}
14

15
main();

Random click in node region

Requires accessibility 7.0+ or gestures via agent service
Click node
@return bool; true on success, false on failure

1
function main() {
2
    // Get selector object
3
    // Select all CheckBox nodes: clz=android.widget.CheckBox
4
    var node = clz("android.widget.CheckBox").getOneNodeInfo(10000);
5
    if (node) {
6
        node.click()
7
    } else {
8
        toast("No node");
9
    }
10
}
11

12
main();

Pointerless click clickEx

Requires accessibility 5.0+ or gestures via agent service
Pointerless click on selector; node must be clickable
@param selectors Selector object
@return {boolean}

1
function main() {
2
    var node = text("Sample text").getOneNodeInfo(10000);
3
    var result = node.clickEx();
4
    if (result) {
5
        toast("Click succeeded");
6
    } else {
7
        toast("Click failed");
8
    }
9
}
10

11
main();

Pointerless long click longClickEx

Requires accessibility 5.0+ or gestures via agent service
Pointerless long click on selector; node must be clickable
@param selectors Selector object
@return {boolean}

1
function main() {
2
    var node = text("Sample text").getOneNodeInfo(10000);
3
    var result = node.longClickEx();
4
    if (result) {
5
        toast("Click succeeded");
6
    } else {
7
        toast("Click failed");
8
    }
9
}
10

11
main();

Click node center

Requires accessibility 7.0+ or gestures via agent service
Click node center point
@return bool; true on success, false on failure

1
function main() {
2
    // Get selector object
3
    // Select all CheckBox nodes: clz=android.widget.CheckBox
4
    var node = clz("android.widget.CheckBox").getOneNodeInfo(10000);
5
    if (node) {
6
        node.clickCenter();
7
    } else {
8
        toast("No node");
9
    }
10
}
11

12
main();

Long click node

Requires accessibility 7.0+ or gestures via agent service
Long click node
@return bool; true on success, false on failure

1
function main() {
2
    // Get selector object
3
    // Select all CheckBox nodes: clz=android.widget.CheckBox
4
    var node = clz("android.widget.CheckBox").getOneNodeInfo(10000);
5
    if (node) {
6
        node.longClick()
7
    } else {
8
        toast("No node");
9
    }
10
}
11

12
main();

Node input inputText

Requires accessibility 5.0+ or gestures via agent service
Input data on a node
@param content content to enter
@return bool; true on success, false on failure

1
function main() {
2
    // Get selector object
3
    // Select all EditText nodes: clz=android.widget.EditText
4
    var node = clz("android.widget.EditText").getOneNodeInfo(10000);
5
    if (node) {
6
        node.inputText("content")
7
    } else {
8
        toast("No node");
9
    }
10
}
11

12
main();

Node IME input imeInputText

Requires accessibility 5.0+ or gestures via agent service
IME input on a node; requires this app’s IME as default
@param content content to enter
@return bool; true on success, false on failure

1
function main() {
2
    // Get selector object
3
    // Select all EditText nodes: clz=android.widget.EditText
4
    var node = clz("android.widget.EditText").getOneNodeInfo(10000);
5
    if (node) {
6
        node.imeInputText("content")
7
    } else {
8
        toast("No node");
9
    }
10
}
11

12
main();

imeInputKeyCode

IME input; requires this app’s IME as default
For scenarios without nodes, e.g. games
@param selectors Selector; may be empty if input field is focused
@param content See KeyEvent.KEYCODE_* values, e.g. 66 = enter, 67 = del, 84 = SEARCH
@return {boolean}

1
function main() {
2
    var result = clz("android.widget.EditText").getOneNodeInfo(10000);
3
    if (result) {
4
        result.imeInputKeyCode(66);
5
        toast("Yes");
6
    } else {
7
        toast("No");
8
    }
9
}
10

11
main();

Clear node text

Requires accessibility 5.0+ or gestures via agent service
Clear node text

1
function main() {
2
    // Get selector object
3
    // Select all EditText nodes: clz=android.widget.EditText
4
    var node = clz("android.widget.EditText").getOneNodeInfo(10000);
5
    if (node) {
6
        var r = node.clearText();
7
        logd("r -=" + r);
8
    } else {
9
        toast("No node");
10
    }
11
}
12

13
main();

Refresh node

This method refreshes the node cache

1
function main() {
2
    // Get selector object
3
    // Select all EditText nodes: clz=android.widget.EditText
4
    var node = clz("android.widget.EditText").getOneNodeInfo(10000);
5
    if (node) {
6
        node.refresh();
7
    } else {
8
        toast("No node");
9
    }
10
}
11

12
main();

Check node valid

Whether node info is valid @return bool|Boolean true if present

1
function main() {
2
    // Get selector object
3
    // Select all EditText nodes: clz=android.widget.EditText
4
    var node = clz("android.widget.EditText").getOneNodeInfo(10000);
5
    if (node) {
6
        var x = node.isValid();
7
        toast("Node valid:" + x);
8
    } else {
9
        toast("No node");
10
    }
11
}
12

13
main();

Scroll forward scrollForward

Requires accessibility 5.0+ or gestures via agent service
Scroll forward
@param selectors Selector object
@return {boolean}

1
function main() {
2
    var node = scrollable(true).getOneNodeInfo(10000);
3
    var result = node.scrollForward();
4
    if (result) {
5
        toast("Scroll succeeded");
6
    } else {
7
        toast("Scroll failed");
8
    }
9
}
10

11
main();

Scroll backward scrollBackward

Requires accessibility 5.0+ or gestures via agent service
Scroll backward
@param selectors Selector object
@return {boolean}

1
function main() {
2
    var node = scrollable(true).getOneNodeInfo(10000);
3
    var result = node.scrollBackward();
4
    if (result) {
5
        toast("Scroll succeeded");
6
    } else {
7
        toast("Scroll failed");
8
    }
9
}
10

11
main();