DEV Community: wave1008

shirates-core 2.3.1 released

wave1008 — Tue, 28 Feb 2023 17:05:15 +0000

Shirates (shirates-core)

Shirates is an Integration Testing Framework that makes it easy and fun to write test code for mobile apps.
shirates-core is core library.

shirates-core 2.3.1

Quality Improvement

Stability improvement on launching app
Resetting SpringBoard automatically (iOS)
Rebooging Android Emulator automatically (Android)

New Properties

enableWarnOnRetryError
enableGetSourceLog

New Config

waitSecondsForLaunchAppComplete

New Feature

Test Report Index(Irregular section, WARN column)

Obsolete

swipeOffsetY

shirates-core 2.0.0 released

wave1008 — Mon, 19 Dec 2022 16:26:44 +0000

Shirates (shirates-core)

Shirates is an integration testing framework that makes it easy and fun to write test code for mobile apps.
shirates-core is core library.

shirates-core 2.0.0

Now you can set up devices with profile naming convention.
This is very easy and useful.

New Feature

Automatic device detection

shirates-core 1.2.0 released

wave1008 — Thu, 10 Nov 2022 15:36:54 +0000

Shirates (shirates-core)

Shirates is an integration testing framework that makes it easy and fun to write test code for mobile apps.
shirates-core is core library.

shirates-core 1.2.0

New Feature

Introduced new parameter "enableImageAssertion"

Bug Fix

Spec-Report logging (tapAppIcon, target, SKIP_SCENARIO, SKIP_CASE, stub, stubNot, dataPattern)
Summary-Report logging (os colum)

shirates-core 1.1.1 released

wave1008 — Fri, 21 Oct 2022 21:03:09 +0000

Shirates (shirates-core)

Shirates is an integration testing framework that makes it easy and fun to write test code for mobile apps.
shirates-core is core library.

shirates-core 1.1.1

Update environments
Fix Unit tests
Introduced new parameter "appiumProxyReadTimeoutSeconds"
Update doc & tutorial

How to use Relative Selector in Shirates - Part 3 -

wave1008 — Thu, 20 Oct 2022 21:50:40 +0000

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(XML based)

You can get an element relatively along with hierarichical structure of XML.

Relative selectors

relative selector	description
:parent	parent element
:child	child element
:sibling	sibling element
:ancestor	ancestor element
:descendant	descendant element
:next	next element
:previous	previous element
:nextLabel	next label element
:preLabel	previous label element
:nextInput	next input element
:preInput	previous input element
:nextImage	next image element
:preImage	previous image element
:nextButton	next button element
:preButton	previous button element
:nextSwitch	next switch element
:preSwitch	previous switch element

Relative selector examples

example	description
`<.class1>:child(1)`	Select the first element that type is class1, then select the first child.
`<#id1>:next`	Select the first element that resource-id is "id1", then select next element.
`<text1>:previous`	Select the first element that text is "text1", then select previous element.
`<@access1>:next:next`	Select the first element that accessibility(content-desc or name) is "access1", then select next element, then select next element.
`<@access1>:next(2)`	This is equivalent to `<@access1>:next:next`
`<text1>:next(.class1)`	Select the first element that text is "text1", then select next element that class is "class1"
`<text1>:nextInput`	Select the first element that text is "text1", then select next input element.

Material

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

SelectWithXmlTest

import org.junit.jupiter.api.Order
import org.junit.jupiter.api.Test
import shirates.core.driver.commandextension.classIs
import shirates.core.driver.commandextension.restartApp
import shirates.core.driver.commandextension.select
import shirates.core.testcode.UITest

class SelectWithXmlTest : UITest() {

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

        scenario {
            case(1) {
                condition {
                    it.restartApp()
                }.expectation {
                    it.select("Network & internet") {
                        select(":next").classIs("android.widget.TextView")
                        select(":next(2)").classIs("android.widget.LinearLayout")
                        select(":next(3)").classIs("android.widget.LinearLayout")
                        select(":next(4)").classIs("android.widget.ImageView")
                        select(":next(5)").classIs("android.widget.RelativeLayout")
                        select(":next(6)").classIs("android.widget.TextView")
                        select(":next(7)").classIs("android.widget.TextView")
                    }
                }
            }
        }
    }

}

