Web Application Plugin
The plugin provides functionality to interact with Web applications.
Installation
-
Copy the below line to
dependencies
section of the projectbuild.gradle
filePlease make sure to use the same version for all VIVIDUS dependencies. Example 1. build.gradleimplementation(group: 'org.vividus', name: 'vividus-plugin-web-app', version: '0.6.4')
-
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.
Properties
The properties marked with bold are mandatory. |
Property Name | Acceptable values | Default | Description |
---|---|---|---|
|
Valid target platform name |
empty |
Identifies the operating system for the testing. e.g. |
|
Valid target platform version |
empty |
Identifies the operating system version for the testing. e.g. |
|
hostname |
|
The host of Selenium Grid used to create a new session. |
|
username |
|
The username for authentication at Selenium Grid used to create a new session. |
|
password |
|
The password for authentication at Selenium Grid used to create a new session. |
|
|
|
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. |
|
ISO-8601 Durations format |
|
The maximum amount of time to wait for HTTP response from Selenium Grid. |
|
|
|
The test lifecycle of the browser:
An empty property value will lead to the error: "Application session scope is not set". |
|
|
|
Whether to publish the application source code on failure or not |
|
|
|
If the value is set to |
|
ISO-8601 Durations format |
|
Total duration to wait for UI condition |
|
ISO-8601 Durations format |
|
Used together with |
|
The value between 0 and 1 e.g. 0.75 |
|
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. |
|
|
|
Enable proxy for the whole test run |
|
|
|
Enable proxy recording |
|
any host name resolving on the machine |
|
Overrides the host which will be used by proxy |
|
ports range (e.g., |
|
Ports range which could be occupied for proxy |
|
|
|
Overrides the proxy host which will be passed to browser |
|
|
|
Enables publishing of attachments with HAR to each failed step. |
|
|
|
Whether to disable verification of upstream servers SSL certificates |
|
HAR capture types: |
|
List of HAR capture types |
|
|
|
Whether to enable MITM proxy for the whole test run |
|
|
|
The MITM type using the corresponding certificates. |
|
keystore type |
|
The keystore type |
|
path to keystore |
|
The relative to |
|
password for keystore |
|
The password for keystore |
|
keystore alias |
|
The alias for certificate entry in keystore |
|
|
|
Provides possibility to attach screenshot for failed proxy steps |
|
|
Sets the amount of time to wait for a page load to complete before throwing an error. |
|
|
|
Sets the amount of time to wait for an asynchronous script to finish execution before throwing an error. |
|
|
string with arguments |
|
|
|
An absolute URL |
|
The URL of the strating page of the web application under test |
|
header size as a viewport size percent |
|
Before the click VIVIDUS scrolls element into the viewport, the property defines top edge indent in viewport percent for the scroll |
How to configure user preferences for Chrome browser?
In addition to the command line arguments, user preferences (see the Preferences file in Chrome’s user data directory or open chrome://prefs-internals/
link in Chrome browser for examples) can be customised.
Here is an example how to configure third-party cookies behaviour.
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.
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.
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})}`
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
Image binary data. |
Dynamic variables
Current page URL
The variable provides the URL of the page currently loaded in the browser.
${current-page-url}
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 |
---|---|
|
the height of the browser window |
|
the width 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
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 |
---|---|
|
the height of the context element |
|
the width of the context element |
|
the absolute |
|
the absolute |
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`
Profiles
Profiles allow to choose or parameterize browser that tests run on. See more details on the profiles and nesting strategy on the configuration page.
Web-application plugin contains significant number of built-in profiles. They can be found after plugin installation by the following path in Eclipse IDE:
Referenced Libraries -> vividus-plugin-web-app-X.Y.Z -> properties -> profile -> web
Let’s go through the structure and review its content.
Desktop
General place for web profiles. Each of the directory contains browser related properties. This is a place for adjustments for your browser. Add there any properties you need: screen resolution, path to driver or to a custom browser.
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
List of desktop profiles
Profile | Example of properties | ||
---|---|---|---|
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
Mobile emulation
-
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.
-
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
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
-
web/headless/firefox
-
web/headless/edge
Docker
The profile can be enabled by adding web/docker
to configuration.profiles
property. The profile should be used together with the browser profile.
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.
|
configuraiton.profiles=web/docker,web/desktop/chrome
Phone
Contains phone related properties, for android and iOS devices.
Profile | Example of properties |
---|---|
web/phone/android |
|
web/phone/ios |
|
Tablet
Similar to the Phone directory, but is designed for tablets properties.
Profile | Example of properties |
---|---|
web/tablet |
|
Locator
By.<locatorType>(<locatorValue>):<visibility>->filter.<filterType>(<filterValue>)
By. prefix is optional. |
-
locatorType
- [mandatory] type of the locator -
locatorValue
- [mandatory] value of the locator -
visibility
- [optional] visibility of element (visible by default) -
filterType
- [optional] type of the filter -
filterValue
- [required if filter type defined] value of the filter
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.
ui.locator.<locatorName>.pattern
ui.locator.<locatorName>.locator-type
-
locatorName
- The name of the reusable locator. Supported characters areA-Z, a-z, -
. -
pattern
- The pattern of the reusable locator. -
locator-type
- The base locator type.
ui.locator.anyAttOrText.locator-type=xpath
ui.locator.anyAttOrText.pattern=//*[@*='%s' or text()='%s']
Given I am on main application page
Then number of elements found by `anyAttOrText(attribute, text)` is = `1`
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. |
|
|
|
The pattern with a single parameter was referenced twice. |
|
|
|
The pattern with a |
|
|
|
The pattern containing |
|
|
|
The pattern without parameters |
|
|
|
The pattern with two parameter placeholders was used with invalid number of parameters. |
|
|
|
Locator Types
Type | Description | Example |
---|---|---|
|
Locates elements whose |
id(submitBtn) |
|
Locates elements matching a CSS selector |
cssSelector(.menu-item) |
|
Locates elements matching an xPath expression |
xpath(//a) |
|
Locates elements matching an xPath expression.
Unlike |
unnormalizedXPath(//li[text()='ID: testId']) |
|
name of an element tagName |
tagName(a) |
|
CSS class name |
className(bold) |
|
text of the link |
linkText(Google) |
|
href attribute of the link element |
linkUrl(/faq) |
|
part of a href attribute of the link element |
linkUrlPart(faq) |
|
case sensitive text of an element |
caseSensitiveText(Description) |
|
case insensitive text of an element |
caseInsensitiveText(description) |
|
shortcut to a .//img[@src='<value>>'] |
imgSrc(/images/kote.png) |
|
shortcut to a .//img[contains(@src,'<value>>')]'] |
imgSrcPart(kote.png) |
|
elements of type button or input with text or any attribute value |
buttonName(submit) |
|
input or textarea with text or any attribute value |
fieldName(editor) |
|
input element with @type="radio" and label text value |
radioButton(One) |
|
input element with @type="checkbox" and text value |
checkboxName(allow) |
|
any attribute or text value |
elementName(OK) |
|
chain of css selectors, separated by |
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 |
---|---|---|
|
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) |
|
Filter elements by their text parts. |
tagName(h3)→filter.textPart(Welcome) |
|
Filter elements by their attribute values |
|
|
element State |
id(v1)→filter.state(VISIBLE) |
|
element text should match case sensitively |
id(v1)→filter.caseSensitiveText(text) |
|
class attribute should contain part |
id(v1)→filter.classAttributePart(clazz) |
|
href attribute of the link element |
id(v1)→filter.linkUrl(/url) |
|
part of href attribute of the link element |
id(v1)→filter.linkUrlPart(/url) |
|
title attribute value |
id(v1)→filter.tooltip(title) |
|
src attribute should contain value |
id(v1)→filter.imageSrcPart(part) |
|
Placeholder attribute should be equal to a value |
id(v1)→filter.placeholder(placeholder-value) |
|
CSS property background-image should match |
id(v1)→filter.validationIconSource(src) |
|
field text should match expected value |
id(v1)→filter.fieldText(value) |
|
field text should contain expected value |
id(v1)→filter.fieldTextPart(value) |
|
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`
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`
-
relativeUrl
- A relative URL pointing to a resource within a website (e.g.about.html
or/products
). If the relative URL starts with '/' char, the navigation will be performed from the root. Otherwise the navigation will be performed from the current URL path.Table 2. Examples Current page URL Relative URL parameter Resulting page URL about.html
/products/new
stats
./docs/info.html
/documents
Given I am on main application page
When I go to relative URL `/products/new`
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.
Then page title is equal to `What is VIVIDUS :: VIVIDUS`
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.
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.
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
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`
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:
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.
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.
id
attribute having value send
and validate page is not refreshed after the actionWhen 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.
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.
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.
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.
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.
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.
id
having value email
using keyboardWhen 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 |
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.
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.
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
Then page is scrolled to element located by `$locator`
-
$locator
- The locator used to find element.
Then page is scrolled to element located by `xpath(//a[text()="Contact"])`
Text validation steps
Validate the text exists
Validates that the text is presented in the current context. Expected text is case sensitive.
The context can be set by the corresponding steps. If no context is set, the text will be searched on the whole page.
Then text `$text` exists
-
$text
- Expected text.
Given I am on page with URL `https://docs.vividus.dev/`
Then text `Contract Us` exists
Validate the text does not exists
Validates that the text is not presented in the current context.
The context can be set by the corresponding steps. If no context is set, the text will be searched on the whole page.
Then text `$text` does not exist
-
$text
- Text that should not exist.
When I change context to element located by `id(code)`
Then text `Deprecated` does not exist
Validate the text matches regex
Validates that the text from current context matches the specified regular expression.
The context can be set by the corresponding steps. If no context is set, the text will be searched on the whole page.
Then text matches `$regex`
Deprecated syntax (will be removed in VIVIDUS 0.7.0):
Then the text matches '$regex'
-
$regex
- The regular expression used to validate the text of the context.
When I change context to element located by `id(code)`
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
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.
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. |
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` .
|
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 executeTable 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. |
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 39. Select all text in the focused field and copy it to the clipboard on Windows
Example 40. Paste text from the clipboard to the focused field on MacOS
Example 41. Select all text in the focused field and copy it to the clipboard on any OS
|
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:
|
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.
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.
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.
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. -
$variableName
- The name of the variable to save the value of the barcode.
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.*`
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.
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
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
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.
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
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`
-
$stringComparisonRule
- String comparison rule. -
$tabName
- The expected tab title.
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
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
-
$duration
- The timeout duration to wait for a tab in ISO-8601 Durations format. -
$comparisonRule
- The tab title comparison rule. -
$title
- The expected tab title.
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 |
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.
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`
-
$webPerformanceMetric
- The web performance metric. Where:-
TIME_TO_FIRST_BYTE
- The time between the navigation start and the response start. -
DNS_LOOKUP_TIME
- The time between the domain lookup start and the domain lookup end. -
DOM_CONTENT_LOAD_TIME
- The time between the DOM loading and the the DOM complete. -
PAGE_LOAD_TIME
- The time between the navigation start and the load event end.
-
-
$comparisonRule
- The duration comparison rule. -
$duration
- The duration to compare against in ISO-8601 Durations format.
Given I am on page with URL `https://example.com`
Then metric PAGE_LOAD_TIME is less than `PT5S`
Taking screenshot steps
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
.
-
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
-
$locator
- Locator.
When I wait until element located by `name(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
-
$locator
- Locator.
When I wait until element located by `name(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
When I wait `PT10S` with `PT1S` polling until element located by `id(element-to-hide)` becomes not visible
Wait for expected elements number
Waits for the expected number of elements located by locator.
In order to wait for invisible elements one rely on Visibility types. |
When I wait until number of elements located by `$locator` is $comparisonRule $number
-
$locator
- Locator. -
$comparisonRule
- The comparison rule. -
$number
- The expected number of the elements.
When I wait until number of elements located by `tagName(img)` is equal to `5`
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
-
$locator
- Locator.
When I wait until element located by `id(submitForm)` stops moving
Verify elements number
Verifies if the number of elements located by locator matches the desired number.
Then number of elements found by `$locator` is $comparisonRule `$quantity`
-
$locator
- Locator. -
$comparisonRule
- The comparison rule. -
$quantity
- The expected number of the elements.
Then number of elements found by `tagName(img)` 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 ':i' and 'NOT_VISIBLE') exception will be thrown. In such cases please use step: Verify elements number. Contradictory visibility parameters (locator - ':i' and checked state - 'VISIBLE') are also not allowed. |
Then number of $state elements found by `$locator` is $comparisonRule `$quantity`
-
$state
- State -
$locator
- Locator. -
$comparisonRule
- The comparison rule. -
$quantity
- The expected number of elements.
Then number of VISIBLE elements found by `tagName(img)` is = `1`
Save text of an element
Saves text of an element into a variable.
When I save text of element located by `$locator` to $scopes variable `$variableName`
-
$locator
- Locator. -
$variableName
- The name of the variable to save the text.
When I save text of element located by `tagName(h1)` to scenario variable `headingText`
Save the text of the context
Saves the text of the context element into a variable.
Step will throw an error if the context element is not set. |
When I save text of context element to $scopes variable `$variableName`
-
$variableName
- The name of the variable to save the text.
When I change context to element located by `id(username)`
When I save text of context element to SCENARIO variable `username`
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`
-
$attributeName
- The name of an element attribute. -
$variableName
- The name of the variable to save the attribute value.
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`
-
$attributeName
- The name of an element attribute. -
$locator
- Locator. -
$variableName
- The name of the variable to save the attribute value.
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`
-
$locator
- Locator. -
$variableName
- The name of the variable to save the number of elements.
When I save number of elements located by `tagName(a)` to scenario variable `numberOfLinks`
Then `${numberOfLinks}` is equal to `1`
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.
Then element located by `id(banner)` exists for `PT5S` duration
Wait until element has text matching regular expression
Waits until an element with the specified locator has text that matches the provided regular expression.
When I wait until element located by `$locator` has text matching `$regex`
-
$locator
- The Locator of the element which text to check. -
$regex
- The regular expression used to validate the text of the element.
When I wait until element located by `id(indicator)` has text matching `\d+`
Verify elements order
Gets a collection of elements by locator and checks that they are sorted by their text in the specified order. The collection should have more than 1 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 |
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 |
---|---|---|
|
|
|
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`
-
$variableName
- The name of the variable to save the value of the 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.
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 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. Eitherstring
orobject
.
-
When I execute javascript `document.querySelector('#assistant').remove()` with arguments:
When I execute javascript `sauce:inject-image` with arguments:
|value |type |
|iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=|string|
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`
-
$jsCode
- Any JavaScript code. In order to save a result return statement should be used. -
$variableName
- The variable name to script execution result.
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 |
---|---|---|
|
|
|
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`
-
$variableName
- The name of the variable to save the value of 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
When I select element located by `id(uploadfile)` and upload file `/folder/file_for_upload.png`
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`
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.
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
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.
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.
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
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.
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
ornot in focus
.
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
ornot in focus
.
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
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
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.
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.
When I select `Red` in dropdown located by `id(colors)`
Cookie Steps
Validate cookie presence
Validates whether the certain cookie is set.
Then cookie with name `$cookieName` is set
-
$cookieName
- The name of the cookie to check presence.
Then cookie with name `JSESSIONID` is set
Validate cookie absence
Validates whether the certain cookie is not set.
Then cookie with name `$cookieName` is not set
-
$cookieName
- The name of the cookie to check absence.
Then cookie with name `JSESSIONID` is not set
Set cookies
Adds the cookies provided in the input ExamplesTable. It’s allowed to add the cookies for the current domain only: make sure the web browser is opened at the expected domain. The actions performed by the step:
-
add the cookies;
-
refresh the current page (this action is required to apply the changes in cookies).
When I set all cookies for current domain:$parameters
-
$parameters
- The parameters of the cookies to set as ExamplesTable:Column Name Description cookieName
the name of the cookie to set
cookieValue
the value of the cookie to set
path
the path of the cookie to set
When I set all cookies for current domain:
|cookieName |cookieValue |path |
|cookieAgreed |2 |/ |
Get cookie value
Finds the cookie by the name and saves its value to a variable.
When I save value of cookie with name `$cookieName` to $scopes variable `$variableName`
-
$cookieName
- The name of the cookie to save the value. -
$variableName
- The variable name to save the cookie value.
When I save value of cookie with name `JSESSIONID` to scenario variable `session-id`
Get cookie
Finds the cookie by the name and saves all its parameters as JSON to a variable.
When I save cookie with name `$cookieName` as JSON to $scopes variable `$variableName`
-
$cookieName
- The name of the cookie to save. -
$variableName
- The variable name to save the cookie.
When I save cookie with name `JSESSIONID` as JSON to scenario variable `session-id`
Remove cookie
Removes the certain cookie from the current domain. The actions performed by the step:
-
remove the certain cookie the from current domain;
-
refresh the current page (this action is required to apply the changes in cookies).
When I remove cookie with name `$cookieName` from current domain
-
$cookieName
- The name of the cookie to remove.
When I remove cookie with name `JSESSIONID` from current domain
Remove cookie without apply
Removes the certain cookie from the current domain, but does not apply the changes in cookies. The current page must be refreshed or the navigation must be performed to apply the cookie changes.
When I remove cookie with name `$cookieName` from current domain without applying changes
-
$cookieName
- The name of the cookie to remove.
When I remove cookie with name `JSESSIONID` from current domain without applying changes
When I refresh page
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: eitherlocal
orsession
. -
$key
- The name of the key to retrieve the value of. -
$variableName
- The name of the variable to store the value of the web 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: eitherlocal
orsession
. -
$key
- The name of the key to create/update. -
$value
- The value to give the key that is creating/updating.
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: eitherlocal
orsession
. -
$key
- The name of the key to check presence.
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: eitherlocal
orsession
. -
$key
- The key of the local storage item to check absence.
Then local storage item with key `token` does not exist
Proxy Steps
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
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.
-
-
-
$variableName
- The variable name to save the HTTP message part.
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`
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]}`
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`
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` 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
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` exists in proxy log
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
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 proxy log
Given I am on page with URL `https://www.google.com/search?q=vividus`
When I clear proxy log
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
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
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
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
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.
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.
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. -
$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
-
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.
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`
-
$jsCode
- Any JavaScript code. In order to save a result return statement should be used. -
$variableName
- The variable name to save the cookie value.
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 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 element. -
$timeout
- The maximum time to wait for the element disappearance in ISO-8601 Durations format.
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'
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`
-
$variableName
- The variable name to refer to the variable value.
Before using this step, ensure the context is set to the required table. See the example below. |
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`
-
$variableName
- The variable name to refer to the variable value.
When I save number of open tabs to SCENARIO variable `count`
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.
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.
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
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
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
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
Given I am on page with URL `http://example.com`
Then an alert is not present
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.
cookieFrame
name and switch to itGiven 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`
-
$comparisonRule
- String comparison rule. -
$pattern
- The expected title pattern of the current page.
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.
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.
Then value `50` is selected in slider located by `id(test_slider)`
Tips & Tricks
Validate URL host of the opened page
To validate host component of the current page URL the following statement can be used:
Given I am on page with URL `https://example.com/relative/url/example.html`
Then `#{extractHostFromUrl(${current-page-url})}` is equal to `example.com`
-
${current-page-url}
is the current page URL dynamic variable.
Validate URL path of the opened page
To validate path component of the current page URL the following statement can be used:
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`
-
${current-page-url}
is the current page URL dynamic variable.
Validate URL of the opened page partially
To validate whether current page URL contains some part the following statement can be used:
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.