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.11')
-
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
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`
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`