Mobile Application Plugin

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

Filter Types

Type	Description	Examples partial$common-filters.adoc
`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'])
`accessibilityId`	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)
`iosClassChain`	`iOS`	See Class Chain Queries for more details	iosClassChain(/XCUIElementTypeCell[$name BEGINSWITH "A"$]) or By.iosClassChain(/XCUIElementTypeCell[$name BEGINSWITH "B"$])
`iosNsPredicate`	`iOS`	See iOS Predicate Syntax for more details	iosNsPredicate(name BEGINSWITH 'A') or By.iosNsPredicate(name BEGINSWITH 'B')

partial$visibility-types.adoc

Properties

Note	The properties marked with bold are mandatory.

Property Name Acceptable values Default Description partial$selenium-properties.adoc

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`

partial$proxy-properties.adoc

partial$proxy-meta-tags.adoc

Important

For device configuration, we need to perform the following steps: install CA certificate(download CA certificate from a browserup repository), configure device proxy, and configure the test app to allow proxy in cases of necessity.

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

tvOS

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

Default profile configuration

selenium.grid.platform-name=tvOS
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

Local

The local profiles can be used in conjunction with:

mobile_app/android,
mobile_app/ios,
mobile_app/tvos.

`mobile_app/local`

The profile simplifies configuration of tests execution against the local Appium 1.x server.

Configure local execution of the tests for iOS native application

configuration.profiles=mobile_app/local,mobile_app/ios

`mobile_app/local2`

The profile simplifies configuration of tests execution against the local Appium 2.x server.

Configure local execution of the tests for Android native application

configuration.profiles=mobile_app/local2,mobile_app/android

Dynamic variables

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}

Verify clipboard content

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

partial$dynamic-variables-ui.adoc

Steps

Start mobile application

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

Given I start mobile application

Start mobile application with capabilities

Starts mobile application with capabilities from user’s *.properties files and profiles set by a user. Additionally the step takes a list of capabilities as an argument that overrides globally-defined capabilities.

Given I start mobile application with capabilities:$capabilities

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

Start mobile application with 2 custom capabilities

Given I start mobile application with capabilities:
|name                           |value|
|bstack:options.networkLogs     |true |
|appium:options.clearSystemFiles|false|

Activate mobile application

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

When I activate application with bundle identifier `$bundleId`

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

Switch to Safari browser application

When I activate application with bundle identifier `com.apple.mobilesafari`

Reinstall mobile application

Removes the mobile application from device/emulator/simulator and installs it again.

When I reinstall mobile application with bundle identifier `$bundleId`

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

The key benefit is that instead of the full remote session recreation (which includes device re-allocation in testing clouds, like SauceLabs, BrowserStack, etc.) achivable via the following example:

When I close mobile application
Given I start mobile application with capabilities:
|name     |value|
|fullReset|true |

the step re-uses the current session which significantly improves performance.

Reinstall mobile application

When I reinstall mobile application with bundle identifier `vividus-mobile.app`

Terminate mobile application

Terminates the running application on the device/emulator/simulator and navigates to the home device screen. The remote session will not be closed.

When I terminate application with bundle identifier `$bundleId`

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

Terminates Safari browser application

When I terminate application with bundle identifier `com.apple.mobilesafari`

Close mobile application

Closes the mobile application and quits the remote session.

When I close mobile application

Run mobile application in background

Runs mobile application in the background for specific period of time and either activates the app after a certain amount of time, or leave the app deactivated (when PT-1S is used). See Appium docs for more details.

When I send mobile application to background for `$period` period

$period - The period of time in {durations-format-link} format.

Run app in background

When I send mobile application to background for `PT5S` period
Then number of elements found by `accessibilityId(login-button)` is equal to `1`

Change session settings

Changes the behavior of the Appium session.

When I change Appium session settings:$settings

$settings - The settings to set.

Configure to show invisible elements

When I change Appium session settings:
|name                  |value|
|allowInvisibleElements|true |

Upload a file to the device

Uploads a file to the device/emulator/simulator.

When I upload file `$filePath` to device

