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', version: '0.6.12')
  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.

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

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 search value

id(submitBtn)

css

Locates elements matching a CSS selector

css(.menu-item)

xPath

Locates elements matching an xPath expression

xpath(//a)

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

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 9. 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 10. 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 11. 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 12. 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 13. 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 14. 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 15. 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 16. 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 17. Validate the number of elements
Then number of elements found by `xpath(./a)` is equal to `5`

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 18. 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 19. 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 20. 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 21. 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 22. 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 23. 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 24. 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 25. 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.

When I wait until element located by `$locator` appears
Example 26. Wait for appearance of the element with the specified id
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.
When I wait until element located by `$locator` disappears
Example 27. Wait for disappearance of the element with the specified id
When I wait until element located by `id(welcome-image)` disappears

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 28. Wait for the visible elements
When I wait until number of elements located by `xpath(//a)` is equal to `5`

JavaScript steps

Execute JavaScript

Executes passed JavaScript code on the opened page.

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

Example 29. 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 30. 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 31. 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 32. 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

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 33. 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 34. 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 35. 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 36. 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 37. 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 38. 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 39. 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 40. 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 41. 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

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 42. Upload file_for_upload.png file
When I select element located by `id(uploadfile)` and upload file `/folder/file_for_upload.png`