Web Application Plugin: Playwright Engine
The plugin provides functionality to interact with Web applications with help of Playwright engine.
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-playwright', version: '0.6.12')
-
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 |
---|---|---|---|
|
An absolute URL |
|
The URL of the starting page of the web application under test |
|
A relative or absolute path of the directory on the file system |
|
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. |
|
|
|
When tracing with the screenshots option turned on, each trace records a screencast and renders it as a film strip. |
|
|
|
When tracing with the snapshots option turned on, Playwright captures a set of complete DOM snapshots for each action. |
|
ISO-8601 Durations format |
|
Total duration to wait for UI condition |
Locator
By.<locatorType>(<locatorValue>):<visibility>
By. prefix is optional. |
-
locatorType
- [mandatory] type of the locator -
locatorValue
- [mandatory] value of the locator -
visibility
- [optional] visibility of element (visible by default)
Locator Types
Type | Description | Example |
---|---|---|
|
Locates elements whose |
id(submitBtn) |
|
Locates elements matching a CSS selector |
css(.menu-item) |
|
Locates elements matching an xPath expression |
xpath(//a) |
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 1. 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`
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`
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. |
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.
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.
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.
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)`
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.
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.
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.
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`
-
$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`
-
$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 `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. -
$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
coordinatey
the
y
coordinateheight
the
height
of the elementwidth
the
width
of the element
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.
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.
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`
-
$regex
- The regular expression used to validate the context text.
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
-
$locator
- Locator.
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
-
$locator
- Locator.
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
-
$locator
- Locator. -
$comparisonRule
- The comparison rule. -
$number
- The expected number of the 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.
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`
-
$jsCode
- The JavaScript code with return value. -
$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 `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
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`
-
$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
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)`
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)`|
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` |
Cookie Steps
Validate cookie presence
Validates whether the certain cookie is set.
Then cookie with name that $stringComparisonRule `$cookieName` is set
-
$stringComparisonRule
- String comparison rule. -
$cookieName
- The name of the cookie to check presence.
Then cookie with name that is equal to `JSESSIONID` is set
Validate cookie absence
Validates whether the certain cookie is not set.
Then cookie with name that $stringComparisonRule `$cookieName` is not set
-
$stringComparisonRule
- String comparison rule. -
$cookieName
- The name of the cookie to check absence.
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
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`
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
When I select element located by `id(uploadfile)` and upload file `/folder/file_for_upload.png`