For more information

See Relative selector(XML 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 an element relatively along with hierarichical　structure of XML.

How to use Relative Selector in Shirates - Part 2 -

wave1008 — Wed, 19 Oct 2022 13:10:55 +0000

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(Widget flow based)

You can get a widget relatively along with widget flow.

Widget flow algorithm

Widget flow algorithm groups widgets with vertical position (1st group - 6th group), then searches widgets in each groups from left to right, then up to down.

In the 1st group, widget flow order is (0),(1),(2).
In the 2nd group, widget flow order is (3),(4),(5),(6),(7).
In the 3nd group, widget flow order is (8),(9).
In the 4th group, widget flow order is (10),(11).
In the 5th group, widget flow order is (12).
In the 6th group, widget flow order is (13).

Grouping patterns

Relative selectors (Widget flow based)

relative selector	alias	description
:flow	-	widget in widget flow
:flowLabel	:label	label in widget flow
:flowInput	:input	input in widget flow
:flowImage	:image	image in widget flow
:flowButton	:button	button in widget flow
:flowSwitch	:switch	switch in widget flow
:innerFlow	:inner	widget in widget flow inside of the container
:innerLabel	-	label in widget flow inside of the container
:innerInput	-	input in widget flow inside of the container
:innerImage	-	image in widget flow inside of the container
:innerButton	-	button in widget flow inside of the container
:innerSwitch	-	switch in widget flow inside of the container
:vflow	-	widget in vertical widget flow
:innerVflow	:innerV	widget in vertical widget flow inside of the container
:innerVlabel	-	label in vertical widget flow inside of the container
:innerVinput	-	input in vertical widget flow inside of the container
:innerVimage	-	image in vertical widget flow inside of the container
:innerVbutton	-	button in vertical widget flow inside of the container
:innerVswitch	-	switch in vertical widget flow inside of the container

Relative selector examples

example	description
`<text1>:input`	Select the first element that text is "text1", then select the first input in widget flow.
`<.Class1>:flow(2)`	Select the first element that type is Class1, then select the second widget in widget flow.

Material

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

SelectWithWidgetFlowTest

import org.junit.jupiter.api.Order
import org.junit.jupiter.api.Test
import shirates.core.driver.commandextension.classIs
import shirates.core.driver.commandextension.restartApp
import shirates.core.driver.commandextension.select
import shirates.core.driver.commandextension.textIs
import shirates.core.testcode.UITest

class SelectWithWidgetFlowTest : UITest() {

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

        scenario {
            case(1) {
                condition {
                    it.restartApp()
                }.expectation {
                    it.select("<Settings>:flow")
                        .classIs("android.widget.ImageButton")
                    it.select("<Settings>:flow(2)")
                        .textIs("Search settings")
                    it.select("<Settings>:flow(3)")
                        .classIs("android.widget.ImageView")
                    it.select("<Settings>:flow(4)")
                        .textIs("Network & internet")
                    it.select("<Settings>:flow(5)")
                        .textIs("Mobile, Wi‑Fi, hotspot")
                }
            }
            case(2) {
                expectation {
                    it.select("<Settings>") {
                        // Select relatively from <Settings>
                        select(":flow").classIs("android.widget.ImageButton")
                        select(":flow(2)").textIs("Search settings")
                        select(":flow(3)").classIs("android.widget.ImageView")
                        select(":flow(4)").textIs("Network & internet")
                        select(":flow(5)").textIs("Mobile, Wi‑Fi, hotspot")
                    }
                }
            }
        }
    }

    @Test
    @Order(20)
    fun selectWithWidgetFlow2() {

        scenario {
            case(1) {
                condition {
                    it.restartApp()
                }.expectation {
                    it.select("<Settings>") {
                        // Select relatively from <Settings>
                        select(":label").textIs("Search settings")
                        select(":label(2)").textIs("Network & internet")
                        select(":label(3)").textIs("Mobile, Wi‑Fi, hotspot")
                    }
                }
            }
            case(2) {
                expectation {
                    it.select("<Network & internet>") {
                        // Select relatively from <Network & internet>
                        select(":image").classIs("android.widget.ImageView")
                        select(":label").textIs("Mobile, Wi‑Fi, hotspot")
                    }
                }
            }
        }
    }

}

