The plugin provides functionality to test mobile application on real devices, Android Emulators and iOS Simulators.
Type | Description | Examples partial$common-filters.adoc |
---|---|---|
|
Filter elements by their exact text. |
tagName(android.widget.EditText)→filter.text(Welcome) |
|
Filter elements by their attribute values |
|
Type | Platform | Description | Examples |
---|---|---|---|
|
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']) |
|
any |
See Accessibility ID selector strategy |
accessibilityId(menu-toggler) or By.accessibilityId(menu-toggler) |
|
any |
See ID selector strategy |
id(org.vividus:id/menu-toggler) or By.id(menu-toggler) |
|
|
See Class Chain Queries for more details |
iosClassChain(**/XCUIElementTypeCell[$name BEGINSWITH "A"$]) or By.iosClassChain(**/XCUIElementTypeCell[$name BEGINSWITH "B"$]) |
|
|
See iOS Predicate Syntax for more details |
iosNsPredicate(name BEGINSWITH 'A') or By.iosNsPredicate(name BEGINSWITH 'B') |
Note
|
The properties marked with bold are mandatory. |
Property Name | Acceptable values | Default | Description partial$selenium-properties.adoc | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|
|
Depends on the set profile |
Defines the mobile OS to use |
||||||||
|
|
Depends on the set profile |
Defines automation engine to use
|
||||||||
|
|
Depends on the set profile |
Defines whether the tests run on real device
|
||||||||
|
|
Depends on the set profile |
Defines a destination folder on a device for a file being uploaded
|
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. |
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
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
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
The local profiles can be used in conjunction with:
-
mobile_app/android
, -
mobile_app/ios
, -
mobile_app/tvos
.
The profile simplifies configuration of tests execution against the local Appium 1.x server.
configuration.profiles=mobile_app/local,mobile_app/ios
The profile simplifies configuration of tests execution against the local Appium 2.x server.
configuration.profiles=mobile_app/local2,mobile_app/android
Gets the text of the system clipboard of simulator or real device
Property Name | Default | Description |
---|---|---|
|
|
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}
Then `${clipboard-text}` is equal to `uarlouski@gmail.com`
Starts mobile application with capabilities from user’s *.properties
files and profiles set by a user.
Given I start mobile application
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.
Given I start mobile application with capabilities:
|name |value|
|bstack:options.networkLogs |true |
|appium:options.clearSystemFiles|false|
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 orBundle identifier
fromPlist.info
for iOS
When I activate application with bundle identifier `com.apple.mobilesafari`
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 orBundle identifier
fromPlist.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.
When I reinstall mobile application with bundle identifier `vividus-mobile.app`
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 orBundle identifier
fromPlist.info
for iOS
When I terminate application with bundle identifier `com.apple.mobilesafari`
Closes the mobile application and quits the remote session.
When I close mobile application
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.
When I send mobile application to background for `PT5S` period
Then number of elements found by `accessibilityId(login-button)` is equal to `1`
Changes the behavior of the Appium session.
When I change Appium session settings:$settings
-
$settings
- The settings to set.
When I change Appium session settings:
|name |value|
|allowInvisibleElements|true |
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.
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/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.
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
When I upload file with name `message.txt` and data `This is a message` to device
Then message file is displayed in file explorer
Deletes a file from the device/emulator/simulator.
When I delete file `$filePath` from device
Argument | Platform | Description | Examples |
---|---|---|---|
|
iOS |
The path to an existing remote file on the device. This variable can be prefixed with bundle id, so then the file will be deleted from the corresponding application container instead of the default media folder. Use |
|
Android |
The full path to the remote file or a file inside an application bundle |
|
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. |
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.
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`
Switches context to a mobile native context. See Automating hybrid apps for more information.
When I 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`
Taps on the element located by the locator.
The atomic actions performed are:
-
press on the element;
-
release.
When I tap on element located `$locator`
When I tap on element located by `$locator`
-
$locator
- [_locator].
When I tap on element located by `accessibilityId(menu-toggler)`
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 `$locator` with duration `$duration`
When I tap on element located by `$locator` with duration `$duration`
-
$locator
- [_locator]. -
$duration
- The duration between an element is pressed and released in {durations-format-link} format.
When I tap on element located by `accessibilityId(menu-toggler)` with duration `PT0.5S`
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].
When I double tap on element located by `accessibilityId(increment)`
Presses iOS keys or Android keys.
When I press $key key
-
$key
- The key to press.
When I press Home 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.
When I long press Home key
Presses a sequence of iOS keys or Android keys.
When I press keys:$keys
-
$keys
- The keys to press.
When I press keys:
|key|
|P |
|a |
|s |
|1 |
|$ |
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.
When I type text `pas1$`
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].
When I type `Bob` in field located `accessibilityId(username)`
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].
When I type `Bob` in field located `accessibilityId(username)` and keep keyboard opened
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].
When I clear field located `accessibilityId(username)`
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].
When I clear field located `accessibilityId(username)` and keep keyboard open
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. |
-
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 swipex
axis position in percentage from0
to100
, where0
corresponds tox=1
and100
corresponds tox = mobile screen width - 1
, default value is0
-
mobile-application.swipe.horizontal.y-position
- defines a horizontal swipey
axis position in percentage from0
to100
, where0
corresponds toy=1
and100
corresponds toy = mobile screen height - 1
, default value is50
When I swipe $direction to element located `$locator` with duration $swipeDuration
When I swipe $direction to element located by `$locator` with duration $swipeDuration
-
$direction
- The direction to swipe:UP
,DOWN
,LEFT
orRIGHT
. -
$locator
- [_locator]. -
$swipeDuration
- The swipe duration in {durations-format-link} format.
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`
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`
Executes the sequence of touch actions.
When I execute sequence of touch actions: $actions
-
Table 1. Possible actions$actions
- The table with actions to execute.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
|
When I execute sequence of touch actions:
|type |argument |
|TAP_AND_HOLD |By.id(Hello World)|
|MOVE_BY_OFFSET|(0,200) |
|RELEASE | |
Performs zoom in/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. |
Property Name | Acceptable values | Default value | Description |
---|---|---|---|
|
size in percentage |
|
The size of the top part of the context to be excluded from zoom area |
|
size in percentage |
|
The size of the bottom part of the context to be excluded from zoom area |
|
size in percentage |
|
The size of the right part of the context to be excluded from zoom area |
|
size in percentage |
|
The size of the left part of the context to be excluded from zoom area |
Warning
|
The indent percentage value should be from The sum of The sum of |
mobile-application.zoom.indent.top=30
mobile-application.zoom.indent.bottom=30
mobile-application.zoom.indent.right=20
mobile-application.zoom.indent.left=20
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
orPREVIOUS
. -
$offset
- The ofset to pick from a middle of the wheel, see Select Picker Wheel Value guide. -
$locator
- The locator to findXCUIElementTypePickerWheel
element.
When I select next value with `0.1` offset in picker wheel located `xpath(//XCUIElementTypePickerWheel)->filter.index(3)`
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.
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`
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 findXCUIElementTypeSlider
element. -
$percent
- The target value of the slider in percents.
When I set value of iOS slider located `xpath(//XCUIElementTypeSlider)` to `90` percents
When I set value of iOS slider located `xpath(//XCUIElementTypeSlider)` to `70` percents
When I set value of iOS slider located `xpath(//XCUIElementTypeSlider)` to `80` percents
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 findandroid.widget.SeekBar
element. -
$number
- The number to set on the slider
When I set value of Android slider located `xpath(//android.widget.SeekBar)` to `13`
When I set value of Android slider located `xpath(//android.widget.SeekBar)` to `25`
When I set value of Android slider located `xpath(//android.widget.SeekBar)` to `2`
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
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.
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`
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
orOFF
. -
$connectionName
- The name of the network connect to toggle.
Connection name | Supported platforms | Description |
---|---|---|
|
Android emulators, Android and iOS real devices |
Wi-Fi connection |
|
Android emulators, Android and iOS real devices |
Mobile Data connection |
|
Android real devices, Android emulators |
Airplane Mode |
|
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`. |
When I turn OFF `WIFI` network connection
When I turn OFF `WIFI` network connection
When I activate application with bundle identifier `my-application-bundle-id`