$filePath - The path of the file to upload to the device.

partial$mobile-upload-folder-info.adoc

Upload file

When I upload file `images/avatar.png` to device
Then the avatar icon is displayed with the uploaded image

Upload the file with data to the device

Upload the file with data to the device/emulator/simulator.

When I upload file with name `$fileName` and data `$data` to device

$data - The data to store as a file.
$fileName - The name of the uploaded file.

partial$mobile-upload-folder-info.adoc

Upload the file with the image data to the device

When I execute HTTP GET request for resource with URL `https://raw.githubusercontent.com/vividus-framework/vividus/master/vividus-tests/src/main/resources/baselines/context.png`
When I upload file with name `context.png` and data `${response-as-bytes}` to device
Then image is displayed in gallery

Upload the file with the text data to the device

When I upload file with name `message.txt` and data `This is a message` to device
Then message file is displayed in file explorer

Delete a file from the device

Deletes a file from the device/emulator/simulator.

When I delete file `$filePath` from device

partial$mobile-remote-file-path.adoc

Delete file

When I delete file `/sdcard/Pictures/avatar.png` from device

Important

On iOS real device to add or delete photo or video to/from "Camera Roll" you need upload/delete photos or videos to/from /DCIM/100APPLE/ folder and then trigger a rebuild of the "Camera Roll" database by deleting the old databases. You can accomplish it by deleting following files: /PhotoData/Photos.sqlite, /PhotoData/Photos.sqlite-shm, /PhotoData/Photos.sqlite-wal. Restart device is necessary after that.

Important

On iOS simulator to delete photo or video from "Camera Roll" you need to delete photo or video from /Media/DCIM/100APPLE/ and then trigger a rebuild of the "Camera Roll" database by deleting the old databases. You can accomplish it by deleting following files: /Media/PhotoData/Photos.sqlite, /Media/PhotoData/Photos.sqlite-shm, /Media/PhotoData/Photos.sqlite-wal. And then restart simulator.

Download the file from the device

Downloads the file from the device/emulator/simulator and saves its content to a variable.

When I download file `$filePath` from device and save its content to $scopes variable `$variableName`

partial$mobile-remote-file-path.adoc

$scopes - The comma-separated set of the variables scopes.
$variableName - The variable name to store the file content.

Download file

When I download file `/sdcard/file.json` from device and save its content to scenario variable `json-file`

Switch to Web view by name

Switches context to a web view with name that matches the rule (see Automating hybrid apps for more information). Also, Appium capabilities for iOS and Android are available for the fine-tuning configuration.

When I switch to web view with name that $comparisonRule `$value`

$comparisonRule - The web view name comparison rule.
$value - The value to find the target web view.

Switch to web view by name