selectWithWidgetFlow/case(1),case(2)

selectWithWidgetFlow2/case(1)

selectWithWidgetFlow2/case(2)

Test Result

HTML-Report

For more information

See Relative selector(Widget flow 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 along with widget flow.

How to use Relative Selector in Shirates - Part 1 -

wave1008 — Tue, 18 Oct 2022 16:05:25 +0000

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.

Demonstration Sample Project "Practice1" (Movie)

wave1008 — Mon, 17 Oct 2022 17:32:45 +0000

Shirates (shirates-core)

Shirates is an integration testing framework that makes it easy and fun to write test code for mobile apps.
shirates-core is core library.

Demonstraion

This is a demonstration movie for the article Introducing Shirates, a Mobile Testing Automation Tool.

shirates-core 1.1.0 released

wave1008 — Mon, 17 Oct 2022 14:07:59 +0000

Shirates (shirates-core)

Shirates is an integration testing framework that makes it easy and fun to write test code for mobile apps.
shirates-core is core library.

shirates-core 1.1.0

New functions

How to use Screen Nickname in Shirates - Part2 -

wave1008 — Sun, 16 Oct 2022 14:12:24 +0000

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

Material

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

Example 2: Android Settings

This sample shows how to use screen nickname using four screens in Android Settings app.

Settings Screen

System Screen/Language & input Screen/Languages Screen

[Android Settings Top Screen].json

{
  "key": "[Android Settings Top Screen]",

  "identity": "#recycler_view",
  "satellites": ["Battery", "Accessibility", "Passwords & accounts", "Tips & support"],

  "selectors": {
    "[Account Avatar]": "#account_avatar",
    "[Settings]": "#homepage_title",

    "[Search Button]": "<#search_action_bar>:inner(1)",
    "[Search settings]": "#search_action_bar_title",

    "[Network & internet]": "",
    "{Network & internet}": "[Network & internet]:label",
    "[Network & internet Icon]": "[Network & internet]:leftImage",

    "[Connected devices]": "",
    "{Connected devices}": "[Connected devices]:label",
    "[Connected devices Icon]": "[Connected devices]:leftImage",

    "[Apps]": "",
    "{Apps}": "[Apps]:label",
    "[Apps Icon]": "[Apps]:leftImage",

    "[Notifications]": "",
    "{Notifications}": "[Notifications]:label",
    "[Notifications Icon]": "[Notifications]:leftImage",

    "[Battery]": "",
    "{Battery}": "[Battery]:label",
    "[Battery Icon]": "[Battery]:leftImage",

    "[Storage]": "",
    "{Storage}": "[Storage]:label",
    "[Storage Icon]": "[Storage]:leftImage",

    "[Sound & vibration]": "",
    "{Sound & vibration}": "[Sound & vibration]:label",
    "[Sound & vibration Icon]": "[Sound & vibration]:leftImage",

    "[Display]": "",
    "{Display}": "[Display]:label",
    "[Display Icon]": "[Display]:leftImage",

    "[Wallpaper & style]": "",
    "{Wallpaper & style}": "[Wallpaper & style]:label",
    "[Wallpaper & style Icon]": "[Wallpaper & style]:leftImage",

    "[Accessibility]": "",
    "{Accessibility}": "[Accessibility]:label",
    "[Accessibility Icon]": "[Accessibility]:leftImage",

    "[Security]": "",
    "{Security}": "[Security]:label",
    "[Security Icon]": "[Security]:leftImage",

    "[Privacy]": "",
    "{Privacy}": "[Privacy]:label",
    "[Privacy Icon]": "[Privacy]:leftImage",

    "[Location]": "",
    "{Location}": "[Location]:label",
    "[Location Icon]": "[Location]:leftImage",

    "[Safety & emergency]": "",
    "{Safety & emergency}": "[Safety & emergency]:label",
    "[Safety & emergency Icon]": "[Safety & emergency]:leftImage",

    "[Passwords & accounts]": "",
    "{Passwords & accounts}": "[Passwords & accounts]:label",
    "[Passwords & accounts Icon]": "[Passwords & accounts]:leftImage",

    "[Google]": "",
    "{Google}": "[Google]:label",
    "[Google Icon]": "[Google]:leftImage",

    "[System]": "",
    "{System}": "[System]:label",
    "[System Icon]": "[System]:leftImage",

    "[About emulated device]": "",
    "{About emulated device}": "[About emulated device]:label",
    "[About emulated device Icon]": "[About emulated device]:leftImage",

    "[About phone]": "",
    "{About phone}": "[About phone]:label",
    "[About phone Icon]": "[About phone]:leftImage",

    "[Tips & support]": "",
    "{Tips & support}": "[Tips & support]:label",
    "[Tips & support Icon]": "[Tips & support]:leftImage"
  },

  "scroll": {
    "start-elements": "",
    "end-elements": "{Tips & support}",
    "overlay-elements": "[Search Button][Search settings]"
  }
}

identity with satellites

Android Settings app has scrollable view and has no fixed identifier that displayed always. In this case, you can use identity with satellites to identify displayed screen.

  "identity": "#recycler_view",
  "satellites": ["Battery", "Accessibility", "Passwords & accounts", "Tips & support"],

Above example shows that "identity": "#recycler_view" is always displayed(but not unique identifier), "satellites" is a list of members that any of members are displayed on the Android Settings view. "identity"+"satellites" is recognized as unique identifier of the screen.

Relative Selector

Appium locators seems to assume that every element has unique attribute or to be implemented. But in the real world, especially for scrolling views, there are many elements that has no unique identifier.

In Shirates, we introduced Relative Selector to resolve this theme. When a UI element group has at least one element that has unique identifier, you can get elements around it relatively.

See following image.

"Battery" is static content and unique.
"100%" is dynamic content and has no unique identifier.
Battery Icon has no unique identifier.

In this case, you can define selector nickname as follows.

    "[Battery]": "",
    "{Battery}": "[Battery]:label",
    "[Battery Icon]": "[Battery]:leftImage",

:label is relative selector that selects next label on Widget flow. See Relative selector(Widget flow based)

:leftImage is relative selector that selects left image. See Relative selector(Direction based).

[System Screen].json

{
  "key": "[System Screen]",

  "include": [
  ],

  "identity": "[<-][System]",

  "selectors": {
    "[<-]": "@Navigate up",
    "[System]": "@System",

    "[Languages & input]": "",
    "{Languages & input}": "[Languages & input]:belowLabel",

    "[Gestures]": "",

    "[Date & time]": "",
    "{Date & time}": "[Date & time]:belowLabel",

    "[Backup]": "",

    "[System update]": "",
    "{System update}": "[System update]:belowLabel",

    "[Rules]": "",
    "{Rules}": "[Rules]:belowLabel",

    "[Multiple users]": "",
    "{Multiple users}": "[Multiple users]:belowLabel",

    "[Developer options]": "",
    "{Developer options}": "[Developer options]:belowLabel",

    "[Reset options]": ""
  }

}

[Languages & input Screen].json

{
  "key": "[Languages & input Screen]",

  "include": [
  ],

  "identity": "[<-][Languages & input]",

  "selectors": {
    "[<-]": "@Navigate up",
    "[Languages & input]": "@Languages & input",

    "[Languages]": "",
    "{Languages}": "[Languages]:belowLabel",
    "[Languages Icon]": "[Languages]:leftImage",

    "[Keyboards]": "",

    "[On-screen keyboard]": "",
    "{On-screen keyboard}": "[On-screen keyboard]:belowLabel",

    "[Physical keyboard]": "",
    "{Physical keyboard}": "[Physical keyboard]:belowLabel",

    "[Tools]": "",

    "[Spell checker]": "",
    "{Spell checker}": "[Spell checker]:belowLabel",

    "[Personal dictionary]": "",
    "{Personal dictionary}": "[Personal dictionary]:belowLabel",

    "[Pointer speed]": "",

    "[Text-to-speech output]": ""
  }

}

[Languages Screen].json

{
  "key": "[Languages Screen]",

  "include": [
  ],

  "identity": "[<-][Languages]",

  "selectors": {
    "[<-]": "@Navigate up",
    "[Languages]": "@Languages",

    "[Add a language]": ""
  }

}

AndroidSettingsTest

The following is Android Settings test code without or with Screen Nickname file. In case of without Screen Nickname file, you have to use low level identifier such as content-desc. On the other hand, in case of with Screen Nickname file, you can use abstract Screen Nickname/Selector Nickname.

package androidSettings

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

class AndroidSettingsTest : UITest() {

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

        scenario {
            case(1) {
                condition {
                    it.tapAppIcon("Settings")
                        .existWithScrollDown("Battery||Accessibility||Passwords & accounts||Tips & support")
                }.action {
                    it.tapWithScrollDown("System")
                }.expectation {
                    it.exist("@Navigate up")
                        .exist("@System")
                }
            }
            case(2) {
                action {
                    it.tap("Languages & input")
                }.expectation {
                    it.exist("@Navigate up")
                        .exist("@Languages & input")
                }
            }
            case(3) {
                action {
                    it.tap("Languages")
                }.expectation {
                    it.exist("@Navigate up")
                        .exist("@Languages")
                }
            }
        }
    }

    @Test
    @Order(20)
    fun withNickname() {

        scenario {
            case(1) {
                condition {
                    it.tapAppIcon("Settings")
                        .screenIs("[Android Settings Top Screen]")
                }.action {
                    it.tapWithScrollDown("[System]")
                }.expectation {
                    it.screenIs("[System Screen]")
                        .exist("[<-]")
                        .exist("[System]")
                }
            }
            case(2) {
                action {
                    it.tap("[Languages & input]")
                }.expectation {
                    it.screenIs("[Languages & input Screen]")
                        .exist("[Languages]")
                }
            }
            case(3) {
                action {
                    it.tap("[Languages]")
                }.expectation {
                    it.screenIs("[Languages Screen]")
                }
            }
        }
    }

}

