Mobile Application Plugin

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

Installation

  1. Copy the below line to dependencies section of the project build.gradle file

    Please make sure to use the same version for all VIVIDUS dependencies.
    Example 1. build.gradle
    implementation(group: 'org.vividus', name: 'vividus-plugin-mobile-app')
  2. If the project was imported to the IDE before adding new dependency, re-generate the configuration files for the used IDE and then refresh the project in the used IDE.

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

Reusable locators

Feature allows to define custom reusable locator types via properties. These new locator types should rely on one of the already existing ones.

Example 2. Properties
ui.locator.<locatorName>.pattern
ui.locator.<locatorName>.locator-type
  1. locatorName - The name of the reusable locator. Supported characters are A-Z, a-z, -, ..

  2. pattern - The pattern of the reusable locator.

  3. locator-type - The base locator type.

Example 3. Definition of custom locator
ui.locator.anyAttOrText.locator-type=xpath
ui.locator.anyAttOrText.pattern=//*[@*='%s' or text()='%s']
Example 4. Usage of custom locator
Given I am on main application page
Then number of elements found by `anyAttOrText(attribute, text)` is = `1`
Example 5. Usage of custom locator with comma in parameter
Given I am on main application page
Then number of elements found by `anyAttOrText(attribute, with comma\, text)` is = `1`
Description Pattern Usage Result

Single parameter doesn’t require comma escaping.

//[@='%1$s' or text()='%1$s']

customLocator(Hello, Vlad!)

//[@='Hello, Vlad!' or text()='Hello, Vlad!']

The pattern with a single parameter was referenced twice.

//[@='%1$s' or text()='%1$s']

customLocator(text)

//[@='text' or text()='text']

The pattern with a , in value.

//[@='%s' or text()='%s']

customLocator(te\,xt1, text2)

//[@='te,xt1' or text()='text2']

The pattern containing % character

//input[@id="username" and text()="%%%s"]

customLocator(admin)

//input[@id="username" and text()="%admin]

The pattern without parameters

//input[@id="username"]

customLocator()

//input[@id="username"]

The pattern with two parameter placeholders was used with invalid number of parameters.

//[@='%s' or text()='%s']

customLocator(text)

Exception will be thrown!

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'])

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

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

The properties marked with bold are mandatory.
Property Name Acceptable values Default Description

selenium.grid.host

hostname

<empty>

The host of Selenium Grid used to create a new session.

selenium.grid.username

username

<empty>

The username for authentication at Selenium Grid used to create a new session.

selenium.grid.password

password

<empty>

The password for authentication at Selenium Grid used to create a new session.

selenium.grid.retry-session-creation-on-http-connect-timeout

true
false

false

Whether to rety session creation at Selenium Grid in case of HTTP connect timeout. This flag may be useful when tests are executed via intermittent network connection.

selenium.grid.http.read-timeout

ISO-8601 Durations format

PT10M

The maximum amount of time to wait for HTTP response from Selenium Grid.

mobile-application.session-scope

story

scenario

story

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

Whether to publish the application source code on failure or not

ui.context.self-healing

true
false

false

If the value is set to true, an attempt to reset context will be performed when it becomes stale.

ui.wait.timeout

ISO-8601 Durations format

PT1M

Total duration to wait for UI condition

ui.wait.polling-period

ISO-8601 Durations format

PT2S

Used together with ui.wait.timeout. Total duration of time between two iterations of UI condition check

ui.report.image-compression-quality

The value between 0 and 1 e.g. 0.75

1

Enables compressions of the images published to the report using the specified compression quality. If 1 is set then no compression will be performed. It may help to decrease total report size.

selenium.grid.platform-name

Android

iOS

Depends on the set profile

Defines the mobile OS to use

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

proxy.enabled

true false

false

Enable proxy for the whole test run

proxy.recording.enabled

true false

false

Enable proxy recording

proxy.host

any host name resolving on the machine

<empty>

Overrides the host which will be used by proxy

proxy.ports

ports range (e.g., 10000-10005)

<empty>

Ports range which could be occupied for proxy

proxy.connectable-host

host.docker.internal

<empty>

Overrides the proxy host which will be passed to browser

proxy.publish-har-on-failure

true false

false

Enables publishing of attachments with HAR to each failed step. @noHarOnFailure meta tag can be used to disable HAR publishing at the story level.