Then number of elements found by `xpath(html)` is equal to `0`
When I switch to web view with name that contains `vividustestapp`
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

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`

Tap on element

Taps on the element located by the locator.

The atomic actions performed are:

press on the element;
release.

When I tap on element located by `$locator`

Deprecated syntax (will be removed in VIVIDUS 0.6.0):

When I tap on element located `$locator`

$locator - [_locator].

Tap on element

When I tap on element located by `accessibilityId(menu-toggler)`

Tap on element with duration

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.

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

Deprecated syntax (will be removed in VIVIDUS 0.6.0):

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

$locator - [_locator].
$duration - The duration between an element is pressed and released in {durations-format-link} format.

Tap on element with duration

When I tap on element located by `accessibilityId(menu-toggler)` with duration `PT0.5S`

Double tap on element

Performs double tap on the element located by the locator.

Warning

The step is supported for Android and iOS platforms.

When I double tap on element located by `$locator`

$locator - [_locator].

Double tap on element

When I double tap on element located by `accessibilityId(increment)`

Press key

Presses iOS keys or Android keys.

When I press $key key

$key - The key to press.

Go to Home screen

When I press Home key

Long press key

Performs long press of iOS keys or Android keys.

Tip	to modify long press duration for `iOS` and `tvOS` you could use `mobile-application.long-press-duration` property.

When I long press $key key

$key - The key to perform long press action.

Go to Home screen

When I long press Home key

Press keys

Presses a sequence of iOS keys or Android keys.

When I press keys:$keys

$keys - The keys to press.

Enter password

When I press keys:
|key|
|P  |
|a  |
|s  |
|1  |
|$  |

Type text sequentially

Types the provided text

Warning

All the characters will be treated as is and passed sequentially. To send special key like HOME please use [_press_keys].

When I type text `$text`

$text - The text to type.

Enter password

When I type text `pas1$`

Type text in a field

Types the text into the element located by the locator.

Warning

The existing text is re-written by the text passed into the step.

The atomic actions performed are:

type text into the element;
hide keyboard.

Warning

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 is performed to close the keyboard.

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

$text - The text to type into the element.
$locator - [_locator].

Type text

When I type `Bob` in field located `accessibilityId(username)`

Type text and keep keyboard opened

Only types text into the element. The keyboard hiding is skipped.

When I type `$text` in field located `$locator` and keep keyboard opened

$text - The text to type into the element.
$locator - [_locator].

Type text and keep keyboard opened

When I type `Bob` in field located `accessibilityId(username)` and keep keyboard opened

Clear field

Clears the field located by the locator.

The atomic actions performed are:

clear the field;
hide keyboard.

Warning

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 is performed to close the keyboard.

When I clear field located `$locator`

$locator - [_locator].

Clear the field

When I clear field located `accessibilityId(username)`

Clear field and keep keyboard open

Only clears the field located by the locator. The keyboard hiding is skipped.

When I clear field located `$locator` and keep keyboard open

$locator - [_locator].

Clear text and keep keyboard open

When I clear field located `accessibilityId(username)` and keep keyboard open

Swipe to an element

Swipes to an element in either UP, DOWN, LEFT or RIGHT direction with the specified swipe duration.

Note	The step takes into account the current context. If you need to perform swipe on the element, you need to switch the context to this element.

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
mobile-application.swipe.vertical.x-position - defines a vertical swipe x axis position in percentage from 0 to 100, where 0 corresponds to x=1 and 100 corresponds to x = mobile screen width - 1, default value is 0
mobile-application.swipe.horizontal.y-position - defines a horizontal swipe y axis position in percentage from 0 to 100, where 0 corresponds to y=1 and 100 corresponds to y = mobile screen height - 1, default value is 50

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

Deprecated syntax (will be removed in VIVIDUS 0.6.0):

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

$direction - The direction to swipe: UP, DOWN, LEFT or RIGHT.
$locator - [_locator].
$swipeDuration - The swipe duration in {durations-format-link} format.

Swipe to an element

Then number of elements found by `accessibilityId(end-of-screen)` is equal to `0`
When I swipe UP to element located by `accessibilityId(end-of-screen)` with duration PT1S
Then number of elements found by `accessibilityId(end-of-screen)` is equal to `1`

Swipe the context element

Scenario: Switch slides
When I change context to element located by `accessibilityId(carousel)`
Then number of elements found by `accessibilityId(slide 2)` is equal to `0`
When I swipe LEFT to element located `accessibilityId(slide 2)` with duration PT1S
Then number of elements found by `accessibilityId(slide 2)` is equal to `1`

Execute sequence of touch actions

Executes the sequence of touch actions.

When I execute sequence of touch actions: $actions

$actions - The table with actions to execute.

Table 1. Possible actions

`type`	`argument`	Argument example
TAP	Element locator or empty	By.id(Name)
TAP_AND_HOLD	Element locator or empty	By.id(Name)
MOVE_TO	Element locator	By.id(username)
MOVE_BY_OFFSET	Point, that specifies x and y distance to move from its current position or from upper left corner (0,0), if the pointer has not previously been moved	(10, 15) where x is 10 and y is 15
RELEASE	empty
WAIT	Duration	PT1S - wait 1 second

Note	`RELEASE` action releases the finger at the current touch location. For example, it can be used in the following sequence of actions:`TAP_AND_HOLD` → `MOVE_BY_OFFSET` → `RELEASE`

Execute touch actions

When I execute sequence of touch actions:
|type          |argument          |
|TAP_AND_HOLD  |By.id(Hello World)|
|MOVE_BY_OFFSET|(0,200)           |
|RELEASE       |                  |

Zoom in/out

Performs zoom in/out

Example 1. Zoom in

Example 2. Zoom out

Note	The step takes into account the current context. If you need to perform zoom on the element, you need to switch the context to this element.

Properties

Property Name	Acceptable values	Default value	Description
`mobile-application.zoom.indent.top`	size in percentage	`30`	The size of the top part of the context to be excluded from zoom area
`mobile-application.zoom.indent.bottom`	size in percentage	`30`	The size of the bottom part of the context to be excluded from zoom area
`mobile-application.zoom.indent.right`	size in percentage	`20`	The size of the right part of the context to be excluded from zoom area
`mobile-application.zoom.indent.left`	size in percentage	`20`	The size of the left part of the context to be excluded from zoom area

Warning

The indent percentage value should be from 0 to 99.

The sum of top and bottom indent percentage values should be from 0 to 99.

The sum of right and left indent percentage values should be from 0 to 99.

Property configuration

mobile-application.zoom.indent.top=30
mobile-application.zoom.indent.bottom=30
mobile-application.zoom.indent.right=20
mobile-application.zoom.indent.left=20

Step

When I zoom $zoomType context

$zoomType - The type of zoom: IN or OUT

Zoom in/out

When I zoom in context
When I wait until element located by `xpath(<welcomeMessageXpath>)` disappears
When I zoom out context
When I wait until element located by `xpath(<welcomeMessageXpath>)` appears

Select date in date picker

Selects a next or previous picker wheel value in date picker

Only iOS platform is supported.
The target element must be of type XCUIElementTypePickerWheel.

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

$direction - The direction to search the value: NEXT or PREVIOUS.
$offset - The ofset to pick from a middle of the wheel, see Select Picker Wheel Value guide.
$locator - The locator to find XCUIElementTypePickerWheel element.

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)`