Test Result

Look and compare without Screen Nickname and with Screen Nickname. You can find that with Screen Nickname is easier to understand.

`_Report(simple).html`

`AndroidSettingsTest@a.xlsx`

Conclusion

In Shirates, you can define Screen Nickname as JSON file. Screen Nickname makes test codes readable and productive.

How to use Screen Nickname in Shirates

wave1008 — Sun, 16 Oct 2022 07:07:33 +0000

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

Screen Nickname

In Shirates, you can define Screen Nickname as JSON file. Screen Nickname makes test codes readable and productive.

Screen Nickname features

Identify current displayed screen
Provide Selector Nicknames in the screen

Material

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

Example 1: Calculator

Start Android Emulator.
Launch Calculator App.

Launch Appium Inspector.
Capture Calculator App.

Create [Calculator Main Screen].json under testConfig/screens/calculator directory.

Inspect screen elements using Appium Inspector, edit the Screen Nickname file as follows.

[Calculator Main Screen].json

{
  "key": "[Calculator Main Screen]",

  "identity": "[AC][()]",

  "selectors": {
    "[formula]": "#formula",
    "[result final]": "#result_final",
    "[result preview]": "#result_preview",

    "[√]": "#op_sqrt",
    "[π]": "#const_pi",
    "[^]": "#op_pow",
    "[!]": "#op_fact",

    "[AC]": "#clr",
    "[()]": "#parens",
    "[%]": "#op_pct",

    "[÷]": "#op_div",
    "[×]": "#op_mul",
    "[-]": "#op_sub",
    "[+]": "#op_add",
    "[=]": "#eq",
    "[⌫]": "#del",

    "[0]": "#digit_0",
    "[1]": "#digit_1",
    "[2]": "#digit_2",
    "[3]": "#digit_3",
    "[4]": "#digit_4",
    "[5]": "#digit_5",
    "[6]": "#digit_6",
    "[7]": "#digit_7",
    "[8]": "#digit_8",
    "[9]": "#digit_9",
    "[.]": "#dec_point"
  }

}