proxy.trust-all-servers

true false

false

Whether to disable verification of upstream servers SSL certificates

proxy.capture-types

HAR capture types: REQUEST_HEADERS, REQUEST_COOKIES, REQUEST_CONTENT, REQUEST_BINARY_CONTENT, RESPONSE_HEADERS, RESPONSE_COOKIES, RESPONSE_CONTENT, RESPONSE_BINARY_CONTENT

REQUEST_CONTENT, RESPONSE_CONTENT, REQUEST_BINARY_CONTENT, RESPONSE_BINARY_CONTENT, REQUEST_HEADERS, RESPONSE_HEADERS

List of HAR capture types

proxy.mitm.enabled

true false

false

Whether to enable MITM proxy for the whole test run

proxy.mitm.mitm-manager-type

SELF_SIGNED IMPERSONATED

IMPERSONATED

The MITM type using the corresponding certificates. SELF_SIGNED MITM manager uses self-signed certificates that are generated lazily if the given keystore file doesn’t yet exist. Please note that certificates are usually generated in the current working directory

proxy.mitm.key-store.type

keystore type

JKS

The keystore type

proxy.mitm.key-store.path

path to keystore

<empty>

The relative to src/main/resources path to keystore

proxy.mitm.key-store.password

password for keystore

<empty>

The password for keystore

proxy.mitm.key-store.alias

keystore alias

<empty>

The alias for certificate entry in keystore

Meta Tags

@proxy - some steps require proxy to be turned on: it can be done by setting the corresponding properties or by switching on this meta tag at story level.

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

tvOS

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

Android

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

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.

Example 6. 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.

Example 7. 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}
Example 8. Verify clipboard content
Then `${clipboard-text}` is equal to `uarlouski@gmail.com`

Context element rectangle

Context element rectangle dynamic variables are deprecated and will be removed in VIVIDUS 0.7.0, please use Save size and coordinates of element step.

The set of dynamic variables provides ability to access context element coordinates, width and height.

The variables rely on the contextual approach: it is necessary to switch context to the target element.
In case of missing search context the error will be logged and -1 will be returned as a result

Variable name

Variable name Description

context-height

the height of the context element

context-width

the width of the context element

context-x-coordinate

the absolute X coordinate of the context element

context-y-coordinate

the absolute Y coordinate of the context element

Example 9. Check the size and the location of the image
When I change context to element located by `id(userpic)`
Then `${context-height}` is > `0`
Then `${context-width}` is > `0`
Then `${context-x-coordinate}` is > `0`
Then `${context-y-coordinate}` is > `0`

Context source code

Variable provides source code of the current UI context of the application under test.

${context-source-code}
Example 10. Firstly check frames on the entire page, and then links in the specified context
Given I am on main application page
Then all resources by selector `frame,iframe` from ${context-source-code} are valid
When I change context to element located by `id(linksList)`
Then all resources by selector `a` from ${context-source-code} are valid

Source code

Variable provides source code of the UI of the application under test.

The variable is deprecated and will be removed in VIVIDUS 0.7.0. Please use ${context-source-code} dynamic variable instead.

Variable name

${source-code}
Example 11. Check if element exists on UI
Then `${source-code}` matches `.+Home.+`

Steps

Application management

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.

Example 12. 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

Example 13. 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.

Example 14. 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). If the application is not running, new failed assertion is recorded.

When I terminate application with bundle identifier `$bundleId`
  • $bundleId - Package name for Android or Bundle identifier from Plist.info for iOS of the application to terminate.

Example 15. 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
Example 16. 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
Example 17. Configure to show invisible elements
When I change Appium session settings:
|name                  |value|
|allowInvisibleElements|true |

Device file management

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.

The destination folder on the device for the uploaded file is configured by mobile-environment.device.folder-for-file-upload property. See more information in the properties section.
Example 18. 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.

The destination folder on the device for the uploaded file is configured by mobile-environment.device.folder-for-file-upload property. See more information in the properties section.
Example 19. 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
Example 20. 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
Argument Platform Description Examples

