Mobile Application Plugin
The plugin provides functionality to test mobile application on real devices, Android Emulators and iOS Simulators
Installation
implementation(group: 'org.vividus', name: 'vividus-plugin-mobile-app', version: '0.3.2-SNAPSHOT')
Locator
By.<locatorType>(<locatorValue>):<visibility>->filter.<filterType>(<filterValue>)
By. prefix is optional. |
-
locatorType
- [mandatory] type of the locator -
locatorValue
- [mandatory] value of the locator -
visibility
- [optional] visibility of element (visible by default) -
filterType
- [optional] type of the filter -
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 |
|
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) |
iOS Class Chain |
|
See Class Chain Queries for more details |
iosClassChain(**/XCUIElementTypeCell[$name BEGINSWITH "A"$]) or By.iosClassChain(**/XCUIElementTypeCell[$name BEGINSWITH "B"$]) |
Properties
Property Name | Acceptable values | Default | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|
|
|
Defines the test lifecycle of the mobile application:
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 |
||||||||
|
|
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
|
Profiles
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 |
---|---|---|
|
|
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`
Steps
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
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
Tap on element
Info
Taps on the element located by the locator.
The atomic actions performed are: * press on the element * release
Parameters
-
$locator
- Locator
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.
|
Parameters
-
$text
- text to type into the element -
$locator
- Locator
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.
|
Parameters
-
$locator
- Locator
Swipe to an 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
Usage
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`
Activate mobile application
Verify elements number
Parameters
-
$locator
- Locator -
$comparisonRule
- Comparison rule -
$quantity
- expected number of elements
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 |
Parameters
-
$state
- State -
$locator
- Locator -
$comparisonRule
- Comparison rule -
$quantity
- expected number of elements
Wait for element appearance
Parameters
-
$locator
- Locator
Wait for element disappearance
Parameters
-
$locator
- Locator
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 |
Parameters
-
$scopes
- The set of variable’s scope -
$variableName
- name of a variable
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
-
$attributeName
- name of an element’s attribute -
$scopes
- The set of variable’s scope -
$variableName
- name of a variable
Save attribute value of element
Wording
When I save `$attributeName` attribute value of element located `$locator` to $scopes variable `$variableName`
Parameters
-
$attributeName
- name of an element’s attribute -
$locator
- Locator -
$scopes
- The set of variable’s scope -
$variableName
- name of a variable
Save number of elements
Parameters
-
$locator
- Locator -
$scopes
- The set of variable’s scope -
$variableName
- name of a variable
Change context
Info
Changes the context to an element located by locator for limiting area of subsequent UI interactions
Parameters
-
$locator
- Locator
Reset context
Usage
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`
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.
Parameters
-
$locator
- Locator -
$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 |
Change session settings
Parameters
-
$settings
- Settings
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
Parameters
-
$direction
- next value to select, eitherNEXT
orPREVIOUS
-
$offset
- offset for pick from a middle of a wheel, see Select Picker Wheel Value -
$locator
- locator to locateXCUIElementTypePickerWheel
element
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`
-
$index
- index of a 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
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`
Verify elements number
Parameters
-
$locator
- Locator -
$comparisonRule
- Comparison rule -
$quantity
- expected number of elements
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 |
Parameters
-
$state
- State -
$locator
- Locator -
$comparisonRule
- Comparison rule -
$quantity
- expected number of elements
Wait for element appearance
Parameters
-
$locator
- Locator
Wait for element disappearance
Parameters
-
$locator
- Locator
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 |
Parameters
-
$scopes
- The set of variable’s scope -
$variableName
- name of a variable
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
-
$attributeName
- name of an element’s attribute -
$scopes
- The set of variable’s scope -
$variableName
- name of a variable
Save attribute value of element
Wording
When I save `$attributeName` attribute value of element located `$locator` to $scopes variable `$variableName`
Parameters
-
$attributeName
- name of an element’s attribute -
$locator
- Locator -
$scopes
- The set of variable’s scope -
$variableName
- name of a variable
Save number of elements
Parameters
-
$locator
- Locator -
$scopes
- The set of variable’s scope -
$variableName
- name of a variable
Change context
Info
Changes the context to an element located by locator for limiting area of subsequent UI interactions
Parameters
-
$locator
- Locator
Reset context
Usage
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`
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.
Parameters
-
$locator
- Locator -
$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 |