You can identify the screen with identity "[AC][()]" as [Calculator Main Screen] on running test.
For example, you can assert current screen is [Calculator Main Screen].

it.screenIs("[Calculator Main Screen]")

CalculatorTest

The following is Calculator test code without or with Screen Nickname file. In case of without Screen Nickname file, you have to use low level identifier such as resource-id. On the other hand, in case of with Screen Nickname file, you can use abstract Screen Nickname/Selector Nickname.

package calculator

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

class CalculatorTest : UITest() {

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

        scenario {
            case(1) {
                condition {
                    it.tapAppIcon("Calculator")
                }.expectation {
                    it.exist("#clr")
                    it.exist("#parens")
                }
            }
            case(2) {
                action {
                    it.tap("#clr")
                }.expectation {
                    it.select("#formula")
                        .textIsEmpty()
                    it.select("#result_preview")
                        .textIsEmpty()
                }
            }
            case(3) {
                action {
                    it.tap("#digit_1")
                }.expectation {
                    it.select("#formula")
                        .textIs("1")
                    it.select("#result_preview")
                        .textIsEmpty()
                }
            }
            case(4) {
                action {
                    it.tap("#op_add")
                }.expectation {
                    it.select("#formula")
                        .textIs("1+")
                    it.select("#result_preview")
                        .textIsEmpty()
                }
            }
            case(5) {
                action {
                    it.tap("#digit_2")
                }.expectation {
                    it.select("#formula")
                        .textIs("1+2")
                    it.select("#result_preview")
                        .textIs("3")
                }
            }
            case(6) {
                action {
                    it.tap("#eq")
                }.expectation {
                    it.select("#result_final")
                        .textIs("3")
                }
            }
        }
    }

    @Test
    @Order(20)
    fun withNickname() {

        scenario {
            case(1) {
                condition {
                    it.tapAppIcon("Calculator")
                }.expectation {
                    it.screenIs("[Calculator Main Screen]")
                }
            }
            case(2) {
                action {
                    it.tap("[AC]")
                }.expectation {
                    it.select("[formula]")
                        .textIsEmpty()
                    it.select("[result preview]")
                        .textIsEmpty()
                }
            }
            case(3) {
                action {
                    it.tap("[1]")
                }.expectation {
                    it.select("[formula]")
                        .textIs("1")
                    it.select("[result preview]")
                        .textIsEmpty()
                }
            }
            case(4) {
                action {
                    it.tap("[+]")
                }.expectation {
                    it.select("[formula]")
                        .textIs("1+")
                    it.select("[result preview]")
                        .textIsEmpty()
                }
            }
            case(5) {
                action {
                    it.tap("[2]")
                }.expectation {
                    it.select("[formula]")
                        .textIs("1+2")
                    it.select("[result preview]")
                        .textIs("3")
                }
            }
            case(6) {
                action {
                    it.tap("[=]")
                }.expectation {
                    it.select("[result final]")
                        .textIs("3")
                }
            }
        }
    }
}