$filePath

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 downloaded/deleted from the corresponding application container instead of the default media folder. Use @<app_bundle_id>:<optional_container_type>/<path_to_the_file_or_folder_inside_containe> format to download/delete a file from an application container of the given type. The only supported container type for real devices is documents. Containers available for Simulators: app, data, groups, <A specific App Group container>. If the container type is not set explicitly for a bundle id, then the default application container is going to be mounted (aka --container ifuse argument) e.g. If @com.myapp.bla:documents/111.png is provided, On My iPhone/<app name> in Files app will be mounted to the host machine. `@com.myapp.bla:documents/ means On My iPhone/<app name>.

/DCIM/100APPLE/image.png or @com.mycompany.myapp:documents/myfile.txt

Android

The full path to the remote file or a specially formatted path, which points to an item inside an app bundle, for example @my.app.id/my/path. It is mandatory for the app bundle to have debugging enabled in order to use the latter remotePath format.

/sdcard/myfile.txt or @my.app.id/path/in/bundle

Example 21. Delete file
When I delete file `/sdcard/Pictures/avatar.png` from device
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.
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`
Argument Platform Description Examples

$filePath

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 downloaded/deleted from the corresponding application container instead of the default media folder. Use @<app_bundle_id>:<optional_container_type>/<path_to_the_file_or_folder_inside_containe> format to download/delete a file from an application container of the given type. The only supported container type for real devices is documents. Containers available for Simulators: app, data, groups, <A specific App Group container>. If the container type is not set explicitly for a bundle id, then the default application container is going to be mounted (aka --container ifuse argument) e.g. If @com.myapp.bla:documents/111.png is provided, On My iPhone/<app name> in Files app will be mounted to the host machine. `@com.myapp.bla:documents/ means On My iPhone/<app name>.

/DCIM/100APPLE/image.png or @com.mycompany.myapp:documents/myfile.txt

Android

The full path to the remote file or a specially formatted path, which points to an item inside an app bundle, for example @my.app.id/my/path. It is mandatory for the app bundle to have debugging enabled in order to use the latter remotePath format.

/sdcard/myfile.txt or @my.app.id/path/in/bundle

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

Context management

The term "context" or "search context" refers to the area within which the element lookup is performed. By changing the context during the process of locating elements, it is possible to significantly streamline the creation and maintenance of tests. This helps to build more efficient and effective test cases, reducing the time spent interacting with unnecessary elements or searching the entire screen for the desired element.

Change context

Resets the context, finds the element by the given locator and sets the context to this element if it’s found.

When I change context to element located by `$locator`

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I change context to element located `$locator`
  • $locator - The locator used to find the element to change context to.

Example 23. Change context
Then number of elements found by `id(header)` is equal to `1`
When I change context to element located by `id(table)`
Then number of elements found by `id(header)` is equal to `0`

Change context within current context

Finds the element by the given locator in the current context and sets the context to this element if it’s found.

When I change context to element located by `$locator` in scope of current context

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I change context to element located `$locator` in scope of current context
  • $locator - The locator used to find the element to change context to.

Example 24. Change context in scope of the current context
Then number of elements found by `id(header)` is equal to `1`
When I change context to element located by `id(table)`
Then number of elements found by `id(header)` is equal to `0`
When I change context to element located `id(first-row)` in scope of current context
Then number of elements found by `id(table)` is equal to `0`

Reset context

Resets the context if it was set previously.

When I reset context
Example 25. Reset context behaviour
Then number of elements found by `id(header)` is equal to `1`
When I change context to element located by `id(table)`
Then number of elements found by `id(header)` is equal to `0`
When I reset context
Then number of elements found by `id(header)` is equal to `1`

Wait for tab and switch

Waits for a tab with desired title and switches to it.

When I wait `$duration` until tab with title that $comparisonRule `$title` appears and switch to it
Example 26. Wait for tab and switch to it
Given I am on page with URL `https://vividus-test-site-a92k.onrender.com/windows.html`
When I click on element located by `id(timeout)`
When I wait `PT3S` until tab with title that is equal to `Vividus test site` appears and switch to it

Elements validation

Validate elements number

Validates the context contains the number of elements matching the specified comparison rule.

Then number of elements found by `$locator` is $comparisonRule `$quantity`
  • $locator - The locator used to find elements.

  • $comparisonRule - The comparison rule.

  • $quantity - The expected number of the elements.

Example 27. Validate the number of elements
Then number of elements found by `xpath(./a)` is equal to `5`

Verify elements state

