Web Application Plugin: Playwright Engine

The plugin provides functionality to interact with Web applications with help of Playwright engine.

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-playwright')
  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_pw/desktop/chromium - for Google Chrome, Microsoft Edge and other Chromium-based browsers, by default, Playwright uses open source Chromium builds.

  • web_pw/desktop/firefox - Playwright’s Firefox version matches the recent Firefox Stable build.

  • web_pw/desktop/webkit - Playwright’s WebKit version matches the recent WebKit trunk build, before it is used in Apple Safari and other WebKit-based browsers.

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_pw/headless/chromium - for Google Chrome, Microsoft Edge and other Chromium-based browsers, by default, Playwright uses open source Chromium builds.

  • web_pw/headless/firefox - Playwright’s Firefox version matches the recent Firefox Stable build.

  • web_pw/headless/webkit - Playwright’s WebKit version matches the recent WebKit trunk build, before it is used in Apple Safari and other WebKit-based browsers.

Properties

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

web-application.main-page-url

An absolute URL

<empty>

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

playwright.tracing.output-directory

A relative or absolute path of the directory on the file system

${output.report-directory}/playwright-traces

When any tracing option is enabled, the traces are recorded and saved to the specified directory. Every session is stored in the own file, the full path to the file is printed in the logs.

playwright.tracing.screenshots-enabled

true
false

false

When tracing with the screenshots option turned on, each trace records a screencast and renders it as a film strip.

playwright.tracing.snapshots-enabled

true
false

false

When tracing with the snapshots option turned on, Playwright captures a set of complete DOM snapshots for each action.

ui.wait.timeout

ISO-8601 Durations format

PT1M

Total duration to wait for UI condition

Dynamic variables

Context source code

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

${context-source-code}
Example 2. 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

Locator

By.<locatorType>(<locatorValue>):<visibility>
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)

Locator Types

Type Description Example

id

Locates elements whose id attribute matches the specified search value.

id(submitBtn)

css

Locates elements matching a CSS selector.

css(.menu-item)

xPath

Locates elements matching an xPath expression.