Test Result

Look and compare without Screen Nickname and with Screen Nickname. You can find that with Screen Nickname is easier to understand.

`_Report(simple).html`

`CalculatorTest@a.xlsx`

Conclusion

In Shirates, you can define Screen Nickname as JSON file. Screen Nickname makes test codes readable and productive.

How to use selector expression in Shirates

wave1008 — Sat, 15 Oct 2022 20:16:35 +0000

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

Selector expression

Shirates Selector expression is expression to filter screen elements.

select function accepts selector expressions, parses them, retrieves and filters elements, and returns result element.

Selector expression consists of one or more filter expressions.

Filter expression

Shirates Filter expression is expression describing conditions to filter screen elements.

filter	formal	abbreviation	Android attribute	iOS attribute
text	text=text1	text1	text	label
textStartsWith	textStartsWith=text1	text1*	text	label
textContains	textContains=text1	text1	text	label
textEndsWith	textEndsWith=text1	*text1	text	label
textMatches	textMatches=^text$	n/a	text	label
literal	literal=literal1	'literal1'	text	label
id	id=id1	#id1	resource-id	name
access	access=access1	@access1	content-desc	name
accessStartsWith	accessStartsWith=access1	@access1*	content-desc	name
accessContains	accessContains=access1	@access1	content-desc	name
accessEndsWith	accessEndsWith=access1	@*access1	content-desc	name
accessMatches	accessMatches=^access1$	n/a	content-desc	name
value	value=value1	n/a	text	value
valueStartsWith	valueStartsWith=value1	n/a	text	value
valueContains	valueContains=value1	n/a	text	value
valueEndsWith	valueEndsWith=value1	n/a	text	value
valueMatches	valueMatches=^value1$	n/a	text	value
class	class=class1	.class1	class	type
focusable	focusable=true	n/a	focusable	n/a
scrollable	scrollable=true	n/a	scrollable	n/a
visible	visible=true	n/a	n/a	visible
xpath	xpath=//*[@text='text1']	n/a	(arbitrary)	(arbitrary)
pos	pos=2	[2]	n/a	n/a
ignoreTypes	ignoreTypes=Class1,Class2	n/a	class	type
image	image=image1.png	image1.png	n/a	n/a