Recording iOS Performance metrics

Records performance metrics of iOS application. It is based on the Instruments utility distributed by Xcode which provides a number of built-in analyses and measurements. See Capturing Performance Data for Native iOS Apps and Getting Started with Instruments for more information.

Note	Appium server should be started with the --relaxed-security flag. This is because Instruments can gather data from the system as a whole, not just the AUT. (It’s thus a security risk to expose potentially sensitive system information to Appium sessions running from a remote client).

Note	Archive with results contains *.trace file which could be opened by XCode. There is possibility to parse this file using XCode’s utility xctrace and use generated data in tests

When I start recording `$instrument` metrics
When I stop recording `$instrument` metrics and save results to file `$path`

$instrument - The instrument of Xcode Instruments utility. Some useful instruments: Time Profiler, Leaks, File Activity, etc.
$path - The path to the file to save an archive with collected data.

Perform profiling during application usage

When I start recording `Time Profiler` metrics
!-- set of actions to measure performance
When I stop recording `Time Profiler` metrics and save results to file `${outputDirectory}/time_profiler.zip`

Set slider value

iOS

Sets the slider value in percents.

The accuracy of setting the slider value is not guaranteed and may vary depending on the device screen resolution.
The target element must be of type XCUIElementTypeSlider.
The percent number must be between 0 and 100 inclusively.

When I set value of iOS slider located `$locator` to `$percent` percents

$locator - The locator to find XCUIElementTypeSlider element.
$percent - The target value of the slider in percents.

Set value of iOS slider (with range 0:50) to 45

When I set value of iOS slider located `xpath(//XCUIElementTypeSlider)` to `90` percents

Set value of iOS slider (with range -50:50) to 20

When I set value of iOS slider located `xpath(//XCUIElementTypeSlider)` to `70` percents

Set value of iOS slider (with range 18:65) to 55

When I set value of iOS slider located `xpath(//XCUIElementTypeSlider)` to `80` percents

Android

Sets the slider value to the number relatively to the slider leftmost side of its range.

