Mobile Application Plugin

The plugin provides functionality to test mobile application on real devices, Android Emulators and iOS Simulators

Installation

Example 1. build.gradle
implementation(group: 'org.vividus', name: 'vividus-plugin-mobile-app', version: '0.3.6-SNAPSHOT')

Locator

By.<locatorType>(<locatorValue>):<visibility>->filter.<filterType>(<filterValue>)
By. prefix is optional.

  1. locatorType - [mandatory] type of the locator

  2. locatorValue - [mandatory] value of the locator

  3. visibility - [optional] visibility of element (visible by default)

  4. filterType - [optional] type of the filter

  5. filterValue - [required if filter type defined] value of the filter

Filter Types

Type Description Examples

index

Get an element by the specified index from a collection of elements found by a locator. Indexes start from 1.

tagName(div)→filter.index(2)

textPart

Filter elements by their text parts.

tagName(h3)→filter.textPart(Welcome)

text

Filter elements by their exact text.

tagName(android.widget.EditText)→filter.text(Welcome)

attribute

Filter elements by their attribute values

tagName(android.widget.TextView)→filter.attribute(text=Hi) - android.widget.TextView element has the text attribute with Hi value tagName(android.widget.TextView)→filter.attribute(text) - android.widget.TextView element has the text attribute with any value tagName(android.widget.TextView)→filter.attribute(text=) - android.widget.TextView element has the text attribute with an empty value

Locator Types

Type Platform Description Examples

XPath

any

Search the app XML source using xpath (not recommended, has performance issues)

