How to use Relative Selector in Shirates - Part 1 -

This article is an introduction of how to use Shirates, a mobile testing automation tool.

Selector expression

You can use selector expression for selecting an element in the screen. This is simple and powerful expression(See How to use selector expression in Shirates).

Relative selector

Once you selected an element on the screen, you might want to get another element around the element relatively. In this case, you can use Shirates's relative selector.

Relative selector(Direction based)

You can get a Widget relatively with direction right, below, left, above.

Relative selectors

relative selector	description
:right	widget in right direction
:rightInput	input in right direction
:rightLabel	label in right direction
:rightImage	image in right direction
:rightButton	button in right direction
:rightSwitch	switch in right direction
:below	widget in below direction
:belowInput	input in below direction
:belowLabel	label in below direction
:belowImage	image in below direction
:belowButton	button in below direction
:belowSwitch	switch in below direction
:left	widget in left direction
:leftInput	input in left direction
:leftLabel	label in left direction
:leftImage	image in left direction
:leftButton	button in left direction
:leftSwitch	switch in left direction
:above	widget in above direction
:aboveInput	input in above direction
:aboveLabel	label in above direction
:aboveImage	image in above direction
:aboveButton	button in above direction
:aboveSwitch	switch in above direction

Additional Widget type(input, label, image, button, switch) can be specified.

Widget

Built-in widget information is as follows.

widget	corresponding (Android)	corresponding (iOS)
label	android.widget.TextView	XCUIElementTypeStaticText
input	android.widget.EditText	XCUIElementTypeTextField XCUIElementTypeSecureTextField
image	android.widget.ImageView	XCUIElementTypeImage
button	android.widget.Button android.widget.ImageButton android.widget.CheckBox	XCUIElementTypeButton
switch	android.widget.Switch	XCUIElementTypeSwitch
widget	(all of the above)	(all of the above)

---

Selector command examples

example	description
<text1>:right	Select the first element that text is "text1", then select the first widget in right direction.
<text1>:right(2)	Select the first element that text is "text1", then select the second widget in right direction. This is equivalent to <text1>:right(pos=2) or <text1>:right([2])
<text1>:rightSwitch	Select the first element that text is "text1", then select the first switch in right direction.
<text1>:right(text2)	Select the first element that text is "text1", then select the first widget that text is "text2" in right direction.
<text1>:right:belowButton	Select the first element that text is "text1", then select the first widget in right direction, then select the 1st button in below direction.

Usage of right selector (Android)

from TextView1

Usage of right selector (iOS)

from StaticText1

Search range

Right selector searches in right direction between the top and the bottom of base element.

Material

You can get complete sample project from [https://github.com/wave1008/shirates-samples-selectors].

SelectWithDirectionTest

import org.junit.jupiter.api.Order
import org.junit.jupiter.api.Test
import shirates.core.driver.commandextension.*
import shirates.core.testcode.UITest

class SelectWithDirectionTest : UITest() {

    @Test
    @Order(10)
    fun selectWithDirection() {

        scenario {
            case(1) {
                condition {
                    it.restartApp()
                }.action {
                    it.select("<Battery>:below")
                }.expectation {
                    it.textIs("100%")
                }
            }
            case(2) {
                action {
                    it.select("<Battery>:leftImage")
                }.expectation {
                    it.classIs("android.widget.ImageView")
                }
            }
            case(3) {
                action {
                    it.select("<Battery>:above(2)")
                }.expectation {
                    it.textIs("Notifications")
                }
            }
            case(4) {
                condition {
                    it.tap("Search settings")
                }.action {
                    it.select("<@Back>:right")
                }.expectation {
                    it.classIs("android.widget.EditText")
                }
            }
        }
    }

}

Test Result

HTML-Report

Spec-Report

---

For more information

See Relative selector(Direction based)

---

Conclusion

Once you selected an element on the screen, you can get another element around the element relatively using Shirates's relative selector.

You can get a widget(input, label, image, button, switch) relatively with direction right, below, left, above.