Verifies if the number of elements located by locator matches the number condition and all of them are in the 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 Visibility types are used and checked state are equal (For an example ':v' and 'VISIBLE') exception will be thrown. In such cases please use step: Validate elements number. Contradictory visibility parameters (locator - ':v' and checked state - 'NOT_VISIBLE') are also not allowed.
Then number of $state elements found by `$locator` is $comparisonRule `$quantity`
Example 28. Verify the number of elements in the state
Then number of VISIBLE elements found by `id(img)` is = `1`

Text content manupulations

Save the text of an element

Finds the element by the given locator and saves its text into a variable.

When I save text of element located by `$locator` to $scopes variable `$variableName`
  • $locator - The locator used to find the element whose text content will be saved.

  • $scopes - The comma-separated set of the variables scopes.

  • $variableName - The name of the variable to save the text content.

Example 29. Save the text of the header element
When I save text of element located by `id(header)` to scenario variable `heading-text`

Save the text of the context

Saves the text of the context element into a variable.

An error is thrown if the context is not set to the element.
When I save text of context element to $scopes variable `$variableName`
  • $scopes - The comma-separated set of the variables scopes.

  • $variableName - The name of the variable to save the text content.

Example 30. Save the text of the context element
When I change context to element located by `id(username)`
When I save text of context element to scneario variable `username`

Navigate back

Navigates back to the previous view.

When I navigate back

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`
Example 31. 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
Example 32. 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`
Example 33. 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`
Example 34. 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.

The step is supported for Android and iOS platforms.
When I double tap on element located by `$locator`
Example 35. 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.

Example 36. Go to Home screen
When I press Home key

Long press key

Performs long press of iOS keys or Android keys.

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.

Example 37. 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.

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

Type text sequentially

Types the provided text

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.

Example 39. Enter password
When I type text `pas1$`

Type text in a field

Types the text into the element located by the locator.

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.

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.

Example 40. 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.

Example 41. 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.

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`
Example 42. 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
Example 43. 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.

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
  • $direction - The direction to swipe: UP, DOWN, LEFT or RIGHT.

  • $locator - Locator.

  • $swipeDuration - The swipe duration in ISO-8601 Durations format.

Example 44. 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`
Example 45. 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 by `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

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_OFFSETRELEASE
Example 46. 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

Zoom in
zoom in
Zoom out
zoom out
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

zoom indent
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

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.

Example 47. 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

Example 48. 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.

