Web Application Plugin

The plugin provides functionality to interact with Web applications.

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-web-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.

Profiles

The profiles allow to choose and/or parameterize browser that tests run on.

Desktop

The following profiles running desktop browsers are available out of the box:

  • web/desktop/chrome

  • web/desktop/edge

  • web/desktop/firefox

  • web/desktop/iexplore

    Since Internet Explorer 11 has retired and is officially out of support, this profile is deprecated and will be removed in VIVIDUS 0.8.0.

  • web/desktop/opera

    In order to run tests in Opera browser locally, it is required to configure browser path.
  • web/desktop/safari

Headless

Headless mode is a functionality that allows the execution of a full version of the browser while controlling it programmatically. It can be used without dedicated graphics or display, meaning that it runs without its “head”, the Graphical User Interface (GUI). The following profiles running browsers in headless mode are available:

  • web/headless/chrome

    Profile-specific properties Format Default value Description

    web.headless.chrome.window-size

    width,height

    800,600

    Sets the initial window size.

    This property is ignored when custom CLI arguments are set using web.driver.chrome.command-line-arguments property.
  • web/headless/firefox

  • web/headless/edge

Mobile emulation

  1. Built-in devices

    Chrome allows to emulate view on mobile devices using Device mode. Such feature is reflected in mobile_emulation subdirectory in Profiles. Use device-name property to mention target device:

    web.driver.chrome.mobile-emulation.device-name=DEVICE_NAME

    Available for emulation devices you can find in the Dimensions list in chrome.

  2. Custom devices

    In case you need to use Responsive Viewport Mode and set up your own device, update the screen resolution in the following properties:

    web.driver.chrome.mobile-emulation.width=1440
    web.driver.chrome.mobile-emulation.height=900

Docker

This profile should be used in conjuction with other browser profile.

Example 2. Use Chrome browser running in a docker container
configuraiton.profiles=web/docker,web/desktop/chrome
Default Selenium grid URL is set to selenium.grid.url=http://localhost:4444/wd/hub. Don’t forget to modify it if your grid is running in a different location.

Mobile web

The following profiles running mobile browsers are available out of the box:

  • web/phone/android

  • web/phone/iphone

  • web/tablet/ipad

Properties

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

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

PT3M

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

web-application.session-scope

story

scenario

story

The test lifecycle of the browser:

  • the browser opens at the first step requiring browser interaction

  • the browser 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.

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

screenshot.on-failure.debug-modes

proxy

<empty>

Provides possibility to attach screenshot for failed proxy steps

web.timeouts.page-load

ISO-8601 Durations

PT1M

Sets the amount of time to wait for a page load to complete before throwing an error.

web.timeouts.async-script

ISO-8601 Durations

PT1M

Sets the amount of time to wait for an asynchronous script to finish execution before throwing an error.

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:

web-application.main-page-url

An absolute URL

<empty>

The URL of the starting page of the web application under test

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

ui.publish-shadow-dom-source-on-failure

true
false

true

Whether to publish the source code of Shadow DOM elements on failure or not

Configure driver path

While executing tests on the local machine it is allowed to use custom browser driver. This approach first requires manually downloading the driver (See Quick Reference Section for download links). The path to the downloaded binary should be configured using the following property:

web.driver.<browser>.driver-executable-path=/path/to/driver/executable

where <browser> is one of the following values:

  • chrome

  • firefox

  • safari

  • iexplore

  • edge

  • opera

Configure browser path

While executing tests on the local machine it is allowed to configure path to browser executable file. In general cases it’s not required, installed browsers are found automatically (except Opera browser). Also, for example, if browser is not installed, but only downloaded and unpacked into some folder, the path to the downloaded binary should be configured using the following property:

web.driver.<browser>.binary-path=/path/to/custom/browser/executable

where <browser> is one of the following values:

  • chrome

  • firefox

  • edge

  • opera

Configure Basic authentication for Chromium browsers

It is allowed to add predefined configurations for Basic authentication. This setting is only available for desktop Chromium browsers (Chrome, Opera, Microsoft Edge) and allows to define multiple configurations for authentication on different websites.

Property Name Acceptable values Description

web-application.basic-authentication.<configuration-name>.url-regex

Regular expression