The step is expected to set accurate value without deviations.
The target element must be of type android.widget.SeekBar.
The number must be greater than or equal to 0.
Make sure the passed number does not exceed the right limit of the slider, this may lead to unexpected failure.

When I set value of Android slider located `$locator` to `$number`

$locator - The locator to find android.widget.SeekBar element.
$number - The number to set on the slider

Set value of Android slider (with range 0:50) to 13

When I set value of Android slider located `xpath(//android.widget.SeekBar)` to `13`

Set value of Android slider (with range -50:50) to -25

When I set value of Android slider located `xpath(//android.widget.SeekBar)` to `25`

Set value of Android slider (with range 18:65) to 20

When I set value of Android slider located `xpath(//android.widget.SeekBar)` to `2`

partial$generic-ui-steps.adoc

Scan barcode from context

Scan a barcode from the specified context and save its value to the variable with the specified name. If context not set - takes a screenshot of the current screen. Only the first found barcode will be scanned.

Supported Code Formats

partial$code-formats.adoc

Actions performed at this step:

Takes a screenshot of the specified context. If it’s not set - takes a screenshot of the current screen (viewport and system bars)
Scans a barcode from the screenshot and save its value to the variable

When I scan barcode from context and save result to $scopes variable `$variableName`

$scopes - The comma-separated set of the variables scopes.
$variableName - The name of the variable to save the value of the barcode.

Scan the barcode

When I change context to element located by `xpath(//android.view.ViewGroup[@resource-id='qrContainer'])`
When I scan barcode from context and save result to scenario variable `qrCodeLink`
Then `${qrCodeLink}` is equal to `https://www.example.com`

partial$proxy-steps.adoc

Change network connection

Turns ON/OFF network connection.

Warning

To be able to use this step in the cloud testing platform, review the documentation related to simulating the mobile network conditions on the selected platform.

When I turn $toggle `$connectionName` network connection

$toggle - The modes of the toggle: ON or OFF.
$connectionName - The name of the network connect to toggle.

Connection name	Supported platforms	Description
`WIFI`	Android emulators, Android and iOS real devices	Wi-Fi connection
`MOBILE_DATA`	Android emulators, Android and iOS real devices	Mobile Data connection
`AIRPLANE`	Android real devices, Android emulators	Airplane Mode
`WIFI_AND_MOBILE_DATA`	Android real devices, Android emulators	Mobile Data and Wi-Fi connections

Tip	For iOS real devices: to return to the application you must use the step: When I activate application with bundle identifier `$bundleId`.

Turn OFF Wi-Fi for Android

When I turn OFF `WIFI` network connection

Turn OFF Wi-Fi for iOS

When I turn OFF `WIFI` network connection
When I activate application with bundle identifier `my-application-bundle-id`

Change device screen orientation

Changes the device screen orientation.

When I change device screen orientation to $orientation

$orientation - The device screen orientation, either portrait or landscape.

Change the device screen orientation

When I change device screen orientation to portrait

Files

plugin-mobile-app.adoc

Latest commit

History

plugin-mobile-app.adoc

File metadata and controls

Mobile Application Plugin

Filter Types

Locator Types

Properties

Profiles

iOS

tvOS

Android

Local

mobile_app/local

mobile_app/local2

Dynamic variables

Get clipboard text

Properties

Steps

Start mobile application

Start mobile application with capabilities

Activate mobile application

Reinstall mobile application

Terminate mobile application

Close mobile application

Run mobile application in background

Change session settings

Upload a file to the device

Upload the file with data to the device

Delete a file from the device

Download the file from the device

Switch to Web view by name

Switch to native context

Tap on element

Tap on element with duration

Double tap on element

Press key

Long press key

Press keys

Type text sequentially

Type text in a field

Type text and keep keyboard opened

Clear field

Clear field and keep keyboard open

Swipe to an element

Properties

Execute sequence of touch actions

Zoom in/out

Properties

Step

Select date in date picker

Recording iOS Performance metrics

Set slider value

iOS

Android

Scan barcode from context

Change network connection

Change device screen orientation

`mobile_app/local`

`mobile_app/local2`