Web Application Plugin

The plugin provides functionality to interact with Web applications.

plugins:partial$plugin-web-app-locators.adoc

Properties

Note	The properties marked with bold are mandatory.

Property Name	Acceptable values	Default	Description
`selenium.grid.platform-name`	Valid target platform name	empty	Identifies the operating system for the testing. e.g. `Windows`
`selenium.grid.platform-version`	Valid target platform version	empty	Identifies the operating system version for the testing. e.g. `10` partial$selenium-properties.adoc partial$proxy-properties.adoc
`screenshot.on-failure.debug-modes`	`proxy`	`<empty>`	Provides possibility to attach screenshot for failed proxy steps
`web.driver.<browser-name>.command-line-arguments`	string with arguments	`<empty>`	The command line (CLI) arguments to use when starting browser. `<browser-name>` is one of the browsers supporting CLI arguments: `CHROME` `FIREFOX`, `IEXPLORE`.
`web-application.sticky-header-size-percentage`	header size as a viewport size percent	`25`	Before the click VIVIDUS scrolls element into the viewport, the property defines top edge indent in viewport percent for the scroll

How to configure user preferences for Chrome browser?

In addition to the command line arguments, user preferences (see the Preferences file in Chrome’s user data directory or open chrome://prefs-internals/ link in Chrome browser for examples) can be customised.

Here is an example how to configure third-party cookies behaviour.

Add the following property to allow all cookies

web.driver.CHROME.experimental-options={"prefs": {"profile": {"cookie_controls_mode": 0}}}

The allowed values for the preference from the example are:

0 - allow all cookies;
1 - block third-party cookies;
2 - block third-party cookies in Incognito mode only.

partial$proxy-meta-tags.adoc

Dynamic variables

Browser window dimension

The set of dynamic variables provides ability to access height and width of the browser window.

Variable name

Variable name	Description
`browser-window-height`	the height of the browser window
`browser-window-width`	the width of the browser window

Check the dimension of the browser window

When I change window size to `800x600`
Then `${browser-window-width}` is = `800`
Then `${browser-window-height}` is = `600`

partial$dynamic-variables-ui.adoc

plugins:partial$plugin-web-app-profiles.adoc

Steps

plugins:partial$plugin-web-app-steps.adoc

Wait for window and switch

Waits for the windows with desired title and switches to it.

When I wait `$duration` until window with title that $comparisonRule `$windowTitile` appears and switch to it

$duration - The timeout duration to wait for a window in {iso-date-format-link} format.
$comparisonRule - The window title comparison rule.
$windowTitle - The expected window title.

Wait for window and switch to it

Given I am on a page with the URL 'https://vividus-test-site.onrender.com/windows.html'
When I click on element located by `id(timeout)`
When I wait `PT3S` until window with title that is equal to `Vividus test site` appears and switch to it

Stop page loading

Stops page loading

When I stop page loading

Tip	Could be useful in combination with Selenium’s page load strategy

Stop page loading.story

When I open URL `https://delayed.vividus.dev` in new window
When I stop page loading

Configure page load timeout

Sets a custom page load timeout for a part of the story

When I set page load timeout to `$duration`

$duration - total duration to wait for page load completion in {iso-date-format-link} format

Before loading a heavy page set an increased timeout

Given I am on a page with the URL 'https://example.com/'
When I set page load timeout to `PT20S`
When I open URL `https://example.com/super-heavy-page` in new window
When I set page load timeout to `PT10S`

Performance metrics

Checks web performance metrics.

Then metric $webPerformanceMetric is $comparisonRule `$duration`

$webPerformanceMetric - The web performance metric. Where:
- TIME_TO_FIRST_BYTE - The time between the navigation start and the response start.
- DNS_LOOKUP_TIME - The time between the domain lookup start and the domain lookup end.
- DOM_CONTENT_LOAD_TIME - The time between the DOM loading and the the DOM complete.
- PAGE_LOAD_TIME - The time between the navgation start and the load event end.
$comparisonRule - The duration comparison rule.
$duration - The duration to compare against in {iso-date-format-link} format.

Check page load

Given I am on a page with the URL 'https://example.com'
Then metric PAGE_LOAD_TIME is less than `PT5S`

partial$generic-ui-steps.adoc

Scan barcode from context

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

Supported Code Formats

partial$code-formats.adoc

Actions performed at this step:

Takes a screenshot of the specified context. If it’s not set - takes a screenshot of the entire page
Scans a barcode from the screenshot and save its value to the variable

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

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

Scan the barcode

When I change context to element located `By.xpath(//div[@id='qrCode'])`
When I scan barcode from context and save result to scenario variable `qrCodeLink`
Then `${qrCodeLink}` is equal to `https://www.example.com`

Field Steps

Fields are elements where users can enter data. The most typical fields are:

input,
textarea,
CKE editor (it usually should be located via body tag, that is contained in a frame as a separate HTML document).

Enter text in field

Enters the text in a field found by the specified locator.

The atomic actions performed are:

find the field by the locator;
clear the field if it is found, otherwise the whole step is failed and its execution stops;
type the text in the field;
the first three actions are retried once if the field becomes stale during actions execution in other words if StaleElementReferenceException is thrown at any atomic action.

When I enter `$text` in field located by `$locator`

$text - The text to enter in the field.
$locator - The locator used to find field.

Add text 'pa$$w0rd' in password field

When I enter `pa$$w0rd` in field located by `id(password)`

Add text to field

Enters the text in the field found by the specified locator without clearing of the previous content.

When I add `$text` to field located by `$locator`

$text - The text to add to the field.
$locator - The locator used to find field.

Add text 'name' to username field

When I add `name` to field located by `id(username)`

Clear field

Clears the field found by the specified locator. The step does not trigger any keyboard or mouse events on the field.

When I clear field located by `$locator`

$locator - The locator used to find field.

Clear username field

When I clear field located by `id(username)`

Clear field using keyboard

Clears the field found by the specified locator using keyboard. The step simulates user action by pressing buttons kbd:[Ctrl+A] and then kbd:[Backspace] that allows to trigger keyboard events on the field.

When I clear field located by `$locator` using keyboard

$locator - The locator used to find field.

Clear password field using keyboard

When I clear field located by `id(password)` using keyboard

Dropdown Steps

Validate available options

Validates whether the dropdown located by locator exists and contains the list of the expected options.

Then dropdown located `$locator` contains options: $option

$locator - The locator used to find dropdown.
$options - examples table describing expected options

Validate dropdown contains a set of colors

Then a drop down with the name 'colors' contains the items:
|state|item |
|false|Red  |
|false|Green|
|true |Blue |

Important

The item is an option. The state (true or false) specifies whether the item is selected.

Validate the first selected option

Verifies if dropdown located by locator exists and first selected option.

Then dropdown located `$locator` exists and selected option is `$option`

$locator - The locator used to find dropdown.
$option - first selected option

Dropdown.story

Then dropdown located `id(colors)` exists and selected option is `Blue`

Add an option to the mutli-select dropdown

Selects option in multi-select dropdown

Important

Step will fail if target dropdown is not multi-select

When I add `$option` to selection in dropdown located `$locator`

$option - option to select
$locator - The locator used to find dropdown.

Dropdown.story

When I add `Two` to selection in dropdown located `id(numbers)`

Select the option

Selects option in dropdown

Important

Does not support multi-selection

When I select `$option` in dropdown located `$locator``

$option - option to select
$locator - The locator used to find dropdown.

Dropdown.story

When I select `Red` in dropdown located `id(colors)`

Cookie Steps

Validate cookie presence

Validates whether the certain cookie is set.

Then cookie with name `$cookieName` is set

$cookieName - The name of the cookie to check presence.

Check the session cookie is present

Then cookie with name `JSESSIONID` is set

Validate cookie absence

Validates whether the certain cookie is not set.

Then cookie with name `$cookieName` is not set

$cookieName - The name of the cookie to check absence.

Check the session cookie is not present

Then cookie with name `JSESSIONID` is not set

Set cookies

Adds the cookies provided in the input ExamplesTable. It’s allowed to add the cookies for the current domain only: make sure the web browser is opened at the expected domain. The actions performed by the step:

add the cookies;
refresh the current page (this action is required to apply the changes in cookies).

When I set all cookies for current domain:$parameters

$parameters - The parameters of the cookies to set as ExamplesTable:

Column Name Description

cookieName

the name of the cookie to set

cookieValue

the value of the cookie to set

path

the path of the cookie to set

Set the cookie for the current domain

When I set all cookies for current domain:
|cookieName   |cookieValue |path |
|cookieAgreed |2           |/    |

Get cookie value

Finds the cookie by the name and saves its value to a variable.

When I save value of cookie with name `$cookieName` to $scopes variable `$variableName`

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

Get the value of the session cookie

When I save value of cookie with name `JSESSIONID` to scenario variable `session-id`

Get cookie

Finds the cookie by the name and saves all its parameters as JSON to a variable.

When I save cookie with name `$cookieName` as JSON to $scopes variable `$variableName`

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

Get the session cookie

When I save cookie with name `JSESSIONID` as JSON to scenario variable `session-id`

Remove cookie

Removes the certain cookie from the current domain. The actions performed by the step:

remove the certain cookie the from current domain;
refresh the current page (this action is required to apply the changes in cookies).

When I remove cookie with name `$cookieName` from current domain

$cookieName - The name of the cookie to remove.

Remove the session cookie

When I remove cookie with name `JSESSIONID` from current domain

Remove cookie without apply

Removes the certain cookie from the current domain, but does not apply the changes in cookies. The current page must be refreshed or the navigation must be performed to apply the cookie changes.

When I remove cookie with name `$cookieName` from current domain without applying changes

$cookieName - The name of the cookie to remove.

Remove the session cookie

When I remove cookie with name `JSESSIONID` from current domain without applying changes
When I refresh the page

Remove all cookies

Removes all cookies from the current domain. The actions performed by the step:

remove all cookies from the current domain;
refresh the current page (this action is required to apply the changes in cookies).

When I remove all cookies from current domain

Remove all cookies without apply

Removes all cookies from the current domain, but does not apply the changes in cookies. The current page must be refreshed or the navigation must be performed to apply the cookie changes.

When I remove all cookies from current domain without applying changes

Web Storage steps

Get web storage item

Finds the web storage item by the key and saves its value to the variable.

When I save $storageType storage item with key `$key` to $scopes variable `$variableName`

$storageType - One of the web storage mechanisms: either local or session.
$key - The name of the key to retrieve the value of.
$scopes - The comma-separated set of the variables scopes.
$variableName - The name of the variable to store the value of the web storage item.

Get the value of the local storage item

When I save local storage item with key `token` to scenario variable `application-token`

Set web storage item

Adds the item with the specified key-value pair to the web storage, or updates that key’s value if it already exists.

When I set $storageType storage item with key `$key` and value `$value`

$storageType - One of the web storage mechanisms: either local or session.
$key - The name of the key to create/update.
$value - The value to give the key that is creating/updating.

Set the session storage item

When I set session storage item with key `token` and value `session-token`

Validate web storage item presence

Validates the web storage item with the specified key exists.

Then $storageType storage item with key `$key` exists

$storageType - One of the web storage mechanisms: either local or session.
$key - The name of the key to check presence.

Check the session storage item is present

Then session storage item with key `token` exists

Validate web storage item absence

Validates the web storage item with the specified key does not exist.

Then $storageType storage item with key `$key` does not exist

$storageType - One of the web storage mechanisms: either local or session.
$key - The key of the local storage item to check absence.

Check the local storage item is not present

Then local storage item with key `token` does not exist

partial$proxy-steps.adoc

Window Steps

Resize the current browser window

Changes the current browser window size to the specified one.

Important

The specified browser window size should be smaller than the current screen resolution.

When I change window size to `$targetSize`

$targetSize - The desired browser window size in pixels, e.g. 800x600, where the first measure is window width, the last one is window height.

Resize the browser window

Given I am on a page with the URL 'https://example.com/'
When I change window size to `640x320`

Video steps

Steps allow to interact with video elements.

Play Video

Starts video playback.

When I play video in video player located `$locator`

$locator - The locator used to find video player.

Pause Video

Pauses video playback.

When I pause video in video player located `$locator`

$locator - The locator used to find video player.

Rewind Video

Rewinds video to the desired mark in seconds.

When I rewind time to `$number` seconds in video player located `$locator`

$number - time mark in seconds
$locator - The locator used to find video player.

Get info

Saves video player info: duration, currentTime, src, networkState. For more information about the properties see HTML Audio/Video Properties

When I save info from video player located `$locator` to $scopes variable `$variableName`

$locator - The locator used to find video player.
$scopes - The comma-separated set of the variables scopes.
$variableName - The variable name to save the info. If the variable name is info, the following variables will be created:
- ${info.src}- The current source of the audio/video element
- ${info.duration} - The length of the current audio/video (in seconds)
- ${info.currentTime} - The current playback position in the audio/video(in seconds)
- ${info.networkState} - The current network state of the audio/video. For more information see: Network State

Video player verifications

Given I am on a page with the URL 'https://www.youtube.com/watch?v=pYqyVpCV-3c'
When I pause video in video player located `cssSelector(video)`
When I rewind time to `777` seconds in video player located `cssSelector(video)`
When I play video in video player located `cssSelector(video)`
When I save info from video player located `cssSelector(video)` to SCENARIO variable `info`
Then `${info.currentTime}` is > `0`
Then `${info.duration}` is > `1000`
Then `${info.networkState}` is = `2`
Then `${info.src}` matches `.+youtube.+`

Browser Configuration Steps

Set the browser command line arguments

Allows to set command line arguments for browsers. This step works similar to the property

web.driver.<browser-name>.command-line-arguments

In case both property and step are used - arguments from property will be ignored. Step will take effect for all new browser sessions created in the current story. It will not affect the current sessions.

List of supported command line arguments for popular browsers: . Chrome . Firefox . Internet Explorer

Not supported browsers: . Safari . Edge

When I set browser command line arguments to `$argsString`

$argsString - Sequence of command line arguments, separated by space.

Set the browser to use the mocked camera stream

When I set browser command line arguments to `--use-fake-ui-for-media-stream --use-file-for-fake-video-capture=${videoStorage}/${video1}.y4m --use-fake-device-for-media-stream`
Given I am on the main application page

Code steps

Execute async JavaScript and save result.

Executes async JavaScript code and saves result into variable.

When I execute async javascript `$jsCode` and save result to $scopes variable `$variableName`

$jsCode - Any JavaScript code. In order to save a result return statement should be used.
$scopes - The comma-separated set of the variables scopes.
$variableName - The variable name to save the cookie value.

Validate response

When I execute async javascript `
var callback = arguments[arguments.length - 1];
var xhr = new XMLHttpRequest();
xhr.open('GET', '/resource/data.json', true);
xhr.onreadystatechange = function() {
  if (xhr.readyState == 4) {
    callback(xhr.responseText);
  }
};
xhr.send();` and save result to scenario variable `response`
Then `${response}` matcher `.+`

Element wait steps

Wait for disappearance of an element with a tag

Warning

The step is deprecated and will be removed in VIVIDUS 0.6.0. The replacement is a generic step waiting for element disappearance.

Waits for an element with the specified tag, attribute type and value disappearance.

Actions performed by step:

Searches for an element with the specified attribute and tag within search context
If there are no elements by specified attribute and tag, step provides passed assertion and don’t check disappearance of an element
If there are elements by specified attribute and tag, waits until this element becomes not visible

Note	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).

When I wait until an element with the tag '$elementTag' and attribute '$attributeType'='$attributeValue' disappears

$elementTag - Type of the html tag (e.g. div or iframe).
$attributeType - Type of the tag attribute (e.g. name or id).
$attributeValue - Value of the attribute.

Click on the button and waiting for disappearance of the div element with a certain attribute and value

When I click on a button with the name 'Toggle element visibility with delay'
When I wait until an element with the tag 'div' and attribute 'id'='delayed' disappears

Wait for element disappearance with timeout

Waits for element disappearance with desired timeout.

Note	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).

Then element located by `$locator` disappears in `$timeout`

Deprecated syntax (will be removed in VIVIDUS 0.6.0):

Then element located '$locator' disappears in '$timeout'

$locator - The locator used to element.
$timeout - The maximum time to wait for the element disappearance in {iso-date-format-link} format.

Click on the button and waiting for disappearance of the element for 3 seconds

When I click on a button with the name 'Toggle element visibility with delay'
Then element located 'By.xpath(//div[@id='delayed'])' disappears in 'PT3S'

Column Name	Description
`cookieName`	the name of the cookie to set
`cookieValue`	the value of the cookie to set
`path`	the path of the cookie to set

Files

plugin-web-app.adoc

Latest commit

History

plugin-web-app.adoc

File metadata and controls

Web Application Plugin

Properties

How to configure user preferences for Chrome browser?

Dynamic variables

Browser window dimension

Variable name

Steps

Wait for window and switch

Stop page loading

Configure page load timeout

Performance metrics

Scan barcode from context

Field Steps

Enter text in field

Add text to field

Clear field

Clear field using keyboard

Dropdown Steps

Validate available options

Validate the first selected option

Add an option to the mutli-select dropdown

Select the option

Cookie Steps

Validate cookie presence

Validate cookie absence

Set cookies

Get cookie value

Get cookie

Remove cookie

Remove cookie without apply

Remove all cookies

Remove all cookies without apply

Web Storage steps

Get web storage item

Set web storage item

Validate web storage item presence

Validate web storage item absence

Window Steps

Resize the current browser window

Video steps

Play Video

Pause Video

Rewind Video

Get info

Browser Configuration Steps

Set the browser command line arguments

Code steps

Execute async JavaScript and save result.

Element wait steps

Wait for disappearance of an element with a tag

Wait for element disappearance with timeout