Regular expression for site URI (regex validate URI without path, for example for page https://www.example.com/page regex will be ^https:\/\/www\.example\.com$)

web-application.basic-authentication.<configuration-name>.username

Username

Username

web-application.basic-authentication.<configuration-name>.password

Password

Password

Example 3. Set up authentication for websites https://httpbingo.org and https://www.example.com
web-application.basic-authentication.httpbingo.url-regex=https:\/\/httpbingo\.org
web-application.basic-authentication.httpbingo.username=user
web-application.basic-authentication.httpbingo.password=password

web-application.basic-authentication.example.url-regex=.*example\.org
web-application.basic-authentication.example.username=admin
web-application.basic-authentication.example.password=qwerty123

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.

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

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.

Expressions

The expression parameters marked with bold are mandatory.

decodeDataUrl

Parses Data URL-s and decodes their data if Base64 encoding is set. The result of the expression depends on the MIME type of Data URL. The result will be a binary data in case of the binary MIME type and it will be a string for the text MIME type.

If expression is applied to invalid Data URL the error will be thrown.
#{decodeDataUrl($dataUrl)}
  • $dataUrl - The Data URL to decode.

Example 5. Decoding inlined image
When I save `src` attribute value of element located by `id(image)` to scenario variable `image`
When I compare against baseline with name `inlined-image` from image `#{decodeDataUrl(${image})}`
Table 1. Examples of the expressions decoding Data URL
Expression Result

#{decodeDataUrl(data:,value)}

value

#{decodeDataUrl(data:text/plain,value)}

value

#{decodeDataUrl(data:;base64,SGVsbG8sIFdvcmxkIQ==)}

Hello, World!

#{decodeDataUrl(data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==)}

Hello, World!

#{decodeDataUrl(data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==)}

Hello, World!

#{decodeDataUrl(data:image/png;base64,iVBORw…​.)}

Image binary data.

Dynamic variables

Current page URL

The variable provides the URL of the page currently loaded in the browser.

${current-page-url}
Example 6. Validate redirect in the browser
Given I am on page with URL `https://docs.vividus.dev/`
Then `${current-page-url}` is equal to `https://docs.vividus.dev/vividus/latest/index.html`

Browser window dimension

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

Variable name Description

browser-window-height

the height of the browser window

browser-window-width

the width of the browser window

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

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 8. 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 9. 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 10. Check if element exists on UI
Then `${source-code}` matches `.+Home.+`

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 11. 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 12. Definition of custom locator
ui.locator.anyAttOrText.locator-type=xpath
ui.locator.anyAttOrText.pattern=//*[@*='%s' or text()='%s']
Example 13. Usage of custom locator
Given I am on main application page
Then number of elements found by `anyAttOrText(attribute, text)` is = `1`
Example 14. 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!

Locator Types

Type Description Example

id

Locates elements whose id attribute matches the search value

id(submitBtn)

cssSelector

Locates elements matching a CSS selector

cssSelector(.menu-item)

xPath

Locates elements matching an xPath expression

xpath(//a)

unnormalizedXPath

Locates elements matching an xPath expression. Unlike xPath locator this one doesn’t add space normalization and moves handling of spaces up to user

unnormalizedXPath(//li[text()='ID:    testId'])

tagName

name of an element tagName

tagName(a)

className

CSS class name

className(bold)

linkText

text of the link

linkText(Google)

linkUrl

href attribute of the link element

linkUrl(/faq)

linkUrlPart

part of a href attribute of the link element

linkUrlPart(faq)

caseSensitiveText

case sensitive text of an element

caseSensitiveText(Description)

caseInsensitiveText

case insensitive text of an element

caseInsensitiveText(description)

imageSrc

shortcut to a .//img[@src='<value>>']

imgSrc(/images/kote.png)

imageSrcPart

shortcut to a .//img[contains(@src,'<value>>')]']

imgSrcPart(kote.png)

buttonName

elements of type button or input with text or any attribute value

buttonName(submit)

fieldName

input or textarea with text or any attribute value

fieldName(editor)

radioButton

input element with @type="radio" and label text value

radioButton(One)

checkboxName

input element with @type="checkbox" and text value

checkboxName(allow)

elementName

This locator type is deprecated and will be removed in VIVIDUS 0.7.0. Use name locator type instead.

any attribute or text value

elementName(OK)

name

Locate elements where any attribute or text value matches the specified search value.

name(OK)

shadowCssSelector

chain of css selectors, separated by ;, where first value - selector for upper shadow host, last value - target element selector

shadowCssSelector(.upperHost; #innerHost1; #innerHost2; .targetValue)

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

Filter types

The filters are applied after elements search using one of the locators specified above. The elements not matching the filter condition are sorted out without any notice.

Filter type Description Example

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)

attribute

Filter elements by their attribute values

tagName(div)→filter.attribute(class=burger-menu) - div element has the class attribute with burger-menu value tagName(div)→filter.attribute(class) - div element has the class attribute with any value tagName(div)→filter.attribute(class=) - div element has the class attribute with an empty value

state

element State

id(v1)→filter.state(VISIBLE)

caseSensitiveText

element text should match case sensitively

id(v1)→filter.caseSensitiveText(text)

classAttributePart

class attribute should contain part

id(v1)→filter.classAttributePart(clazz)

linkUrl

href attribute of the link element

id(v1)→filter.linkUrl(/url)

linkUrlPart

part of href attribute of the link element

id(v1)→filter.linkUrlPart(/url)

tooltip

This filter type is deprecated and will be removed in VIVIDUS 0.7.0.

title attribute value

id(v1)→filter.tooltip(title)

imageSrcPart

This filter type is deprecated and will be removed in VIVIDUS 0.7.0.

src attribute should contain value

id(v1)→filter.imageSrcPart(part)

placeholder

This filter type is deprecated and will be removed in VIVIDUS 0.7.0.

Placeholder attribute should be equal to a value

id(v1)→filter.placeholder(placeholder-value)

validationIconSource

This filter type is deprecated and will be removed in VIVIDUS 0.7.0.

CSS property background-image should match

id(v1)→filter.validationIconSource(src)

fieldText

field text should match expected value

id(v1)→filter.fieldText(value)

fieldTextPart

field text should contain expected value

id(v1)→filter.fieldTextPart(value)

dropDownText

any of select options should be equal to a value

id(v1)→filter.dropDownText(value)

Steps

Navigation

Open application

Navigates to the page which was configured as the main application page in the property with name web-application.main-page-url.

Given I am on main application page

Open the page by URL

Navigates to the page with the given absolute URL, e.g. https://docs.vividus.dev/.

Given I am on page with URL `$pageUrl`
Example 15. Open the page with URL https://docs.vividus.dev/
Given I am on page with URL `https://docs.vividus.dev/`

Navigate to the page by relative URL

Navigates to the page with the given relative URL.

When I go to relative URL `$relativeUrl`
Example 16. Open main application page and then navigate to '/products/new' page
Given I am on main application page
When I go to relative URL `/products/new`

Refresh the page

Reloads the current page: does the same as the reload button in the browser.

When I refresh page

Navigate back

Navigates back to the previous page: does the same as the back button in the browser.

When I navigate back

Validate the page title

Checks the page title matches the text according to the given validation rule.

Then page title $comparisonRule `$text`
  • $comparisonRule - The page title validation rule. One of the following options:

    • is equal to - validate the page title is equal to $text parameter,

    • contains - validate the page title title contains the string from $text parameter,

    • does not contain - validate the page title title does not contain the value from $text parameter.

  • $text - The text to match according to the rule.

Example 17. Validate 'https://docs.vividus.dev/' page title
Then page title is equal to `What is VIVIDUS :: VIVIDUS`
Example 18. Validate the part of 'https://docs.vividus.dev/' page title
Then page title contains `VIVIDUS`

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 19. 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 20. 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 21. 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 22. 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

Mouse Actions

Click on the element

Clicks on the element found by the given locator.

The atomic actions performed are:

  • find the element by the given locator;

  • click on the element if it is found, otherwise the whole step is failed and its execution stops;

  • the first two actions are retried once if the field becomes stale during actions execution in other words if StaleElementReferenceException is occurred at any atomic action.

If the element by the given locator is not clickable (overlapped by another element, page or current context is not loaded properly or the element is disabled) the step will fail with corresponding error:

Could not click on the element: org.openqa.selenium.ElementClickInterceptedException: element click intercepted:
Element <a href="#where-to-buy" data-tab-name="..." role="button">Where to Buy</a> is not clickable at point (1619, 275).
Other element would receive the click: <div class="content">...</div>

In this case extra steps might be needed to ensure element actionability, like, scrolling to the element, adding waits, etc.

When I click on element located by `$locator`
  • $locator - The locator used to find the element to click.

Example 23. Click on element with name Submit
When I click on element located by `name(Submit)`

Validate page is not refreshed after click on element

Clicks on the element and checks that the page has not been refreshed after the click.

When I click on element located by `$locator` then page does not refresh

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I click on an element '$locator' then the page does not refresh
  • $locator - The locator used to find the element to click.

Example 24. Click on the element with id attribute having value send and validate page is not refreshed after the action
When I click on element located by `id(send)` then page does not refresh

Right-click on the element

Finds the element by the given locator and performs a right-click in the center of the element if it’s found (at first moves mouse to the location of the element).

When I perform right-click on element located by `$locator`

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I perform right click on element located `$locator`
  • $locator - The locator used to find the element to right-click.

Example 25. Right-click on the element with id attribute having value clickme
When I perform right-click on element located by `id(clickme)`

Hover mouse over the element

Finds the element by the given locator and moves a mouse cursor over the center of the element, if it’s found.

When I hover mouse over element located by `$locator`

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I hover mouse over element located `$locator`
  • $locator - The locator used to find the element to hover mouse over.

Example 26. Hover mouse over element with id attribute having value tooltip
When I hover mouse over element located by `id(tooltip)`

Input Fields Interactions

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

  • <input> elements,

  • <textarea> elements,

  • [contenteditable] elements (e.g CKE editors, they are usually located via <body> tag, that is placed in a frame as a separate HTML document).

Enter text in field

Enter the text in the field found by the given 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.

When I enter `$text` in field located by `$locator`
  • $text - The text to enter in the field.

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

Example 27. Type text pa$$w0rd in the field with attribute id having value password
When I enter `pa$$w0rd` in field located by `id(password)`

Add text to field

Enters the text in the field, found by the given locator, without clearing 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 the field to add the text.

Example 28. Add text name to the field with attribute id having value username
When I add `name` to field located by `id(username)`

Clear field

Finds the field by the given locator and clears it if it’s found. 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 the field to clear.

Example 29. Clear the field with attribute id having value email
When I clear field located by `id(email)`

Clear field using keyboard

Finds the field by the given locator and clears it using keyboard if the field is found. The step simulates user action by pressing buttons Ctrl+A or Cmd+A and then 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 a field.

Example 30. Clear the field with attribute id having value email using keyboard
When I clear field located by `id(email)` using keyboard

Scrolling steps

Scroll context

Scrolls the context to an edge

When I scroll context to $scrollDirection edge
  • $scrollDirection - the direction of the scroll. One of:

    • LEFT - start of a page/element horizontally

    • RIGHT - end of a page/element horizontally

    • TOP - start of a page/element vertically

    • BOTTOM - end of a page/element vertically

If the context is not set, the whole page will be scrolled
Example 31. Scroll login to a bottom
When I change context to element located by `id(login)`
When I scroll context to BOTTOM edge

Scroll element into view

Scrolls an element into the view with centred positioning.

If the element to scroll is located inside an overflow container then native scrollIntoView JS method with top alignment is used.
When I scroll element located by `$locator` into view
  • $locator - The locator used to find element.

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I scroll element located `$locator` into view
  • $locator - The locator used to find element.

Example 32. Scroll button into view
When I scroll element located by `id(way_down_button)` into view

Validate the page is scrolled to element

Checks if the page is scrolled to the specific element

This step is deprecated and will be removed in VIVIDUS 0.8.0. Please see the replacement pattern below:

Then element located by `$locator` is visible in viewport
Then page is scrolled to element located by `$locator`
  • $locator - The locator used to find element.

Example 33. Validate Contact link is scrolled into view
Then page is scrolled to element located by `xpath(//a[text()="Contact"])`

Validate element presence in viewport

Checks if the element located by the specified locater is or is not presented in the browser viewport

Then element located by `$locator` $presence visible in viewport
  • $locator - The locator used to find element.

  • $presence - The presence state of the element, either is or is not.

Example 34. Validate element presence in viewport
Given I am on a page with the URL 'https://ui.com/long-page-with-image'
Then element located by `tagName(img)` is not visible in viewport
When I scroll element located `tagName(img)` into view
Then element located by `tagName(img)` is visible in viewport

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 35. 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 36. 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 37. 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 38. 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`

Text content validation

The context can be set by the corresponding steps. If no context is set, the text will be searched across the whole page.

Validate the text exists

Validates the text is present in the current context. The expected text is case-sensitive.

Then text `$text` exists
  • $text - The expected text to be found in the context text.

Example 39. Check the text 'Contract Us' is present on the page
Given I am on page with URL `https://docs.vividus.dev/`
Then text `Contact Us` exists

Validate the text does not exists

Validates the text is not present in the current context.

Then text `$text` does not exist
  • $text - The text that should not be present in the context.

Example 40. Check the text 'Deprecated' is not present in the element
When I change context to element located by `id(code)`
Then text `Deprecated` does not exist

Validate the text matches regular expression

Validates the text from current context matches the specified regular expression.

Then text matches `$regex`
Example 41. Check the text with pattern 'User ".*" successfully logged in' is present in the current context
When I change context to element located by `id(message)`
Then text matches `User ".*" successfully logged in`

Tab steps

Open a new tab

Opens a new browser tab and switches the focus for future commands to this tab.

When I open new tab
Example 42. Open page in a new tab
When I open new tab
Given I am on page with URL `https://docs.vividus.dev/`

Open URL in a new tab

Opens a new tab, switches the focus to this tab and loads the given URL.

The key difference of this step from the previous one opening a new tab is that this step inherits the state of the previous page, i.e.:

When I open URL `$URL` in new tab

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I open URL `$URL` in new window
  • $URL - The URL to open.

Example 43. Open docs in a new tab
When I open URL `https://docs.vividus.dev` in new tab

Close current tab

Closes the current tab and switches to the previous tab.

When I close current tab

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I close the current window
Handling alerts displayed with 'onbeforeunload' events is not implied by the WebDriver specification to close window. For handling alerts use step based on JavaScript 'Close current tab with possibility to handle alert'.
This step can only be applied to a session with multiple tabs open.
Example 44. Open URL in new tab, close it and switch to the previous page
Given I am on page with URL `https://example.com/`
When I open URL `https://example.com/contact-us` in new tab
When I close current tab

Close current tab with possibility to handle alert

Trying to close the current tab with 'onbeforeunload' events handling.

  • If an alert window is opened via 'onbeforeunload' event, it must be checked and handled in the subsequent steps.

  • If an alert window is not opened, the step closes the current window and switches to the previous window.

When I attempt to close current tab with possibility to handle alert

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I attempt to close current window with possibility to handle alert
This step can only be used if the current tab was opened via the step When I open URL `$pageUrl` in new tab.
If you confirm window close in alert, the tab will be closed, and you will need to switch to current tab using the following step: When I switch to tab with title that $stringComparisonRule `$windowName`.
Example 45. Checking for an alert when trying to close a window with form
Given I am on page with URL `https://example.com/`
When I open URL `https://example.com/form` in new tab
When I click on element located by `xpath(//*[@id='form-edit'])`
When I execute sequence of actions:
|type      |argument    |
|ENTER_TEXT|changed text|
When I attempt to close current tab with possibility to handle alert
Then an alert is present
When I accept alert with message which matches `.*`

Execute sequence of actions

Executes the sequence of web actions

When I execute sequence of actions: $actions
  • $actions - table of actions to execute

    Table 3. Possible actions
    type argument Argument example

    DOUBLE_CLICK

    Element locator or empty.

    By.linkUrl(http://httpbin.org)

    CLICK_AND_HOLD

    Element locator or empty.

    By.linkText(Click me)

    MOVE_BY_OFFSET

    Point.

    (10, 15) where x is 10 and y is 15

    RELEASE

    Element locator or empty.

    By.tagName(div)

    ENTER_TEXT

    Text to type.

    Minsk City

    CLICK

    Element locator or empty.

    By.caseSensitiveText(Done)

    PRESS_KEYS

    Comma-separated keys to press and release.

    BACK_SPACE

    KEY_DOWN

    Comma-separated keys to press one by one.

    CONTROL,SHIFT,ALT

    KEY_UP

    Comma-separated keys to release one by one.

    CONTROL,SHIFT,ALT

    MOVE_TO

    Element locator.

    By.id(username)

Windows/Unix and macOS platforms have different keyboards. For example, Ctrl+C combination is used to copy text on Windows and Unix, but ⌘ Command+C should be used on macOS with default preferences.

In order to close this gap VIVIDUS offers unique key OS_INDEPENDENT_CONTROL: it is mapped to CONTROL key on Windows/Unix and to COMMAND key on macOS. Using this key it is possible to make tests fully platform independent.

Example 46. Execute various web-actions
When I execute sequence of actions:
|type          |argument                                |
|DOUBLE_CLICK  |By.fieldText(Hello World)               |
|DOUBLE_CLICK  |                                        |
|CLICK_AND_HOLD|By.xpath(//signature-pad-control/canvas)|
|CLICK_AND_HOLD|                                        |
|MOVE_BY_OFFSET|(-300, 0)                               |
|RELEASE       |By.xpath(//signature-pad-control/canvas)|
|RELEASE       |                                        |
|ENTER_TEXT    |Text                                    |
|CLICK         |By.placeholder(Enter your password)     |
|CLICK         |                                        |
|PRESS_KEYS    |BACK_SPACE                              |
|KEY_DOWN      |CONTROL,SHIFT                           |
|KEY_UP        |CONTROL,SHIFT                           |
|MOVE_TO       |By.id(name)                             |

This step can be used to perform clipboard interactions.

Example 47. Select all text in the focused field and copy it to the clipboard on Windows
When I execute sequence of actions:
|type      |argument  |
|KEY_DOWN  |CONTROL, a|
|KEY_UP    |a, CONTROL|
|KEY_DOWN  |CONTROL, c|
|KEY_UP    |c, CONTROL|
Example 48. Paste text from the clipboard to the focused field on MacOS
When I execute sequence of actions:
|type      |argument  |
|KEY_DOWN  |COMMAND, v|
|KEY_UP    |v, COMMAND|
Example 49. Select all text in the focused field and copy it to the clipboard on any OS
When I execute sequence of actions:
|type      |argument                 |
|KEY_DOWN  |OS_INDEPENDENT_CONTROL, a|
|KEY_UP    |a, OS_INDEPENDENT_CONTROL|
|KEY_DOWN  |OS_INDEPENDENT_CONTROL, c|
|KEY_UP    |c, OS_INDEPENDENT_CONTROL|

Browser logs steps

This set of steps allows to validate the browser console logging messages.

In order to configure availability of the INFO level messages use following properties:

Browser

Property to enable INFO logs

Google Chrome

selenium.capabilities.goog\:loggingPrefs.browser=INFO

Microsoft Edge Chromium

selenium.capabilities.ms\:loggingPrefs.browser=INFO

Validate log entries absence

Validates the absence of log entries of the desired level in the browser console.

Then there are no browser console $logLevels
  • $logLevels - List of the comma-separated messages levels. The supported levels are: ERRORS, WARNINGS, INFOS.

Example 50. Validate absence of JS errors
Given I am on page with URL `https://vividus-test-site-a92k.onrender.com/`
Then there are no browser console ERRORS

Validate specific log entries absence

Validates the absence of specific log entries of the desired level in the browser console.

Then there are no browser console $logLevels by regex `$regex`

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

Then there are no browser console $logLevels by regex '$regex'
  • $logLevels - List of the comma-separated messages levels. The supported levels are: ERRORS, WARNINGS, INFOS.

  • $regex - The regular expression to match log entry messages.

Example 51. Validate absence of JS error referencing user
Given I am on page with URL `https://vividus-test-site-a92k.onrender.com/`
Then there are no browser console ERRORS by regex `.*user.*`

Validate specific log entries presence

Validates the presence of specific log entries of the desired level in the browser console.

Then there are browser console $logLevels by regex `$regex`
  • $logLevels - List of the comma-separated messages levels. The supported levels are: ERRORS, WARNINGS, INFOS.

  • $regex - The regular expression to match log entry messages.

Example 52. Validate presence of JS errors referencing user
Given I am on page with URL `https://vividus-test-site-a92k.onrender.com/`
Then there are browser console ERRORS by regex `.*user.*`

Wait for console log entries and save them

Waits for the appearance of the console log entries with the expected level and which match regular expression and saves all the entries (including awaited ones) of the expected level gathered during the wait to the scoped variable.

Wait uses generic UI timeouts specified by the properties ui.wait.timeout and ui.wait.polling-period. See Properties section for more details.
When I wait until browser console $logEntries by regex `$regex` appear and save all entries into $scopes variable `$variableName`
  • $logLevels - List of the comma-separated messages levels. The supported levels are: ERRORS, WARNINGS, INFOS.

  • $regex - The regular expression to match log entry messages.

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

  • $variableName - The name of the variable to save the value of the barcode.

Example 53. Wait for application readiness
Given I am on page with URL `https://vividus-test-site-a92k.onrender.com/`
When I wait until browser console infos by regex `.*Application ready.*` appear and save all entries into scenario variable `logs`
Then `${logs}` matches `.*Application ready in \d+ seconds.*`

Clear browser console logs

Clears browser console logs of all types.

The console.clear(); JS command doesn’t affect the logs fetched by Selenium.
When I clear browser console logs
Example 54. Clear browser console logs
Given I am on page with URL `https://vividus-test-site-a92k.onrender.com/`
When I clear browser console logs
Then there are browser console ERRORS by regex `.*`

Perform steps for each found element

Executes the steps against all elements found by locator. After a required number of elements is found, search context switches in order for each found element and performs all steps on it.

If comparison rule mismatch steps will not be performed even if elements are found.
When I find $comparisonRule `$number` elements by `$locator` and for each element do$stepsToExecute

Alias:

When I find $comparisonRule '$number' elements by $locator and for each element do$stepsToExecute
  • $comparisonRule - The comparison rule.

  • $number - The number of elements to find.

  • $locator - The locator used to find elements.

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

Example 55. Script type check
When I find = `5` elements by `xpath(//script):a` and for each element do
|step                                                                                      |
|When I set 'type' attribute value of the context element to the 'scenario' variable 'type'|
|Then `${type}` is equal to `text/javascript`                                              |

Context steps

Switch to the default context of page

Switches context to the root <html> element of the current page.

When I switch back to page

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I switch back to the page
Example 56. Switch to user context and back to the default context of page
Given I am on page with URL `https://vividus-test-site-a92k.onrender.com/elementState.html`
When I change context to element located by `id(button-hide)`
Then text `Element to hide` does not exist
When I switch back to page
Then text `Element to hide` exists

Switch context to a frame

Switches to <iframe> or <frame> element using one of the supported locators.

When I switch to frame located by `$locator`

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I switch to frame located `$locator`
  • $locator - Locator of frame element.

Example 57. Switch to frame
Given I am on page with URL `https://vividus-test-site-a92k.onrender.com/nestedFrames.html`
Then text `Modal Frame Example` does not exist
When I switch to frame located by `id(parent)`
Then text `Modal Frame Example` exists

Switch context to new tab

Switch the focus of future browser commands to new tab.

This step gets the identifier of the currently active tab and then switches focus to the first available tab with a different identifier. For example, if tabs #1, #2, #3 are open and tab #2 is active, this step will switch focus to tab #3.

A new tab should already be open for this step to function. After executing this step, the new tab will become the active tab.
When I switch to new tab

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I switch to a new window
Example 58. Open the new tab by link and switch to it
Given I am on page with URL `https://the-internet.herokuapp.com/windows`
When I click on element located by `linkUrlPart(/windows/new)`
Then text `New Window` does not exist
When I switch to new tab
Then text `New Window` exists

Switch context to new tab with specified title

Switch the focus of future browser commands to new tab with specified title.

When I switch to tab with title that $stringComparisonRule `$tabName`

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I switch to window with title that $stringComparisonRule `$windowName`
Example 59. Open the new tab by link and switch to it using regex title pattern
Given I am on page with URL `https://the-internet.herokuapp.com/windows`
When I click on element located by `linkUrlPart(/windows/new)`
Then text `New Window` does not exist
When I switch to tab with title that matches `.*[wW]indow.*`
Then text `New Window` exists

Close browser

Closes the browser.

When I close browser

Wait for tab and switch

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

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

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I wait `$duration` until window with title that $comparisonRule `$windowTitile` appears and switch to it
Example 60. 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

Stop page loading

Stops page loading

When I stop page loading
Could be useful in combination with Selenium’s page load strategy
Example 61. Stop page loading.story
When I open URL `https://delayed.vividus.dev` in new tab
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-8601 Durations format.

Example 62. Before loading a heavy page set an increased timeout
Given I am on page with URL `https://example.com/`
When I set page load timeout to `PT20S`
When I open URL `https://example.com/super-heavy-page` in new tab
When I set page load timeout to `PT10S`

Performance metrics

Checks web performance metrics.

Then metric $webPerformanceMetric is $comparisonRule `$duration`
Example 63. Check page load
Given I am on page with URL `https://example.com`
Then metric PAGE_LOAD_TIME is less than `PT5S`

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 64. 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 65. 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 66. 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 67. 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 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+`

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 69. Wait for the visible elements
When I wait until number of elements located by `tagName(img)` is equal to `5`
Example 70. 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 71. 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 72. 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 73. 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 74. 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 75. The element should have existed for 5 second
Then element located by `id(banner)` exists for `PT5S` duration

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 76. 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 77. 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 78. 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 79. 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 80. Remove noisy assistant
When I execute javascript `document.querySelector('#assistant').remove()` with arguments:
Example 81. Inject image
When I execute javascript `sauce:inject-image` with arguments:
|value                                                                                       |type  |
|iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=|string|
Example 82. 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 83. 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 entire page. 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 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`
Example 84. 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`

Upload file

Uploads the resource or file via web interface.

When I select element located by `$locator` and upload `$resourceNameOrFilePath`

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I select element located `$locator` and upload file `$filePath`
  • $locator - the locator of the web element with input tag and attribute type=file

  • $resourceNameOrFilePath - relative path to the file to be uploaded

Example 85. Upload file_for_upload.png file
When I select element located by `id(uploadfile)` and upload file `/folder/file_for_upload.png`

Drag and drop steps

This set of steps facilitates the dragging and dropping of elements on a web page.

Drag and drop using mouse

Performs drag-and-drop operation for the specified elements.

When I drag element located by `$draggable` and drop it at $location of element located by `$target`
  • $draggable - The locator to identify the element to be dragged.

  • $location - The target position relative to the target element (TOP, BOTTOM, LEFT, RIGHT, CENTER, LEFT_TOP, RIGHT_TOP, LEFT_BOTTOM, RIGHT_BOTTOM).

  • $target - The locator to identify the target element.

Example 86. Dragging the image on the page
When I drag element located by `id(item-number)` and drop it at right bottom of element located by `id(item-number)`

Drag and drop simulation

Simulates a drag-and-drop operation for the specified elements, replicating the behavior without actual mouse actions performed.

When I simulate drag of element located by `$draggable` and drop at element located by `$target`
  • $draggable - The locator to identify the element to be dragged.

  • $target - The locator to identify the target element.

Example 87. Simulation of dragging an image onto the page
When I simulate drag of element located by `id(item-number)` and drop at element located by `id(item-number)`

Check each element has a specific number of children elements

Checks that each element specified by the locator contains an exact number of visible child elements specified by another locator

Then each element with locator `$elementLocator` has `$number` child elements with locator `$childLocator`
  • $elementLocator - The locator to the parent element.

  • $number - The expected number of children elements

  • $childLocator - The locator to the child elements.

Example 88. Step example
Then each element with locator `id(menu)` has `5` child elements with locator `id(menu-item)`

Check an element CSS property

Checks the context element has the expected CSS property.

The context can be set by the corresponding steps.

Then context element has CSS property `$cssName` with value that $comparisonRule `$cssValue`
  • $cssName - A name of the CSS property.

  • $comparisonRule - CSS property comparison rule.

  • $cssValue - The expected value of the CSS property.

Example 89. Change context to element and verify it color CSS property value
When I change context to element located by `id(rainbow)`
Then context element has CSS property `color` with value that is equal to `rgba(0, 0, 0, 1)`

Compare sizes of the elements

Check that all elements found on the page by the given locator have the same dimension: width / height.

Element’s dimension is measured in pixels and means the size that given element occupies on the web-page in a browser. Element size may vary in different browsers, it also depends on screen resolution, page scaling, scripts running on the page.
Then each element located by `$locator` has same `$dimension`

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

Then each element located `$locator` has same `$dimension`
  • $locator - The locator to find an elements to compare.

  • $dimension - The elements dimension to compare. Possible values: width, height

Example 90. Check that all menu items have the same size (width and height)
Then each element located `id(context-menu-item)` has same `width`
Then each element located `id(context-menu-item)` has same `height`

Check element width in a percentage

Checks that the context element has an expected width in a percentage (from the style attribute) relative to the page body.

The context can be set by the corresponding steps.

Then context element has width of $widthPercentage%

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

Then the context has a width of '$widthPercentage'%
  • widthPercentage - An expected element width in a percentage relative to the page body.

Example 91. Check element width
When I change context to element located by `id(menu)`
Then context element has width of 30%

Check element width in a percentage relative to the parent element

Checks that the context element has an expected width in a percentage (from the style attribute) relative to the parent element

The context can be set by the corresponding steps.

Then context element has width of $widthPercentage% relative to parent element

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

Then the context element has a width of 'widthPercentage'% relative to the parent element
  • widthPercentage - An expected element width in a percentage.

Example 92. Check element width
When I change context to element located by `id(menu)`
Then context element has width of 13% relative to parent element

Focus Steps

Focus indicates the act of selecting an element of a graphical user interface. Text entered at the keyboard or pasted from a clipboard is sent to the component which has the focus.

Set focus on the context element

Sets the focus on the context element, if it can be focused. The focused element is the element that will receive keyboard and similar events by default.

When I set focus on context element
Example 93. Set focus on the element with ID "input-username"
When I change context to element located by `id(input-username)`
When I set focus on context element

Set focus on the element

Sets the focus on the element found by the specified locator, if it can be focused. The focused element is the element that will receive keyboard and similar events by default.

When I set focus on element located by `$locator`
  • $locator - The locator to find an element.

Example 94. Set focus on the element with ID "input-username"
When I set focus on element located by `id(input-username)`

Check the context element focus state

Checks if the context element is in the provided focus state by comparing the context element and the active element.

Then context element is $focusState
  • $focusState - The state to verify: in focus or not in focus.

Example 95. Check the context element is in focus and do keyboard input
Then context element is in focus
When I press ENTER on keyboard

Check the element focus state

Checks if the element found by the specified locator is in the provided focus state by comparing the found element and the active element

Then element located by `$locator` is $focusState
  • $locator - The locator to find an element.

  • $focusState - The state to verify: in focus or not in focus.

Example 96. Check the element with ID "input-username" is in focus and do keyboard input
Then element located by `id(input-username)` is in focus
When I change context to element located by `id(input-username)`
When I press ENTER on 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 by `$locator` contains options:$options

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

Then dropdown located `$locator` contains options:$options
  • $locator - The locator used to find a dropdown.

  • $options - examples table describing expected options

Example 97. Validate dropdown contains a set of colors
Then dropdown located by `id(colors)` contains options:
|state|item |
|false|Red  |
|false|Green|
|true |Blue |
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 by `$locator` exists and selected option is `$option`

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

Then dropdown located `$locator` exists and selected option is `$option`
  • $locator - The locator used to find a dropdown.

  • $option - first selected option

Example 98. Dropdown.story
Then dropdown located by `id(colors)` exists and selected option is `Blue`

Add an option to the mutli-select dropdown

Selects option in multi-select dropdown

Step will fail if target dropdown is not multi-select
When I add `$option` to selection in dropdown located by `$locator`

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

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

  • $locator - The locator used to find a dropdown.

Example 99. Dropdown.story
When I add `Two` to selection in dropdown located by `id(numbers)`

Select the option

Selects option in dropdown

Does not support multi-selection
When I select `$option` in dropdown located by `$locator`

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I select `$option` in dropdown located `$locator`
  • $option - option to select

  • $locator - The locator used to find a dropdown.

Example 100. Dropdown.story
When I select `Red` in dropdown located by `id(colors)`

Validates whether the certain cookie is set.

Then cookie with name that $stringComparisonRule `$cookieName` is set
Example 101. Check the session cookie is present
Then cookie with name that is equal to `JSESSIONID` is set

Validates whether the certain cookie is not set.

Then cookie with name that $stringComparisonRule `$cookieName` is not set
Example 102. Check that Google Analytics cookies are not present
Then cookie with name that matches `_ga.*` 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

Example 103. Set the cookie for the current domain
When I set all cookies for current domain:
|cookieName   |cookieValue |path |
|cookieAgreed |2           |/    |

Set cookies without applying changes

Adds the cookies provided in the input ExamplesTable, 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. It’s allowed to add the cookies for the current domain only: make sure the web browser is opened at the expected domain.

When I set all cookies for current domain without applying changes:$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

Example 104. Set the cookie for the current domain
When I set all cookies for current domain without applying changes:
|cookieName   |cookieValue |path |
|cookieAgreed |2           |/    |
When I refresh page

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`
Example 105. Get the value of the session cookie
When I save value of cookie with name `JSESSIONID` to scenario variable `session-id`

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`
Example 106. Get the session cookie
When I save cookie with name `JSESSIONID` as JSON to scenario variable `session-id`

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.

Example 107. Remove the session cookie
When I remove cookie with name `JSESSIONID` from current domain

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.

Example 108. Remove the session cookie
When I remove cookie with name `JSESSIONID` from current domain without applying changes
When I refresh 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 applying changes

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.

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

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

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

Example 112. Check the local storage item is not present
Then local storage item with key `token` does not exist

Remove web storage item

Removes an item with the key from web storage.

When I remove item with key `$key` from $storageType storage
  • $key - The key of the item to remove.

  • $storageType - One of the web storage mechanisms: either local or session.

Example 113. Remove item with 'token' key from web storage
When I remove item with key `token` from session storage

Clear web storage

Removes all items from web storage.

When I clear $storageType storage
  • $storageType - One of the web storage mechanisms: either local or session.

Example 114. Clear session storage
When I clear session storage

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 115. 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 116. Validate the URL of the matching HTTP request
Given I am on page with URL `https://www.google.com/search?q=vividus`
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 117. Validate the URL query of the matching HTTP request
Given I am on page with URL `https://www.google.com/search?q=vividus`
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 118. Validate the request data from the matching HTTP message
Given I am on page with URL `https://www.google.com/search?q=vividus`
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 119. Validate the response data from the matching HTTP message
Given I am on page with URL `https://www.google.com/search?q=vividus`
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 120. Wait for the HTTP request
Given I am on page with URL `https://www.google.com/search?q=vividus`
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 121. 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 am on page with URL `https://www.google.com/search?q=vividus`
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 122. Clear the data recorded by the proxy
Given I am on page with URL `https://www.google.com/search?q=vividus`
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 123. 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 am on page with URL `https://www.google.com/search?q=vividus`
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 124. 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 125. 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 126. 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    |

Window Steps

Resize the current browser window

Changes the current browser window size to the specified one.

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.

Example 127. Resize the browser window
Given I am on page with URL `https://example.com/`
When I change window size to `640x320`

Select state in the checkbox

A checkbox is a graphical user interface element. Performs the action with the flag found by the locator. Actions that can be performed (CHECK or UNCHECK)

When I $checkBoxAction checkbox located by `$checkboxLocator`
  • $checkBoxAction - The action to select a state of the checkbox, either CHECK or UNCHECK.

  • $checkboxLocator - The locator used to identify the checkbox.

Example 128. Check 'Terms & Conditions' checkbox
When I check checkbox located by `checkboxName(terms-and-conditions)`

Video steps

Steps allow to interact with video elements.

Play Video

Starts video playback.

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

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I play video in video player located `$locator`
  • $locator - The locator used to find a video player.

Pause Video

Pauses video playback.

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

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

When I pause video in video player located `$locator`
  • $locator - The locator used to find a video player.

Rewind Video

Rewinds video to the desired mark in seconds.

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

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

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

  • $locator - The locator used to find a 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 by `$locator` to $scopes variable `$variableName`

Deprecated syntax (will be removed in VIVIDUS 0.7.0):

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

Example 129. Video player verifications
Given I am on page with 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 the property and the step are used - arguments from the property will be ignored. The step will take effect for all new browser sessions created in the current story. It will not affect the current sessions.

Popular browsers supporting command line arguments configuration:

Not supported browsers:

  • Safari

When I set browser command line arguments to `$argsString`
  • $argsString - Sequence of command line arguments, separated by space.

Example 130. 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 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`
Example 131. 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 element appearance with timeout

Waits for element appearance with desired timeout.

It’s forbidden to use Visibility types in the locator.
Then element located by `$locator` appears in `$timeout`
  • $locator - The locator used to find element.

  • $timeout - The maximum time to wait for the element appearance in ISO-8601 Durations format.

Example 132. Click on the button and waiting for element appearance for 2 minutes
When I click on element located by `buttonName(Show element)`
Then element located by 'id(element-to-show)' appears in 'PT2M'

Wait for element disappearance with timeout

Waits for element disappearance with desired timeout.

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`
  • $locator - The locator used to find element.

  • $timeout - The maximum time to wait for the element disappearance in ISO-8601 Durations format.

Example 133. 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'

Wait for element state

Waits for an element, located by the specified locator in the given search context, to change to the specified state.

Actions performed at this step:

  • finds an element with the specified locator within search context,

  • waits until this element changes to the specified state or timeout is reached.

When I wait until state of element located by `$locator` is $state
  • $locator - The locator used to find element.

  • $state - The expected element state.

Example 134. Click on the button and wait until the element becomes invisible
When I click on element located by `buttonName(hide)`
When I wait until state of element located by `xpath(//*[text()='Element to hide']):a` is NOT VISIBLE

Wait until element becomes stale

Waits for an element, located by the specified locator in the given search context, to become stale.

When an element becomes stale:

  • the element has been disposed,

  • the element is no longer attached to the DOM.

Actions performed at this step:

  • finds an element with the specified locator within search context,

  • waits until this element becomes stale or timeout is reached.

When I wait until element located by `$locator` is stale
  • $locator - The locator used to find element.

Example 135. Delete element using button and wait until the element disappears from the page
When I click on element located by `buttonName(Delete from order)`
When I wait until element located by `xpath(//*[text()='Pizza pepperoni']):a` is stale

Wait until element contains text

Waits for an element, located by the specified locator in the given search context, to contain the certain text.

Actions performed at this step:

  • finds an element with the specified locator within search context,

  • waits until the text in this element becomes visible or timeout is reached.

When I wait until element located by `$locator` contains text `$text`
  • $locator - The locator used to find element.

  • $text - The desired text to be present in the element.

Example 136. Click on the button and wait until the text in specified element becomes visible
When I click on element located by `buttonName(show text)`
When I wait until element located by `id(element-with-text)` contains text `Text to show`

Wait until scroll is finished

Waits for the scroll finish. Useful for the cases when page have very slow scroll and need to synchronize the tests with the scroll.

When I wait until scroll is finished
Example 137. Scroll the page and check that the element in the visible area
Given I am on page with URL `http://example.com/pageWithSlowScroll.html`
When I click on element located by `id(scrollIt)`
When I wait until scroll is finished
Then page is scrolled to element located by `id(footerElement)`

Script Steps

The Script Steps verify the presence of JavaScript files in the HTML source code of an active page.

Check the presence of script resource

This step is deprecated and will be removed in VIVIDUS 0.7.0. Please see the replacement pattern below:

Then number of elements found by `xpath(.//script[contains(@src()='<jsFileName>']):a` is equal to `1`

Checks script (an element with the <script> tag) with the specified path (@src attribute) is included on the page.

Then a javascript file with the name '$jsFileName' is included in the source code
  • $jsFileName - The part of the script resource URL from the @src attribute.

Example 138. Checks if the javascript with the 'script.js' filename exists in the page source code
Then a javascript file with the name 'script.js' is included in the source code.

Check the presence of script code

This step is deprecated and will be removed in VIVIDUS 0.7.0. Please see the replacement pattern below:

Then number of elements found by `xpath(.//script[text()='<jsText>']):a` is equal to `1`

Checks the page contains a script (an element with the <script> tag) whose content is equal to the specified text.

Then a javascript with the text '$jsText' is included in the source code
  • $jsText - The expected text to be equal to the text of a <script> tag.

Example 139. Checks if the JavaScript code equals to the expected one
Then a javascript with the text 'document.getElementById("demo-for-script").innerHTML = "Hello JavaScript!";' is included in the source code

Check script contains code

This step is deprecated and will be removed in VIVIDUS 0.7.0. Please see the replacement pattern below:

Then number of elements found by `xpath(.//script[contains(text(),'<jsTextPart>')]):a` is equal to `1`

Checks the page contains a script (an element with the <script> tag) whose content contains the specified text.

Then a javascript with the textpart '$jsTextPart' is included in the source code
  • $jsTextPart - The expected text to be contained in the text of a <script> tag.

Example 140. Checks if the JavaScript code contains 'Hello JavaScript'
Then a javascript with the textpart 'Hello JavaScript' is included in the source code

Set Variable Steps

Save HTML table to the variable

This step allows you to save an HTML table from a specified context into a variable.

For more information, see how to work with table variables

The HTML table must have a header row with <th> tags.
When I save table to $scopes variable `$variableName`
Before using this step, ensure the context is set to the required table. See the example below.
Example 141. Save the first table on the page into a variable named 'table'
When I change context to element located `xpath(//table[1])`
When I save table to SCENARIO variable `table`

Save the number of opened tabs

Saves the number of currently opened tabs in the browser to the variable.

When I save number of open tabs to $scopes variable `$variableName`
Example 142. Save the number of currently opened browser tabs into a variable named 'count'
When I save number of open tabs to SCENARIO variable `count`

Save the CSS property value of the element

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

When I save `$cssProperty` CSS property value of element located by `$locator` to $scopes variable `$variableName`
Example 143. Save the CSS property value of the table
When I save `padding` CSS property value of element located by `xpath(//table)` to scenario variable `paddingValue`
Then `${paddingValue}` is equal to `5px`

Alert Steps

Perform action in the alert box

Accepts the action in popup alert with matching text by clicking on the "OK" button or dismiss it by clicking "Cancel" button.

Actions performed at this step:

  • Finds the appropriate alert with matching message

  • Performs the corresponding action

When I $alertAction alert with message which $comparisonRule `$message`
  • $alertAction - Action to perform. Possible values: ACCEPT, DISMISS.

  • $comparisonRule - String comparison rule.

  • $message - The text message of the alert.

Example 144. Accept popup alert with any text message
When I accept alert with message which matches `.*`

Type text in the alert input field

This step allows you to type text into popup alert input field and then accept the alert.

This step is applicable only for alerts with a single input field. For authorization alerts, basic URL authorization should be used. For example, https://user:pass@domain.com
When I type text `$text` in alert and accept it
  • $text - The text to be typed into the alert input field.

Example 145. Type text 'VIVIDUS' into alert and close it by clicking OK button
When I type text `VIVIDUS` in alert and accept it

Wait for alert appearance

Waits for an popup alert appearance on the current page.

When I wait until alert appears
Example 146. Wait untill an alert appear after click on the button
When I click on element located by `buttonName(Survey)`
When I wait until alert appears
Then an alert is present

Wait for alert disappearance

Waits for an popup alert disappearance from the current page.

When I wait until alert disappears
Example 147. Wait untill an alert disappear after it is accepted
When I click on element located by `buttonName(Survey)`
Then an alert is present
When I accept alert with message which matches `.*`
When I wait until alert disappears
Then an alert is not present

Verify that an alert is present

Checks that there is popup alert on the page.

Then an alert is present
Example 148. Check that an alert appears after clicking on the button
When I click on element located by `buttonName(Survey)`
Then an alert is present

Verify that an alert isn’t present

Checks that there is no any popup alerts on the page.

Then an alert is not present
Example 149. Check that an alert doesn’t appear on the page
Given I am on page with URL `http://example.com`
Then an alert is not present

Verify that no alert displayed during timeout

Checks that no popup alerts displayed during the timeout.

Then alert does not appear in `$timeout`
  • $timeout - Total duration to wait in the ISO-8601 format.

Example 150. Check that an alert doesn’t appear within 7 seconds after page loaded
Given I am on page with URL `http://example.com`
Then alert does not appear in `PT7S`

Wait for a frame with the specified name and switch to it

Waits for a frame with the specified name to appear and then switches to it.

When I wait until frame with name `$frameName` appears and I switch to it
  • $frameName - The name or ID of the expected frame.

Example 151. Wait for a frame with cookieFrame name and switch to it
Given I am on page with URL `http://example.com`
When I wait until frame with name `cookieFrame` appears and I switch to it

Wait for specific title of the current page

Waits until the current page title matches the certain title using specified comparison rule.

When I wait until page title $comparisonRule `$pattern`
Example 152. Check that current title ends with "Domain"
Given I am on page with URL `http://example.com`
When I wait until page title matches `.*Domain`

Slider steps

Steps allow to interact with slider (input element with type = "range").

Set value in the slider

Set the specified value in the slider.

When I set value `$value` in slider located by `$locator`
  • $value - The value to set in the slider. In most cases, it is a numeric value in the range of [0, 100].

  • $locator - The locator used to find a slider.

Example 153. Set the value into the middle of the slider
When I set value `50` in slider located by `id(test_slider)`

Check value of the slider

Check that the actual value in the slider equals to the value provided in the step.

Then value `$value` is selected in slider located by `$locator`
  • $value - The expected value in the slider. In most cases, it is a numeric value in the range of [0, 100].

  • $locator - The locator used to find a slider.

Example 154. Check that the value is set in the middle of the slider
Then value `50` is selected in slider located by `id(test_slider)`

Mobile Emulation

Emulate mobile device

Emulates mobile device using the provided configuration.

The step is only supported by Chrome browser.
When I emulate mobile device with configuration:`$jsonConfiguration`
  • $jsonConfiguration - The JSON containing device metrics to override.

Example 155. Emulate iPhone 14 Pro Max
When I emulate mobile device with configuration:`{
    "width": 430,
    "height": 932,
    "deviceScaleFactor": 3,
    "mobile": true
}`

Reset mobile device emulation

Resets the mobile device emulation returning the browser to its initial state.

The step is only supported by Chrome browser.
The step ignores the web/desktop/chrome/mobile_emulation/phone profile settings when returning the browser to its initial state.
When I reset mobile device emulation
Example 156. Resets device metrics to defaults
When I reset mobile device emulation

Geolocation emulation

Emulate Geolocation

Set the current Geolocation to coordinates with the specified latitude and longitude.

  • The step is only supported by Chrome browser.

  • The step automatically grants the permission to track geolocation in the browser.

When I emulate Geolocation using coordinates with latitude `$latitude` and longitude `$longitude`
Example 157. Set Geolocation to New York, USA
Given I am on page with URL `https://my-location.org`
Then text `Brooklyn, NY` does not exist
When I emulate Geolocation using coordinates with latitude `40.678207` and longitude `-73.944390`
When I refresh page
Then text `Brooklyn, NY` exists

Reset Geolocation emulation

Resets the emulated Geolocation position.

The step is only supported by Chrome browser.
When I reset Geolocation emulation
Example 158. Set Geolocation emulation and reset it
Given I am on page with URL `https://my-location.org`
When I emulate Geolocation using coordinates with latitude `40.678207` and longitude `-73.944390`
When I refresh page
Then text `Brooklyn, NY` exists
When I reset Geolocation emulation
When I refresh page
Then text `Brooklyn, NY` does not exist

Tips & Tricks

Validate URL host of the opened page

To validate host component of the current page URL the following statement can be used:

Example 159. Validate host component of "https://example.com/relative/url/example.html"
Given I am on page with URL `https://example.com/relative/url/example.html`
Then `#{extractHostFromUrl(${current-page-url})}` is equal to `example.com`

Validate URL path of the opened page

To validate path component of the current page URL the following statement can be used:

Example 160. Validate path component of "https://example.com/relative/url/example.html"
Given I am on page with URL `https://example.com/relative/url/example.html`
Then `#{extractPathFromUrl(${current-page-url})}` is equal to `/relative/url/example.html`

Validate URL of the opened page partially

To validate whether current page URL contains some part the following statement can be used:

Example 161. Validate part of "https://example.com/relative/url/example.html"
Given I am on page with URL `https://example.com/relative/url/example.html`
Then `${current-page-url}` matches `.+\/relative\/url.+`
  • ${current-page-url} is the current page URL dynamic variable.

  • .\/relative\/url. is a regular expression to match the expected part of the page URL.