Example 49. 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.

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).
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`
  1. $instrument - The instrument of Xcode Instruments utility. Some useful instruments: Time Profiler, Leaks, File Activity, etc.

  2. $path - The path to the file to save an archive with collected data.

Example 50. 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.

Example 51. Set value of iOS slider (with range 0:50) to 45
When I set value of iOS slider located `xpath(//XCUIElementTypeSlider)` to `90` percents
Example 52. Set value of iOS slider (with range -50:50) to 20
When I set value of iOS slider located `xpath(//XCUIElementTypeSlider)` to `70` percents
Example 53. 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

Example 54. 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`
Example 55. 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`
Example 56. 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`

Taking screenshot steps

Take screenshot

Takes a screenshot and publish it to the report.

When I take screenshot

Take screenshot and save it to the file

Takes a screenshot and saves it to the file at the specified path.

The full path to the file with the taken screenshot is posted to logs and report.
When I take screenshot and save it to file at path `$screenshotFilePath`

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I take screenshot and save it to folder `$screenshotFilePath`
  • $screenshotFilePath - The path to the file to save the screenshot, the allowed values are:

    • an absolute path to the file, e.g. C:\Windows\screenshot.png;

    • a relative path (it is resolved from the current working directory, e.g. screenshot.png.

Example 57. Take a screenshot and save it to the file
When I take screenshot and save it to file at path `${screenshot-directory}/start-page.png`

Wait for element appearance

Waits for appearance of the element by the locator.

It’s forbidden to use Visibility types in the locator.
When I wait until element located by `$locator` appears
Example 58. Wait for appearance of the element with the specified name
When I wait until element located by `id(welcome-image)` appears

Wait for element disappearance

Waits for disappearance of the element by the locator.

If the element doesn’t exist on the page/context, the step will immediately complete successfully. Checking the element on the page (if needed) should be done in a separate step (e.g. Wait for element appearance or Validate elements).
It’s forbidden to use Visibility types in the locator.
When I wait until element located by `$locator` disappears
Example 59. Wait for disappearance of the element with the specified name
When I wait until element located by `id(welcome-image)` disappears

Wait for element with specified state using polling interval

Waits for an element with the specified state to be found using the specified timeout with polling interval.

When I wait `$duration` with `$pollingDuration` polling until element located by `$locator` becomes $state
  • $duration - Total duration to wait in the ISO-8601 format.

  • $pollingDuration - The duration to wait between search retries in the ISO-8601 format.

  • $locator - The locator of the element to wait for state change.

  • $state - The element state.

Example 60. Verify that the element become invisible up to 10 times
When I wait `PT10S` with `PT1S` polling until element located by `id(element-to-hide)` becomes not visible

Wait for expected elements number

Waits for the expected number of elements located by locator.

In order to wait for invisible elements one rely on Visibility types.
When I wait until number of elements located by `$locator` is $comparisonRule $number
Example 61. Wait for the visible elements
When I wait until number of elements located by `tagName(img)` is equal to `5`
Example 62. Wait for the invisible elements
When I wait until number of elements located by `tagName(img):1` is equal to `5`

Wait for element to stop moving

Waits for element with the specified locator to stop moving.

An element is considered moving when its coordinates (position) are changing. For example, an animated GIF is not a moving element unless it changes position.
When I wait until element located by `$locator` stops moving
Example 63. Wait for element with the specified id to stop moving
When I wait until element located by `id(submitForm)` stops moving

Saves the attribute value of the context

Saves the attribute value of the context element into a variable.

Step will throw an error if the context element is not set.
When I save `$attributeName` attribute value of context element to $scopes variable `$variableName`
Example 64. Save the attribute value of the 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 the attribute value of the element

Saves the attribute value of the element located by locator into a variable.

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

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

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

Save the attribute value of the element

When I save `innerText` attribute value of element located by `id(username)` to SCENARIO variable `username`

Save number of elements

Saves number of elements located by locator into a variable.

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

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I save number of elements located `$locator` to $scopes variable `$variableName`
Example 65. Save number of elements
When I save number of elements located by `xpath(//a)` to scenario variable `numberOfLinks`
Then `${numberOfLinks}` is equal to `1`

Save size and coordinates of element

Saves the information about the size of an element and its coordinates relative to the viewport.

When I save coordinates and size of element located by `$locator` to $scopes variable `$variableName`
  • $locator - Locator.

  • $scopes - The comma-separated set of the variables scopes.

  • $variableName - The name of the variable to save the coordinates and size of an element which can be accessed on the variable name using dot notation (please see examples section):

    Attribute Description

    x

    the x coordinate

    y

    the y coordinate

    height

    the height of the element

    width

    the width of the element

Example 66. Verify image size and coordinates
When I save coordinates and size of element located by `tagName(img)` to scenario variable `rect`
Then `${rect.height}` is equal `400`
Then `${rect.width}` is equal `400`
Then `${rect.x}` is equal `200`
Then `${rect.y}` is equal `8`

Element existence during the time period

Validates the element located by the locator has existed for the period specified by the duration.

The actions performed by the step:

  • check the search context is set,

  • search for the element to validate existence (this search may include wait for element appearance if it’s configured),

  • validate the element has presented for the period specified by the duration.

Then element located by `$locator` exists for `$duration` duration
  • $locator - The Locator to find an element.

  • $duration - The period of time the element should have existed in ISO-8601 Durations format.

Example 67. The element should have existed for 5 second
Then element located by `id(banner)` exists for `PT5S` duration

Wait until element has text matching regular expression

Waits until an element with the specified locator has text that matches the provided regular expression.

When I wait until element located by `$locator` has text matching `$regex`
  • $locator - The Locator of the element which text to check.

  • $regex - The regular expression used to validate the text of the element.

Example 68. The element should have text consisting of numbers only
When I wait until element located by `id(indicator)` has text matching `\d+`

Verify elements order

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

Then elements located by `$locator` are sorted by text in $sortingOrder order
  • $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

Example 69. Check items are sorted
Given I am on page with 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

Scan barcode

Scan a barcode and save its value to the variable with the specified name. Only the first founded barcode will be scanned.

Supported Code Formats

1D product 1D industrial 2D
  • UPC-A

  • UPC-E

  • EAN-8

  • EAN-13

  • UPC/EAN Extension 2/5

  • RSS-14

  • RSS-Expanded

  • Code 39

  • Code 93

  • Code 128

  • Codabar

  • ITF

  • QR Code

  • Data Matrix

  • Aztec

  • PDF 417

  • MaxiCode

Actions performed at this step:

  • Takes a viewport screenshot

  • Scans a barcode from the screenshot and save its value to the variable

When I scan barcode from screen and save result to $scopes variable `$variableName`
Example 70. Scan a barcode
When I scan barcode from screen and save result to scenario variable `qrCodeLink`
Then `${qrCodeLink}` is equal to `https://www.example.com`

Perform steps while elements exist

Executes the steps while the found elements exist.

To avoid infinite loops the iterationLimit parameter is used. If iteration’s limit reached the step will fail.
When I find $comparisonRule `$number` elements `$locator` and while they exist do up to $iterationLimit iteration of$stepsToExecute

Alias:

When I find $comparisonRule '$number' elements $locator and while they exist do up to $iterationLimit iteration of$stepsToExecute
  • $comparisonRule - The comparison rule.

  • $number - The number of elements to find.

  • $locator - Locator.

  • $iterationLimit - The maximum number of iterations to perform.

  • $stepsToExecute - The ExamplesTable with a single column containing the steps to execute.

Example 71. Disable menus
When I find >= `0` elements `xpath(//*[@class='menu enabled'])` and while they exist do up to 10 iteration of
|step                                            |
|When I click on element located by `id(disable)`|

Execute JavaScript

Executes passed JavaScript code on the opened page via JavascriptExecutor.

When I execute javascript `$jsCode`
  • $jsCode - The JavaScript code.

Example 72. Click on the link using JavaScript
Given I am on page with URL `https://vividus-test-site-a92k.onrender.com`
When I execute javascript `document.querySelector('a').click()`

Execute JavaScript with arguments

Executes JavaScript via JavascriptExecutor. Step executes the script either without any arguments or with String or Object argument types.

When I execute javascript `$script` with arguments:$arguments
  • $script - The JavaScript code to execute.

  • $arguments - The examples table with set of arguments and their type:

    • value - The value of the argument.

    • type - The type of the argument. Either string or object.

Example 73. Remove noisy assistant
When I execute javascript `document.querySelector('#assistant').remove()` with arguments:
Example 74. Inject image
When I execute javascript `sauce:inject-image` with arguments:
|value                                                                                       |type  |
|iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=|string|
Example 75. Throttle CPU
When I execute javascript `sauce:throttleCPU` with arguments:
| value        | type   |
| {"rate" : 4} | object |

Execute JavaScript and save result.

Executes JavaScript code and saves result into variable.

When I execute javascript `$jsCode` and save result to $scopes variable `$variableName`
Example 76. Validate timings
Given I am on page with URL `https://vividus-test-site-a92k.onrender.com/`
When I execute javascript `return JSON.stringify(window.performance.timing)` and save result to scenario variable `timings`
Then number of JSON elements from `${timings}` by JSON path `$.connectStart` is = 1

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

1D product 1D industrial 2D
  • UPC-A

  • UPC-E

  • EAN-8

  • EAN-13

  • UPC/EAN Extension 2/5

  • RSS-14

  • RSS-Expanded

  • Code 39

  • Code 93

  • Code 128

  • Codabar

  • ITF

  • QR Code

  • Data Matrix

  • Aztec

  • PDF 417

  • MaxiCode

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`
Example 77. 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`

Proxy Steps

The maximum size the HAR file being published on failure is 40 MB, in case of exceeding the limit and getting an error please re-structure the scenarios to include Clear the recordings step.

Check the number of HTTP requests

This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level.

The actions preformed by the step:

  • extract HTTP messages from the recorded proxy archive

  • filter out the HTTP messages with the response status code 302 Moved Temporarily

  • find HTTP requests matching the provided HTTP methods and the URL regular expression

  • check that the total number of the found HTTP messages satisfies the desired condition

In case of failure the full HTTP archive (HAR) is attached to the report.

Then number of HTTP $httpMethods requests with URL pattern `$urlPattern` is $comparisonRule `$number`
  • $httpMethods - The comma-separated HTTP methods to filter by

  • $urlPattern - The regular expression to match HTTP request URL

  • $comparisonRule - Comparison Rule

  • $number - The number to compare with

Example 78. Check the number of HTTP GET and POST requests matching URL regular expression is equal to 1
Then number of HTTP GET, POST requests with URL pattern `http://httpbin\.org/get` is equal to `1`

Capture HTTP message

Save the HTTP message part from the HTTP request with given URL-pattern into the variable with specified name and the scopes.

This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level.

The actions preformed by the step:

  • extract HTTP messages from the recorded proxy archive

  • filter out the HTTP messages with the response status code 302 Moved Temporarily

  • find HTTP requests matching the provided HTTP methods and the URL regular expression

  • check that total number of the found HTTP messages is equal to 1

  • save the HTTP message part to the specified variable

In case of failure the full HTTP archive (HAR) is attached to the report.

When I capture HTTP $httpMethods request with URL pattern `$urlPattern` and save $httpMessagePart to $scopes variable `$variableName`
  • $httpMethods - The "or"-separated set of HTTP methods to filter by, e.g. GET or POST or PUT.

  • $urlPattern - The regular expression to match HTTP request URL.

  • $httpMessagePart - The HTTP message part to save. One of:

    • URL - The request URL.

    • URL query - The request URL query parameters.

    • request data - The request data includes the following keys:

      • query - The URL query is stored as a collection of key and value pairs, where key is the name of the query parameter and value is the list of query parameter values. The query parameter values are accessible via zero-based index.

      • requestBody.mimeType - The MIME type of posted data, the variable will not be saved if MIME type is not present.

      • requestBody.text - The posted data as plain text, the variable will not be saved if the request body is not present.

      • requestBodyParameters - The form data parameters are stored as a collection of key and value pairs, where key is the name of the form parameter and value is the list of form parameter values. The form parameter values are accessible via zero-based index.

      • responseStatus - The response status, the variable will not be saved if the response is not present.

    • response data - The response data includes the following keys:

      • responseBody.mimeType - The MIME type of response data, the variable will not be saved if MIME type is not present.

      • responseBody.text - The response data as plain text, the variable will not be saved if the response body is not present.

  • $scopes - The comma-separated set of the variables scopes.

  • $variableName - The variable name to save the HTTP message part.

Example 79. Validate the URL of the matching HTTP request
Given I start mobile application
When I capture HTTP GET or POST request with URL pattern `.*/search.*=vividus` and save URL to scenario variable `URL`
Then `${URL}` is equal to `https://www.google.com/search?q=vividus`
Example 80. Validate the URL query of the matching HTTP request
Given I start mobile application
When I capture HTTP GET request with URL pattern `.*/search.*=vividus` and save URL query to scenario variable `query`
Then `${query.q[0]}` is equal to `vividus`
Then `${query.q}` is equal to `[vividus]`
Then `${query}` is equal to `{q=[vividus]}`
Example 81. Validate the request data from the matching HTTP message
Given I start mobile application
When I capture HTTP GET request with URL pattern `https://www.google.com/search?q=vividus` and save request data to scenario variable `data`
Then `${data.query}` is equal to `{}`
Then `${data.requestBodyParameters}` is equal to `{delivery=, custtel=, comments=, custemail=, custname=}`
Then `${data.requestBody}` is not equal to `null`
Then `${data.responseStatus}` is equal to `200`
Example 82. Validate the response data from the matching HTTP message
Given I start mobile application
When I capture HTTP GET request with URL pattern `https://www.google.com/search?q=vividus` and save request data to scenario variable `data`
Then `${data.responseBody.text}` is equal to `{"status": "ok"}`
Then `${data.responseBody.mimeType}` is equal to `application/json`

Wait for the HTTP request

This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level. Waits for the HTTP requests matching the provided HTTP methods and URL regular expression. If no HTTP request is sent and wait timeout is reached, then the step will fail.

When I wait until HTTP $httpMethods request with URL pattern `$urlPattern` is captured

Deprecated syntax (will be removed in VIVIDUS 0.8.0):

When I wait until HTTP $httpMethods request with URL pattern `$urlPattern` exists in proxy log
  • $httpMethods - the "or"-separated HTTP methods to filter by, e.g. 'GET or POST or PUT'

  • $urlPattern - the regular expression to match HTTP request URL

Example 83. Wait for the HTTP request
Given I start mobile application
When I wait until HTTP GET or POST request with URL pattern `https://www.google.com/search?q=vividus` is captured
Then number of HTTP GET or POST requests with URL pattern `https://www.google.com/search?q=vividus` is equal to `1`

Add headers to the HTTP request

This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level. Add headers to the proxied HTTP request satisfying the desired condition

When I add headers to proxied requests with URL pattern which $comparisonRule `$url`:$headers
  • $comparisonRule - String comparison rule

  • $url - The input value of URL to filter by

  • $headers - The ExamplesTable representing the list of the headers with columns "name" and "value" specifying HTTP header names and values respectively

Example 84. Add headers to the proxied HTTP request
When I add headers to proxied requests with URL pattern which is equal to `https://www.google.com/search?q=vividus`:
|name     |value     |
|testName1|testValue1|
|testName2|testValue2|
Given I start mobile application
Then a JSON element from '${response}' by the JSON path '$.headers' is equal to '
{
    "Testname1": "testValue1",
    "Testname2": "testValue2"
}
'ignoring extra fields

Clear the recordings

This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level. The step clears the HTTP requests and responses recorded by the proxy

When I clear network recordings

Deprecated syntax (will be removed in VIVIDUS 0.8.0):

When I clear proxy log
Example 85. Clear the data recorded by the proxy
Given I start mobile application
When I clear network recordings
Then number of HTTP GET requests with URL pattern 'https://www.google.com/search?q=vividus' is equal to `0`

Clear the mocks

This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level. The step clears previously created mocks

When I clear proxy mocks
Example 86. Clear the proxy mocks
When I mock HTTP responses with request URL which CONTAINS `vividus` using response code `200`, content `#{loadResource(page.html)}` and headers:
|name        |value    |
|Content-Type|text/html|
When I clear proxy mocks
Given I start mobile application
Then number of elements found by `id(sw)` is = `0`

Mock the HTTP response by methods with content

This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level. Mocks HTTP response by methods with a provided content

No actual request will be executed. Short-circuited response will be returned.
When I mock HTTP $httpMethods responses with request URL which $comparisonRule `$url` using response code `$responseCode`, content `$payload` and headers:$headers
  • $httpMethods - The "or"-separated set of HTTP methods to filter by, e.g. GET or POST or PUT.

  • $rule - String comparison rule

  • $url - The input value of URL to filter by

  • $code - The response status code

  • $content - The content to send within a response

  • $headers - The ExamplesTable representing the list of the headers with columns "name" and "value" specifying HTTP header names and values respectively

Example 87. Hijack a page
When I mock HTTP POST responses with request URL which CONTAINS `example` using response code `202`, content `#{loadResource(mocked-example.json)}` and headers:
|name        |value           |
|Content-Type|application/json|

Mock the HTTP response with content

This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level. Mocks HTTP response with a provided content

No actual request will be executed. Short-circuited response will be returned.
When I mock HTTP responses with request URL which $comparisonRule `$url` using response code `$responseCode`, content `$payload` and headers:$headers
  • $rule - String comparison rule

  • $url - The input value of URL to filter by

  • $code - The response status code

  • $content - The content to send within a response

  • $headers - The ExamplesTable representing the list of the headers with columns "name" and "value" specifying HTTP header names and values respectively

Example 88. Hijack a page
When I mock HTTP responses with request URL which CONTAINS `example.com` using response code `200`, content `#{loadResourceAsByteArray(page.html)}` and headers:
|name        |value    |
|Content-Type|text/html|

Mock the HTTP response without content

This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level. Mocks HTTP response

No actual request will be executed. Short-circuited response will be returned.
When I mock HTTP responses with request URL which $comparisonRule `$url` using response code `$responseCode` and headers:$headers
  • $rule - String comparison rule

  • $url - The input value of URL to filter by

  • $code - The response status code

  • $headers - The ExamplesTable representing the list of the headers with columns "name" and "value" specifying HTTP header names and values respectively

Example 89. 404 page
When I mock HTTP responses with request URL which CONTAINS `example.com` using response code `404` and headers:
|name          |value|
|Content-Length|0    |

Change network connection

Turns ON/OFF network connection.

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

For iOS real devices: to return to the application you must use the step:

When I activate application with bundle identifier `$bundleId`.
Example 90. Turn OFF Wi-Fi for Android
When I turn OFF `WIFI` network connection
Example 91. 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.

Example 92. Change the device screen orientation
When I change device screen orientation to portrait