For more information

See Selector expression

Material

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

SelectTest2

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

class SelectTest2 : UITest() {

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

        scenario {
            case(1) {
                condition {
                    it.restartApp()
                }.action {
                    it.select("Network & internet")
                }.expectation {
                    it.textIs("Network & internet")
                }
            }
            case(2) {
                action {
                    it.select("Network &*")
                }.expectation {
                    it.textIs("Network & internet")
                }
            }
            case(3) {
                action {
                    it.select("*internet")
                }.expectation {
                    it.textIs("Network & internet")
                }
            }
            case(4) {
                action {
                    it.select("textMatches=^Network & internet$")
                }.expectation {
                    it.textIs("Network & internet")
                }
            }
            case(5) {
                action {
                    it.selectWithScrollDown("About phone||About emulated device")
                }.expectation {
                    realDevice {
                        it.textIs("About phone")
                    }.emulator {
                        it.textIs("About emulated device")
                    }
                }
            }
        }
    }

    @Test
    @Order(20)
    fun selectById() {

        scenario {
            case(1) {
                condition {
                    it.restartApp()
                }.action {
                    it.select("#search_action_bar_title")
                }.expectation {
                    it.textIs("Search settings")
                }
            }
        }
    }

    @Test
    @Order(30)
    fun selectByAccessibility() {

        scenario {
            case(1) {
                condition {
                    it.restartApp()
                        .tap("Network & internet")
                }.action {
                    it.select("@Network & internet")
                }.expectation {
                    it.idIs("collapsing_toolbar")
                }
            }
        }
    }

    @Test
    @Order(40)
    fun selectByClass() {

        scenario {
            case(1) {
                condition {
                    it.restartApp()
                }.action {
                    it.select(".android.widget.ImageButton")
                }.expectation {
                    it.classIs("android.widget.ImageButton")
                }
            }
        }
    }

    @Test
    @Order(50)
    fun selectByXpath() {

        scenario {
            case(1) {
                condition {
                    it.restartApp()
                }.action {
                    it.select("xpath=//*[@text='Search settings']")
                }.expectation {
                    it.textIs("Search settings")
                }
            }
        }
    }

    @Test
    @Order(60)
    fun selectByPos() {

        scenario {
            case(1) {
                condition {
                    it.restartApp()
                        .tap("Battery")
                }.action {
                    it.select("*Battery*&&[1]")
                }.expectation {
                    it.textIs("Battery Usage")
                }
            }
            case(2) {
                action {
                    it.select("*Battery*&&[2]")
                }.expectation {
                    it.textIs("Battery Saver")
                }
            }
            case(3) {
                action {
                    it.select("*Battery*&&[3]")
                }.expectation {
                    it.textIs("Battery percentage")
                }
            }
        }
    }

}

Test Result

Conclusion

Shirates Selector expression is simple yet powerful expression for retrieving an element on the screen, as flexible as XPath, but much easier than XPath.