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.10')
  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.

Locator

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)

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`

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 9. 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 10. 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 11. 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 12. 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 13. 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 14. 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 15. 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 16. 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 17. 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`

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 18. 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 19. 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 20. 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 21. 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`