xpath(//a)

tagName

Locates elements whose tag name matches the specified search value. This locator is translated to css(<tagName>) locator.

tagName(div)

className

Locates elements whose class name matches the specified search value. This locator is translated to css(.<className>) locator.

className(bold)

linkText

Locates elements whose text of the link matches the specified search value.

linkText(Google)

linkUrl

Locates elements whose href attribute matches the specified search value. This locator is translated to css([href='<tagName>']) locator.

linkUrl(/faq)

linkUrlPart

Locates elements whose part of href attribute matches the specified search value. This locator is translated to css([href*='<tagName>']) locator.

linkUrlPart(faq)

imageSrc

Locates elements whose src attribute matches the specified search value. This locator is translated to css(img[src='<imageSrc>']) locator.

imgSrc(/images/kote.png)

imageSrcPart

Locates elements whose part of src attribute matches the specified search value. This locator is translated to css(img[src*='<imageSrc>']) locator.

imgSrcPart(kote.png)

fieldName

Locate elements that are either input or textarea and their text or any attribute value matches the specified search value.

fieldName(editor)

radioButton

Locate elements that are input with @type="radio" and their label text value matches the specified searh value

radioButton(One)

name

Locate elements where any attribute or text value matches the specified search value. This locator is translated to xpath(.//*[@*='<elementName>' or text()='<elementName>']) locator.

name(OK)

Visibility types

Visibility type Usage example Description

VISIBLE

xpath(//a)

Default visibility option. Only visible elements will be found

all

xpath(//a):a

Either visible and invisible elements will be found

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 3. 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 4. 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 5. Validate 'https://docs.vividus.dev/' page title
Then page title is equal to `What is VIVIDUS :: VIVIDUS`
Example 6. 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 7. 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 8. 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 9. 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 10. 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

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 11. Open page in a new tab
When I open new tab
Given I am on page with URL `https://docs.vividus.dev`

Close current tab

Closes the current tab and switches to the last browser tab.

When I close current tab
This step can only be applied to a session with multiple tabs open.
Example 12. 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 new tab
Given I am on page with URL `https://example.com/contact-us`
When I close current tab

Mouse Actions

Click on the element

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

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

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

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 14. 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 15. 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 16. 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 17. 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.

When I clear field located by `$locator`
  • $locator - The locator used to find the field to clear.

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

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 19. 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 20. 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 21. 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 into a variable.

When I save text of context 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 22. Save the text of the context
When I change context to element located by `id(username)`
When I save text of context element to scneario variable `username`

Saves the attribute value of the context

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

When I save `$attributeName` attribute value of context element to $scopes variable `$variableName`
Example 23. 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`

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 24. 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 25. 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`

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 26. 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 27. 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 28. 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`

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 29. 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 30. 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 31. Verify that the element become invisible up to 10 times
When I wait `PT10S` with `PT1S` polling until element located by `id(element-to-hide)` becomes not visible

Wait for element appearance with timeout

Waits for appearance of the element by the locator with desired timeout.

It’s forbidden to use Visibility types in the locator.
When I wait until element located by `$locator` appears in `$timeout`

Deprecated syntax web ONLY (will be removed in VIVIDUS 0.8.0):

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 32. Click on the button and waiting for element appearance for 2 minutes
When I click on element located by `buttonName(Show element)`
When I wait until element located by `id(element-to-show)` appears in `PT2M`

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 33. The element should have text consisting of numbers only
When I wait until element located by `id(indicator)` has text matching `\d+`

Wait for element state

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

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 34. Click on the button and wait until the element becomes invisible
When I click on element located by `id(signInButton)`
When I wait until state of element located by `id(signInButton):a` is NOT VISIBLE

Wait for expected elements number

Waits for the expected number of elements located by locator.

When I wait until number of elements located by `$locator` is $comparisonRule $number
Example 35. Wait for the visible elements
When I wait until number of elements located by `xpath(//a)` is equal to `5`

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

Wait for element appearance in viewport

Waits for an element to appear in the browser viewport.

When I wait until element located by `$locator` appears in viewport
  • $locator - The locator used to find element.

Example 37. Wait for element appearance in viewport
When I scroll element located by `id(items-list)` into view
When I wait until element located by `id(sticky-items-filter)` appears in viewport

JavaScript steps

Execute JavaScript

Executes passed JavaScript code on the opened page.

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

Example 38. 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 and save result

Executes passed JavaScript code on the opened page and saves result into variable.

When I execute javascript `$jsCode` and save result to $scopes variable `$variableName`
Example 39. Validate timings
Given I am on page with URL `https://vividus-test-site-a92k.onrender.com/`
When I execute javascript `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

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
Example 40. 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`
  • $locator - Locator of frame element.

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

Select an option in dropdown

Selects the first option in dropdown whose value attribute is equal to the provided value (case-insensitive).

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

  • $locator - The locator used to find dropdown.

Example 42. Select option with the value Red in dropdown
When I select `Red` in dropdown located by `id(colors)`

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 43. 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)`

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 44. 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)`|

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

Validates whether the certain cookie is set.

Then cookie with name that $stringComparisonRule `$cookieName` is set
Example 46. 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 47. 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.

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 48. Set the cookie for the current domain
When I set all cookies for current domain:
|cookieName   |cookieValue |path |
|cookieAgreed |2           |/    |

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

When I remove cookie with name `$cookieName` from current domain
  • $cookieName - The name of the cookie to remove.

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

Remove all cookies

Removes all cookies from the current domain.

When I remove all cookies from current domain

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 52. 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 53. 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 54. 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 55. 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 56. 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 57. Clear session storage
When I clear session storage

Upload file

Uploads the resource or file via web interface.

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

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

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

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 59. 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 60. 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 61. 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 62. 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

Request validation steps

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 network recording to be turned on. It can be done in properties via "proxy.recording.enabled" or by switching on "@proxy" meta tag at the story or scenario level.

The actions performed by the step:

  • extract HTTP messages from the network recording archive

  • 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

When I capture HTTP $httpMethods request with URL pattern `$urlPattern` and save $httpMessagePart to $scopes variable `$variableName`
  • $httpMethods - The comma-separated set of HTTP methods to filter by, e.g. GET, POST, 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.

      • resourceType - The request’s resource type as it was perceived by the rendering engine. resourceType will be one of the following: document, stylesheet, image, media, font, script, texttrack, xhr, fetch, eventsource, websocket, manifest, other.

      • requestBody.contentType - The MIME type of posted data.

      • requestBody.text - The posted data as plain text.

      • responseStatus - The response status.

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

      • responsetBody.contentType - The MIME type of received data.

      • responsetBody.text - The received data as plain text.

Example 63. 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,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 64. 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 65. Validate the request and response data from the matching HTTP messages
Given I am on page with URL `https://httpbingo.org/forms/post`
When I click on element located by `xpath(//input[@value='cheese'])`
When I click on element located by `xpath(//button)`
When I capture HTTP POST request with URL pattern `https://httpbingo\.org/post` and save request data to SCENARIO variable `requestData`
Then `${requestData.query}` is equal to `{}`
Then `${requestData.resourceType}` is equal to `document`
Then `${requestData.requestBody}` is not equal to `null`
Then `${requestData.responseStatus}` is equal to `200`
When I capture HTTP POST request with URL pattern `https://httpbingo\.org/post` and save response data to SCENARIO variable `responseData`
Then `${responseData.responseBody}` matches `.*"topping":.*"cheese".*`

Wait for the HTTP request

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.

This step requires network recording to be turned on. It can be done in properties via "proxy.recording.enabled" or by switching on "@proxy" meta tag at the story or scenario level.
When I wait until HTTP $httpMethods request with URL pattern `$urlPattern` is captured
  • $httpMethods - The comma-separated HTTP methods to filter by, e.g. GET,POST,PUT.

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

Example 66. 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 request with URL pattern `.*/search.*=vividus` is captured

Clear the network recordings

The step clears recorded HTTP requests.

When I clear network recordings
Example 67. Clear the recorded data
Given I am on page with URL `https://www.google.com/search?q=vividus`
When I wait until HTTP GET request with URL pattern `.*/search.*=vividus` is captured
When I clear network recordings

Execute sequence of actions

Executes the sequence of web actions.

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

    Table 2. Possible actions
    type argument Argument example

    CLICK

    Element locator or empty.

    By.caseSensitiveText(Done)

    DOUBLE_CLICK

    Element locator. Empty value is not supported.

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

    CLICK_AND_HOLD

    Element locator or empty.

    By.linkText(Click me)

    RELEASE

    Element locator or empty.

    By.tagName(div)

    ENTER_TEXT

    Text to type.

    Minsk City

    PRESS_KEYS

    Comma-separated keys to press and release.

    Backspace

    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)

Use special Playwright Control key - ControlOrMeta to make tests fully platform independent.

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

This step can be used to perform clipboard interactions.

Example 69. 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 70. Paste text from the clipboard to the focused field on MacOS
When I execute sequence of actions:
|type      |argument |
|KEY_DOWN  |Meta, v  |
|KEY_UP    |v, Meta  |
Example 71. 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  |ControlOrMeta, a |
|KEY_UP    |a, ControlOrMeta |
|KEY_DOWN  |ControlOrMeta, c |
|KEY_UP    |c, ControlOrMeta |

Close browser

Closes the browser.

When I close browser
Example 72. Browser restart
Given I am on page with URL `https://vividus-test-site-a92k.onrender.com`
Then number of elements found by `xpath(//img)` is = `1`
When I execute javascript `document.querySelector('[name="vividus-logo"]').remove()`
Then number of elements found by `xpath(//img)` is = `0`
When I close browser
Given I am on page with URL `https://vividus-test-site-a92k.onrender.com`
Then number of elements found by `xpath(//img)` is = `1`

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`
  • $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 73. 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`