xpath(//android.widget.TextView[@text='Home']) or By.xpath(//XCUIElementTypeStaticText[@value='Home'])

Accessibility ID

any

See Accessibility ID selector strategy

accessibilityId(menu-toggler) or By.accessibilityId(menu-toggler)

ID

any

See ID selector strategy

id(org.vividus:id/menu-toggler) or By.id(menu-toggler)

iOS Class Chain

iOS

See Class Chain Queries for more details

iosClassChain(**/XCUIElementTypeCell[$name BEGINSWITH "A"$]) or By.iosClassChain(**/XCUIElementTypeCell[$name BEGINSWITH "B"$])

Visibility types

Visibility type Usage example Description

VISIBLE

xpath(//a)

Default visibility option. Only visible elements will be found

INVISIBLE

xpath(//a):i

Only invisible elements will be found

all

xpath(//a):a

Either visible and invisible elements will be found

Properties

Property Name Acceptable values Default Description

mobile-application.session-scope

story

scenario

story

Defines the test lifecycle of the mobile application:

  • the mobile application opens at the first step requiring mobile application interaction

  • the mobile application closes after story or scenario depending on the property value

  • each scenario-level examples table iteration is treated as a separate scenario

An empty property value will lead to the error: "Application session scope is not set".

ui.publish-source-on-failure

true/false

true

Defines if Vividus publishes the application source code on failure

selenium.grid.host

hostname

empty

Defines remote grid host to be used to create a new session

selenium.grid.username

username

empty

Defines remote grid username to be used to create a new session

selenium.grid.password

password

empty

Defines password to be used to create a new session

selenium.grid.platform-name

Android

iOS

Depends on the set profile

Defines the mobile OS to use

selenium.grid.automation-name

UIAutomator2 XCUITest

Depends on the set profile

Defines automation engine to use

Platform Recommended engine

Android

UIAutomator2

iOS

XCUITest

mobile-environment.real-device

true

false

Depends on the set profile

Defines whether the tests run on real device

Profile Value

browserstack/mobile_app

true

mobile_app/ios

false

mobile_app/android

false

mobile-environment.device.folder-for-file-upload

string

Depends on the set profile

Defines a destination folder on a device for a file being uploaded

Profile Value

mobile_app/ios

/private/var/mobile/Media/DCIM/

mobile_app/android

/sdcard/Pictures

Profiles

iOS

The profile can be enabled by adding mobile_app/ios to configuration.profiles property

Default profile configuration

selenium.grid.platform-name=iOS
selenium.grid.automation-name=XCUITest

Android

The profile can be enabled by adding mobile_app/android to configuration.profiles property

Default profile configuration

selenium.grid.platform-name=Android
selenium.grid.automation-name=UIAutomator2

Dynamic variables

Dynamic variables are variables available out of the box using standard approach ${name}. The variables support both lower camel case (e.g. ${dynamicVariableName}) and lower hyphen case (e.g. ${dynamic-variable-name}) name formats. Usually the data provided by the dynamic variables calculated at the runtime.

Get clipboard text

Gets the text of the system clipboard of simulator or real device

Properties

Property Name Default Description

mobile-environment.wda-bundle-id

empty

The property is for iOS real devices only and it specifies the WebDriverAgent bundle ID used to get clipboard text. The property value may vary depending on test cloud providers and can be found in the XCode logs.

 
${clipboard-text}
Example 2. Verify clipboard content
Then `${clipboard-text}` is equal to `uarlouski@gmail.com`

Steps

Start mobile application

Info

Starts mobile application with capabilities from user’s *.properties files and profiles set by a user

Wording

Given I start mobile application

Usage

Example 3. Sample.story
Scenario: Start mobile application
Given I start mobile application

Start mobile application with capabilities

Info

Starts mobile application with capabilities from user’s *.properties files and profiles set by a user, additionally step takes list of capabilities as an argument that override previously defined capabilities

Wording

Given I start mobile application with capabilities:$capabilities

Parameters

  1. $capabilities - capabilities to start application with, these capabilies have higher priority than capabilities defined in *.properties files and in profiles

Usage

Example 4. Sample.story
Scenario: Start mobile application with capabilities
Given I start mobile application with capabilities:
|name                           |value|
|bstack:options.networkLogs     |true |
|appium:options.clearSystemFiles|false|

Close mobile application

Info

Closes a mobile application and quits the session

Wording

When I close mobile application

Usage

Example 5. Close mobile application
When I close mobile application

Tap on element with duration

Info

Taps on the element located by the locator with the specified duration.

The atomic actions performed are: * press on the element * wait for the duration * release

Wording

When I tap on element located `$locator` with duration `$duration`

Parameters

  1. $locator - Locator

  2. $duration - duration between an element is pressed and released in ISO-8601 format

Usage

Example 6. Sample.story
Scenario: Tap on element with duration
When I tap on element located `accessibilityId(menu-toggler)` with duration `PT0.5S`

Tap on element

Info

Taps on the element located by the locator.

The atomic actions performed are: * press on the element * release

Wording

When I tap on element located `$locator`

Parameters

  1. $locator - Locator

Usage

Example 7. Sample.story
Scenario: Tap on element
When I tap on element located `accessibilityId(menu-toggler)`

Type text

Info

Types the text into the element located by the locator.

Existing text is re-written by the text passed into the step

The atomic actions performed are: * type text into the element * hide keyboard

For iOS real devices the hide keyboard action works only for XCUIElementTypeTextField elements and skipped for XCUIElementTypeTextView elements, in case of XCUIElementTypeTextView element tap outside the text view to close the keyboard.

Wording

When I type `$text` in field located `$locator`

Parameters

  1. $text - text to type into the element

  2. $locator - Locator

Usage

Example 8. Keyboard.story
Scenario: Type text
When I type `Bob` in field located `accessibilityId(username)`

Clear field

Info

Clears a field located by the locator.

The atomic actions performed are: * clear the field * hide keyboard

For iOS real devices the hide keyboard action works only for XCUIElementTypeTextField elements and skipped for XCUIElementTypeTextView elements, in case of XCUIElementTypeTextView element tap outside the text view to close the keyboard.

Wording

When I clear field located `$locator`

Parameters

  1. $locator - Locator

Usage

Example 9. Keyboard.story
Scenario: Type text
When I clear field located `accessibilityId(username)`

Swipe to an element

Info

Swipes to an element in either UP or DOWN direction with the specified swipe duration

Wording

When I swipe $direction to element located `$locator` with duration $swipeDuration

Properties

  • mobile-application.swipe.limit - defines max numbers of swipes to perform (if it’s reached the swipe process is stopped and the error is thrown)

  • mobile-application.swipe.stabilization-duration - defines a duration to wait after swipe until view becomes stable

Parameters

  1. $direction - direction to swipe, either UP or DOWN

  2. $locator - Locator

  3. $swipeDuration - swipe duration in ISO-8601 format

Usage

Example 10. Swipe.story
Scenario: Swipe to element
Then number of elements found by `accessibilityId(end-of-screen)` is equal to `0`
When I swipe UP to element located `accessibilityId(end-of-screen)` with duration PT1S
Then number of elements found by `accessibilityId(end-of-screen)` is equal to `1`

Upload a file to a device

Info

Uploads a file to a device

Wording

When I upload file `$filePath` to device

Parameters

  1. $filePath - path of the file to upload to a device

Usage

Example 11. Upload.story
Scenario: Upload file
When I upload file `images/avatar.png` to device
Then the avatar icon is displayed with the uploaded image

Activate mobile application

Info

Activates an existing application on the device and moves it to the foreground. The application should be already running in order to activate it.

Wording

When I activate application with bundle identifier `$bundleId`

Parameters

  1. $bundleId - Package name for Android or Bundle identifier from Plist.info for iOS

Usage

Example 12. GoToSafari.story
Scenario: Open safari
When I activate application with bundle identifier `com.apple.mobilesafari`

Verify elements number

Info

Verifies if the number of elements located by locator matches desired number

Wording

Then number of elements found by `$locator` is $comparisonRule `$quantity`

Parameters

  1. $locator - Locator

  2. $comparisonRule - Comparison rule

  3. $quantity - expected number of elements

Usage

Example 13. VerifyNumber.story
Scenario: Step verification 'Then number of elements found by `$locator` is $comparisonRule `$quantity`'
Then number of elements found by `tagName(img)` is equal to `5`

Verify elements state

Info

Verifies if the number of elements located by locator matches number condition and all of them are in desired state

If you describe number condition as equal to 5 in case if there are 10 elements by this locator and only 5 of them in the desired state. You will get two failed assertions. The first one about number condition violation. The second one about state check failure.
In case when locator’s visibility and checked state are equal (For an example :i and NOT_VISIBLE) exception will be thrown. In such cases please use step: Verify elements number

Wording

Then number of $state elements found by `$locator` is $comparisonRule `$quantity`

Parameters

  1. $state - State

  2. $locator - Locator

  3. $comparisonRule - Comparison rule

  4. $quantity - expected number of elements

Usage

Example 14. VerifyState.story
Scenario: Step verification 'Then number of $state elements found by `$locator` is $comparisonRule `$quantity`'
Given I am on a page with the URL '${vividus-test-site-url}'
Then number of VISIBLE elements found by `tagName(img)` is = `1`

Wait for element appearance

Info

Waits for appearance of an element by the locator

Wording

When I wait until element located `$locator` appears

Parameters

  1. $locator - Locator

Usage

Example 15. Wait.story
Scenario: Wait for element appearance
When I wait until element located `name(welcome-image)` appears

Wait for element disappearance

Info

Waits for disappearance of an element by the locator

Wording

When I wait until element located `$locator` disappears

Parameters

  1. $locator - Locator

Usage

Example 16. Wait.story
Scenario: Wait for element disappearance
When I wait until element located `name(welcome-image)` disappears

Save text of context element

Info

Saves text of a context element into a variable

Step will throw an error if the context element is not set

Wording

When I save text of context element to $scopes variable `$variableName`

Parameters

  1. $scopes - The set of variable’s scope

  2. $variableName - name of a variable

Usage

Example 17. SaveText.story
Scenario: Save text of context element
When I change context to element located `By.id(username)`
When I save text of context element to SCENARIO variable `username`

Save attribute value of context element

Info

Saves attribute value of a context element into a variable

Step will throw an error if the context element is not set

Wording

When I save `$attributeName` attribute value of context element to $scopes variable `$variableName`

Parameters

  1. $attributeName - name of an element’s attribute

  2. $scopes - The set of variable’s scope

  3. $variableName - name of a variable

Usage

Example 18. SaveAttributeValue.story
Scenario: Save attribute value of context element
When I change context to element located `By.id(username)`
When I save `innerText` attribute value of context element to SCENARIO variable `username`

Save attribute value of element

Info

Saves attribute value of an element located by locator into a variable

Wording

When I save `$attributeName` attribute value of element located `$locator` to $scopes variable `$variableName`

Parameters

  1. $attributeName - name of an element’s attribute

  2. $locator - Locator

  3. $scopes - The set of variable’s scope

  4. $variableName - name of a variable

Usage

Example 19. SaveAttributeValue.story
Scenario: Save attribute value of element
When I save `innerText` attribute value of element located `By.id(username)` to SCENARIO variable `username`

Save number of elements

Info

Saves number of elements located by locator into a variable

Wording

When I save number of elements located `$locator` to $scopes variable `$variableName`

Parameters

  1. $locator - Locator

  2. $scopes - The set of variable’s scope

  3. $variableName - name of a variable

Usage

Example 20. SaveNumberOfElements.story
Scenario: Save number of elements
When I save number of elements located `tagName(a)` to scenario variable `numberOfLinks`
Then `${numberOfLinks}` is equal to `1`

Change context

Info

Changes the context to an element located by locator for limiting area of subsequent UI interactions

Wording

When I change context to element located `$locator`

Parameters

  1. $locator - Locator

Usage

Example 21. ChangeContext.story
Scenario: Change context
Then number of elements found by `By.xpath(html)` is equal to `1`
When I change context to element located `By.xpath(//body)`
Then number of elements found by `By.xpath(html)` is equal to `0`

Reset context

Info

Resets the context

Wording

When I reset context

Usage

Example 22. ResetContext.story
Scenario: Reset context
Then number of elements found by `By.xpath(html)` is equal to `1`
When I change context to element located `By.xpath(//body)`
Then number of elements found by `By.xpath(html)` is equal to `0`
When I reset context
Then number of elements found by `By.xpath(html)` is equal to `1`

Element exists for duration

Info

Verifies that an element located by locator exists for given duration

Wording

Then element located `$locator` exists for `$duration` duration

Parameters

  1. $locator - Locator

  2. $duration - duration in ISO-8601 format

Usage

Example 23. ElementExistence.story
Scenario: Element should exists for 5 second
Then element located 'id(banner)' exists for 'PT5S' duration

Navigate back

Info

Navigates back to the previous view

Wording

When I navigate back

Usage

Example 24. Navigate back
Scenario: Navigate back
Then number of elements found by `xpath(//*[@*='Welcome'])` is equal to `1`
When I navigate back
Then number of elements found by `xpath(//*[@*='Welcome'])` is equal to `0`

Verify elements order

Info

Gets a collection of elements by locator and checks that they are sorted by their text in the specified order. The collection should have more than 1 element with not empty text, otherwise the step fails.

Wording

Then elements located `$locator` are sorted by text in $sortingOrder order

Parameters

  1. $locator - Locator

  2. $sortingOrder

Plain Readable Description

ASCENDING

ascending

Verify that elements are sorted in ascending order

DESCENDING

descending

Verify that elements are sorted in descending order

CASE_INSENSITIVE_ASCENDING

case-insensitive ascending

Verify that elements are sorted in case-insensitive ascending order

CASE_INSENSITIVE_DESCENDING

case-insensitive descending

Verify that elements are sorted in case-insensitive descending order

Usage

Example 25. OrderVerification.story
Scenario: Check items are sorted
Given I am on a page with the URL 'https://grocery.by'
When I click on element located `By.id(a-z)`
Then elements located `By.xpath(//span[@id='item-to-purchase'])` are sorted by text in ascending order

Change session settings

Info

Changes the behavior of the Appium session

Wording

When I change Appium session settings:$settings

Parameters

  1. $settings - Settings

Usage

Example 26. Settings.story
Scenario: Show invisible elements
When I change Appium session settings:
|name                  |value|
|allowInvisibleElements|true |

Select date in date picker

Info

Selects a next or previous picker wheel value in date picker

  • Only iOS platform is supported

  • Target element must be of type XCUIElementTypePickerWheel

Wording

When I select $direction value with `$offset` offset in picker wheel located `$locator`

Parameters

  1. $direction - next value to select, either NEXT or PREVIOUS

  2. $offset - offset for pick from a middle of a wheel, see Select Picker Wheel Value

  3. $locator - locator to locate XCUIElementTypePickerWheel element

Usage

Example 27. Select next item in the picker wheel
When I select next value with `0.1` offset in picker wheel located `xpath(//XCUIElementTypePickerWheel)->filter.index(3)`

Switch to web view

Switches context to a web view by the index, it starts from 1.

See Automating hybrid apps for more information.

When I switch to web view with index `$index`

  1. $index - index of a web view

Example 28. Switch to web view
Then number of elements found by `xpath(html)` is equal to `0`
When I switch to web view with index `1`
Then number of elements found by `xpath(html)` is equal to `1`

Switch to native context

Switches context to a mobile native context.

See Automating hybrid apps for more information.

When I switch to native context
Example 29. Switch to native context
Then number of elements found by `xpath(html)` is equal to `1`
When I switch to native context
Then number of elements found by `xpath(html)` is equal to `0`

Press key

Presses an iOS key or Android key

When I press $key key

  1. $key - The key to press

Example 30. Go to home
When I press Home key

Press keys

Presses a sequence of iOS keys or Android keys

When I press keys:$keys

  1. $keys - The keys to press

Example 31. Enter password
When I press keys:
|key|
|P  |
|a  |
|s  |
|1  |
|$  |

Verify elements number

Info

Verifies if the number of elements located by locator matches desired number

Wording

Then number of elements found by `$locator` is $comparisonRule `$quantity`

Parameters

  1. $locator - Locator

  2. $comparisonRule - Comparison rule

  3. $quantity - expected number of elements

Usage

Example 32. VerifyNumber.story
Scenario: Step verification 'Then number of elements found by `$locator` is $comparisonRule `$quantity`'
Then number of elements found by `tagName(img)` is equal to `5`

Verify elements state

Info

Verifies if the number of elements located by locator matches number condition and all of them are in desired state

If you describe number condition as equal to 5 in case if there are 10 elements by this locator and only 5 of them in the desired state. You will get two failed assertions. The first one about number condition violation. The second one about state check failure.
In case when locator’s visibility and checked state are equal (For an example :i and NOT_VISIBLE) exception will be thrown. In such cases please use step: Verify elements number

Wording

Then number of $state elements found by `$locator` is $comparisonRule `$quantity`

Parameters

  1. $state - State

  2. $locator - Locator

  3. $comparisonRule - Comparison rule

  4. $quantity - expected number of elements

Usage

Example 33. VerifyState.story
Scenario: Step verification 'Then number of $state elements found by `$locator` is $comparisonRule `$quantity`'
Given I am on a page with the URL '${vividus-test-site-url}'
Then number of VISIBLE elements found by `tagName(img)` is = `1`

Wait for element appearance

Info

Waits for appearance of an element by the locator

Wording

When I wait until element located `$locator` appears

Parameters

  1. $locator - Locator

Usage

Example 34. Wait.story
Scenario: Wait for element appearance
When I wait until element located `name(welcome-image)` appears

Wait for element disappearance

Info

Waits for disappearance of an element by the locator

Wording

When I wait until element located `$locator` disappears

Parameters

  1. $locator - Locator

Usage

Example 35. Wait.story
Scenario: Wait for element disappearance
When I wait until element located `name(welcome-image)` disappears

Save text of context element

Info

Saves text of a context element into a variable

Step will throw an error if the context element is not set

Wording

When I save text of context element to $scopes variable `$variableName`

Parameters

  1. $scopes - The set of variable’s scope

  2. $variableName - name of a variable

Usage

Example 36. SaveText.story
Scenario: Save text of context element
When I change context to element located `By.id(username)`
When I save text of context element to SCENARIO variable `username`

Save attribute value of context element

Info

Saves attribute value of a context element into a variable

Step will throw an error if the context element is not set

Wording

When I save `$attributeName` attribute value of context element to $scopes variable `$variableName`

Parameters

  1. $attributeName - name of an element’s attribute

  2. $scopes - The set of variable’s scope

  3. $variableName - name of a variable

Usage

Example 37. SaveAttributeValue.story
Scenario: Save attribute value of context element
When I change context to element located `By.id(username)`
When I save `innerText` attribute value of context element to SCENARIO variable `username`

Save attribute value of element

Info

Saves attribute value of an element located by locator into a variable

Wording

When I save `$attributeName` attribute value of element located `$locator` to $scopes variable `$variableName`

Parameters

  1. $attributeName - name of an element’s attribute

  2. $locator - Locator

  3. $scopes - The set of variable’s scope

  4. $variableName - name of a variable

Usage

Example 38. SaveAttributeValue.story
Scenario: Save attribute value of element
When I save `innerText` attribute value of element located `By.id(username)` to SCENARIO variable `username`

Save number of elements

Info

Saves number of elements located by locator into a variable

Wording

When I save number of elements located `$locator` to $scopes variable `$variableName`

Parameters

  1. $locator - Locator

  2. $scopes - The set of variable’s scope

  3. $variableName - name of a variable

Usage

Example 39. SaveNumberOfElements.story
Scenario: Save number of elements
When I save number of elements located `tagName(a)` to scenario variable `numberOfLinks`
Then `${numberOfLinks}` is equal to `1`

Change context

Info

Changes the context to an element located by locator for limiting area of subsequent UI interactions

Wording

When I change context to element located `$locator`

Parameters

  1. $locator - Locator

Usage

Example 40. ChangeContext.story
Scenario: Change context
Then number of elements found by `By.xpath(html)` is equal to `1`
When I change context to element located `By.xpath(//body)`
Then number of elements found by `By.xpath(html)` is equal to `0`

Reset context

Info

Resets the context

Wording

When I reset context

Usage

Example 41. ResetContext.story
Scenario: Reset context
Then number of elements found by `By.xpath(html)` is equal to `1`
When I change context to element located `By.xpath(//body)`
Then number of elements found by `By.xpath(html)` is equal to `0`
When I reset context
Then number of elements found by `By.xpath(html)` is equal to `1`

Element exists for duration

Info

Verifies that an element located by locator exists for given duration

Wording

Then element located `$locator` exists for `$duration` duration

Parameters

  1. $locator - Locator

  2. $duration - duration in ISO-8601 format

Usage

Example 42. ElementExistence.story
Scenario: Element should exists for 5 second
Then element located 'id(banner)' exists for 'PT5S' duration

Navigate back

Info

Navigates back to the previous view

Wording

When I navigate back

Usage

Example 43. Navigate back
Scenario: Navigate back
Then number of elements found by `xpath(//*[@*='Welcome'])` is equal to `1`
When I navigate back
Then number of elements found by `xpath(//*[@*='Welcome'])` is equal to `0`

Verify elements order

Info

Gets a collection of elements by locator and checks that they are sorted by their text in the specified order. The collection should have more than 1 element with not empty text, otherwise the step fails.

Wording

Then elements located `$locator` are sorted by text in $sortingOrder order

Parameters

  1. $locator - Locator

  2. $sortingOrder

Plain Readable Description

ASCENDING

ascending

Verify that elements are sorted in ascending order

DESCENDING

descending

Verify that elements are sorted in descending order

CASE_INSENSITIVE_ASCENDING

case-insensitive ascending

Verify that elements are sorted in case-insensitive ascending order

CASE_INSENSITIVE_DESCENDING

case-insensitive descending

Verify that elements are sorted in case-insensitive descending order

Usage

Example 44. OrderVerification.story
Scenario: Check items are sorted
Given I am on a page with the URL 'https://grocery.by'
When I click on element located `By.id(a-z)`
Then elements located `By.xpath(//span[@id='item-to-purchase'])` are sorted by text in ascending order