The plugin provides functionality to test mobile application on real devices, Android Emulators and iOS Simulators.
implementation(group: 'org.vividus', name: 'vividus-plugin-mobile-app', version: '{current-version}')| 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"$]) |
|
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=XCUITestThe 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=XCUITestThe 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=UIAutomator2The profile simplifies execution of tests against the local Appium server. It could be used in conjunction with: mobile_app/android, mobile_app/ios, mobile_app/tvos
The profile can be enabled by adding mobile_app/local to configuration.profiles property
Default profile configuration
selenium.grid.url=http://127.0.0.1:4723/wd/hub
selenium.grid.platformName=${selenium.grid.platform-name}
selenium.grid.automationName=${selenium.grid.automation-name}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 applicationStarts 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 gloablly-defined capabilities.
Given I start mobile application with capabilities:$capabilities-
$capabilities- The capabilities to start application with, these capabilies have higher priority than capabilities defined in*.propertiesfiles 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 namefor Android orBundle identifierfromPlist.infofor 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 namefor Android orBundle identifierfromPlist.infofor 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 namefor Android orBundle identifierfromPlist.infofor iOS
When I terminate application with bundle identifier `com.apple.mobilesafari`Closes the mobile application and quits the remote session.
When I close mobile applicationRuns mobile application in the backround 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 {iso-date-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 imageDeletes 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. |
|
Warning
|
This step is deprecated and will be removed in VIVIDUS 0.5.0. The replacement is [_switch_to_web_view_by_name]. |
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`-
$index- The index of the 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`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 contextThen 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`-
$locator- [_locator].
When I tap on element located `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`-
$locator- [_locator]. -
$duration- The duration between an element is pressed and released in {iso-date-format-link} format.
When I tap on element located `accessibilityId(menu-toggler)` with duration `PT0.5S`Presses iOS keys or Android keys.
When I press $key key-
$key- The key to press.
When I press Home keyPerforms 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 keyPresses 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 openedClears 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 openSwipes 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 swipexaxis position in percentage from0to100, where0corresponds tox=1and100corresponds tox = mobile screen width - 1, default value is0 -
mobile-application.swipe.horizontal.y-position- defines a horizontal swipeyaxis position in percentage from0to100, where0corresponds toy=1and100corresponds toy = mobile screen height - 1, default value is50
When I swipe $direction to element located `$locator` with duration $swipeDuration-
$direction- The direction to swipe:UP,DOWN,LEFTorRIGHT. -
$locator- [_locator]. -
$swipeDuration- The swipe duration in {iso-date-format-link} format.
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`Scenario: Switch slides
When I change context to element located `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`Selects a next or previous picker wheel value in date picker
-
Only
iOSplatform 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:NEXTorPREVIOUS. -
$offset- The ofset to pick from a middle of the wheel, see Select Picker Wheel Value guide. -
$locator- The locator to findXCUIElementTypePickerWheelelement.
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 findXCUIElementTypeSliderelement. -
$percent- The target value of the slider in percents.
When I set value of iOS slider located `xpath(//XCUIElementTypeSlider)` to `90` percentsWhen I set value of iOS slider located `xpath(//XCUIElementTypeSlider)` to `70` percentsWhen I set value of iOS slider located `xpath(//XCUIElementTypeSlider)` to `80` percentsSets 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.SeekBarelement. -
$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 `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:ONorOFF. -
$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 connectionWhen I turn OFF `WIFI` network connection
When I activate application with bundle identifier `my-aplication-bundle-id`