Web Application Plugin
The plugin provides functionality to interact with Web applications.
Installation
implementation(group: 'org.vividus', name: 'vividus-plugin-web-app', version: '0.3.7')
Locator
By.<locatorType>(<locatorValue>):<visibility>->filter.<filterType>(<filterValue>)
By. prefix is optional. |
-
locatorType
- [mandatory] type of the locator -
locatorValue
- [mandatory] value of the locator -
visibility
- [optional] visibility of element (visible by default) -
filterType
- [optional] type of the filter -
filterValue
- [required if filter type defined] value of the filter
Locator Types
Type | Description | Example |
---|---|---|
linkText |
text of the link |
linkText(Google) |
linkUrl |
href attribute of the link element |
linkUrl(/faq) |
linkUrlPart |
part of a href attribute of the link element |
linkUrlPart(faq) |
caseSensitiveText |
case sensitive text of an element |
caseSensitiveText(Description) |
caseInsensitiveText |
case insensitive text of an element |
caseInsensitiveText(description) |
XPath |
xpath(//a) |
|
cssSelector |
CSS selector to an element |
cssSelector(.menu-item) |
tagName |
name of an element tagName |
tagName(a) |
imageSrc |
shortcut to a .//img[@src='<value>>'] |
imgSrc(/images/kote.png) |
imageSrcPart |
shortcut to a .//img[contains(@src,'<value>>')]'] |
imgSrcPart(kote.png) |
buttonName |
elements of type button or input with text or any attribute value |
buttonName(submit) |
fieldName |
input or textarea with text or any attribute value |
fieldName(editor) |
checkboxName |
input element with @type="checkbox" and text value |
checkboxName(allow) |
id |
id attribute of an element |
id(submitForm) |
className |
CSS class name |
className(bold) |
elementName |
Any attribute or text value |
elementName(OK) |
Visibility types
Visibility type | Usage example | Description |
---|---|---|
VISIBLE |
xpath(//a) |
Default visibility option. Only visible elements will be found |
INVISIBLE |
xpath(//a):i |
Only invisible elements will be found |
all |
xpath(//a):a |
Either visible and invisible elements will be found |
Filter types
Filter are applied after elements search via locator. Elements not matching filter condition will be sorted out without additional notice.
Filter type | Description | Example |
---|---|---|
state |
element State |
id(v1)→filter.state(VISIBLE) |
caseSensitiveText |
element text should match case sensitively |
id(v1)→filter.caseSensitiveText(text) |
classAttributePart |
class attribute should contain part |
id(v1)→filter.classAttributePart(clazz) |
linkUrl |
href attribute of the link element |
id(v1)→filter.linkUrl(/url) |
linkUrlPart |
part of href attribute of the link element |
id(v1)→filter.linkUrlPart(/url) |
tooltip |
title attribute value |
id(v1)→filter.tooltip(title) |
imageSrcPart |
src attribute should contain value |
id(v1)→filter.imageSrcPart(part) |
textPart |
text of an element should contain value |
id(v1)→filter.textPart(part) |
placeholder |
Placeholder attribute should be equal to a value |
id(v1)→filter.placeholder(placeholder-value) |
validationIconSource |
CSS property background-image should match |
id(v1)→filter.validationIconSource(src) |
fieldText |
field text should match expected value |
id(v1)→filter.fieldText(value) |
fieldTextPart |
field text should contain expected value |
id(v1)→filter.fieldTextPart(value) |
dropDownText |
any of select options should be equal to a value |
id(v1)→filter.dropDownText(value) |
index |
Get an element by the specified index from a collection of elements found by a locator. Indexes start from 1. |
tagName(div)→filter.index(2) |
textPart |
Filter elements by their text parts. |
tagName(h3)→filter.textPart(Welcome) |
Properties
Property Name | Acceptable values | Default | Description |
---|---|---|---|
|
|
|
Defines the test lifecycle of the browser:
An empty property value will lead to the error: "Application session scope is not set". |
ui.publish-source-on-failure |
true/false |
true |
Defines if Vividus publishes the application source code on failure |
selenium.grid.host |
hostname |
empty |
Defines remote grid host to be used to create a new session |
selenium.grid.username |
username |
empty |
Defines remote grid username to be used to create a new session |
selenium.grid.password |
password |
empty |
Defines password to be used to create a new session |
screenshot.on-failure.debug-modes |
proxy |
empty |
Provides possibility to attach screenshot for failed proxy steps |
proxy.enabled |
true/false |
false |
Enabled proxy for the run |
proxy.host |
any host name resolving on the machine |
empty |
Overrides the host which will be used by proxy |
proxy.ports |
10000-10005 |
empty |
Defines ports range which could be used for proxy |
proxy.connectable-host |
host.docker.internal |
empty |
Overrides the proxy host which will be passed to browser |
Steps
Open URL in a new tab
Opens a new tab, switches to the opened tab and loads the given URL
When I open URL `$URL` in new window
-
$URL
- The URL to open
When I open URL `https://docs.vividus.dev` in new window
Stop page loading
Stops page loading
When I stop page loading
Could be useful in combination with Selenium’s page load strategy |
When I open URL `https://delayed.vividus.dev` in new window
When I stop page loading
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 |
When I change context to element located `id(login)`
When I scroll context to BOTTOM edge
Scroll element into view
Scrolls an element into the view.
When I scroll element located `$locator` into view
-
$locator
- Locator
When I scroll element located `id(way_down_button)` into view
Execute sequence of actions
Executes the sequence of web actions
When I execute sequence of actions: $actions
-
$actions
- table of actions to execute
Possible actions
Type | Argument | Example |
---|---|---|
DOUBLE_CLICK |
Search attribute or empty value |
By.linkUrl(http://httpbin.org) |
CLICK_AND_HOLD |
Search attribute or empty value |
By.linkText(Click me) |
MOVE_BY_OFFSET |
Point |
(10, 15) where x is 10 and y is 15 |
RELEASE |
Search attribute or empty value |
By.tagName(div) |
ENTER_TEXT |
Text |
Minsk City |
CLICK |
Search attribute or empty value |
By.caseSensitiveText(Done) |
PRESS_KEYS |
Press Keys |
BACK_SPACE |
KEY_DOWN |
Press Keys SHIFT, ALT or CONTROL simultaneously |
CONTROL,SHIFT,ALT |
KEY_UP |
Release Keys SHIFT, ALT or CONTROL simultaneously |
CONTROL,SHIFT,ALT |
MOVE_TO |
Search attribute |
By.id(username) |
When I execute sequence of actions:
|type |argument |
|DOUBLE_CLICK |By.fieldText(Hello World) |
|DOUBLE_CLICK | |
|CLICK_AND_HOLD|By.xpath(//signature-pad-control/canvas)|
|CLICK_AND_HOLD| |
|MOVE_BY_OFFSET|(-300, 0) |
|RELEASE |By.xpath(//signature-pad-control/canvas)|
|RELEASE | |
|ENTER_TEXT |Text |
|CLICK |By.placeholder(Enter your password) |
|CLICK | |
|PRESS_KEYS |BACK_SPACE |
|KEY_DOWN |CONTROL,SHIFT |
|KEY_UP |CONTROL,SHIFT |
|MOVE_TO |By.id(name) |
Verify elements number
Parameters
-
$locator
- Locator -
$comparisonRule
- Comparison rule -
$quantity
- expected number of elements
Verify elements state
Info
Verifies if the number of elements located by locator matches number condition and all of them are in 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 locator’s visibility and checked state are equal (For an example :i and NOT_VISIBLE) exception will be thrown. In such cases please use step: Verify elements number |
Parameters
-
$state
- State -
$locator
- Locator -
$comparisonRule
- Comparison rule -
$quantity
- expected number of elements
Wait for element appearance
Parameters
-
$locator
- Locator
Wait for element disappearance
Parameters
-
$locator
- Locator
Save text of context element
Info
Saves text of a context element into a variable
Step will throw an error if the context element is not set |
Save attribute value of context element
Info
Saves attribute value of a context element into a variable
Step will throw an error if the context element is not set |
Wording
When I save `$attributeName` attribute value of context element to $scopes variable `$variableName`
Save attribute value of element
Wording
When I save `$attributeName` attribute value of element located `$locator` to $scopes variable `$variableName`
Parameters
-
$attributeName
- name of an element’s attribute -
$locator
- Locator -
$variableName
- name of a variable
Save number of elements
Parameters
-
$locator
- Locator -
$variableName
- name of a variable
Change context
Info
Changes the context to an element located by locator for limiting area of subsequent UI interactions
Parameters
-
$locator
- Locator
Reset context
Usage
Scenario: Reset context
Then number of elements found by `By.xpath(html)` is equal to `1`
When I change context to element located `By.xpath(//body)`
Then number of elements found by `By.xpath(html)` is equal to `0`
When I reset context
Then number of elements found by `By.xpath(html)` is equal to `1`
Verify elements order
Info
Gets a collection of elements by locator and checks that they are sorted by their text in the specified order. The collection should have more than 1 element with not empty text, otherwise the step fails.
Parameters
-
$locator
- Locator -
$sortingOrder
Plain | Readable | Description |
---|---|---|
ASCENDING |
ascending |
Verify that elements are sorted in ascending order |
DESCENDING |
descending |
Verify that elements are sorted in descending order |
CASE_INSENSITIVE_ASCENDING |
case-insensitive ascending |
Verify that elements are sorted in case-insensitive ascending order |
CASE_INSENSITIVE_DESCENDING |
case-insensitive descending |
Verify that elements are sorted in case-insensitive descending order |
Dropdown: verify available options.
Verifies if dropdown located by locator exists and has expected list of options
Then dropdown located `$locator` contains options: $option
-
$locator
- Locator -
$options
- examples table describing expected options
Then a drop down with the name 'colors' contains the items:
|state|item |
|false|Red |
|false|Green|
|true |Blue |
Item - is an option. State - true/false describes if option selected |
Dropdown: verify first selected option
Verifies if dropdown located by locator exists and first selected option.
Then dropdown located `$locator` exists and selected option is `$option`
-
$locator
- Locator -
$option
- first selected option
Then dropdown located `id(colors)` exists and selected option is `Blue`
Dropdown: add text to a mutli-select
Selects option in multi-select dropdown
Step will fail if target dropdown is not multi-select |
When I add `$option` to selection in dropdown located `$locator`
-
$option
- option to select -
$locator
- Locator
When I add `Two` to selection in dropdown located `id(numbers)`
Dropdown: select option
Selects option in dropdown
Does not support multi-selection |
When I select `$option` in dropdown located `$locator``
-
$option
- option to select -
$locator
- Locator
When I select `Red` in dropdown located `id(colors)`
Proxy - Check the number of HTTP requests
This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level.
The actions preformed by the step:
-
extract HTTP messages from the recorded proxy archive
-
filter out the HTTP messages with the response status code
302 Moved Temporarily
-
find HTTP requests matching the provided HTTP methods and the URL regular expression
-
check that the total number of the found HTTP messages satisfies the desired condition
In case of failure the full HTTP archive (HAR) is attached to the report.
Then number of HTTP $httpMethods requests with URL pattern `$urlPattern` is $comparisonRule `$number`
-
$httpMethods
- The comma-separated HTTP methods to filter by -
$urlPattern
- The regular expression to match HTTP request URL -
$comparisonRule
- Comparison Rule -
$number
- The number to compare with
Then number of HTTP GET, POST requests with URL pattern `http://httpbin\.org/get` is equal to `1`
Proxy - Save the URL
Save the URL from the request with given URL-pattern into the variable with specified name and the scopes.
This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level.
The actions preformed by the step:
-
extract HTTP messages from the recorded proxy archive
-
filter out the HTTP messages with the response status code
302 Moved Temporarily
-
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 request URL to the specified variable
In case of failure the full HTTP archive (HAR) is attached to the report.
When I capture HTTP $httpMethods request with URL pattern `$urlPattern` and save URL to $scopes variable `$variableName`
-
$httpMethods
- The "or"-separated set of HTTP methods to filter by, e.g.GET or POST or PUT
. -
$urlPattern
- The regular expression to match HTTP request URL. -
$variableName
- The variable name to save the URL.
Given I am on a page with the URL 'https://www.google.com/search?q=vividus'
When I capture HTTP GET or 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`
Proxy - Save the URL query
Save the URL query parameters from the request with given URL-pattern into the variable with specified name and the scopes.
This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level.
The actions preformed by the step:
-
extract HTTP messages from the recorded proxy archive
-
filter out the HTTP messages with the response status code
302 Moved Temporarily
-
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 URL query parameters to the specified variable
In case of failure the full HTTP archive (HAR) is attached to the report.
When I capture HTTP $httpMethods request with URL pattern `$urlPattern` and save URL query to $scopes variable `$variableName`
-
$httpMethods
- The "or"-separated set of HTTP methods to filter by, e.g.GET or POST or PUT
. -
$urlPattern
- The regular expression to match HTTP request URL. -
$variableName
- The variable name to save the URL 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.
Given I am on a page with the 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]}`
Proxy - Save the HTTP message
This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level. The actions preformed by the step:
-
extract HTTP messages from the recorded proxy archive
-
filter out the HTTP messages with response status code
302 Moved Temporarily
-
find HTTP requests matching the provided HTTP methods and URL regular expression
-
check that total number of the found HTTP messages is equal to 1
-
save the HTTP message data to the specified variable
In case of failure the full HTTP archive (HAR) is attached to the report.
When I capture HTTP $httpMethods request with URL pattern `$urlPattern` and save request data to $scopes variable `$variableName`
-
$httpMethods
- The "or"-separated set of HTTP methods to filter by, e.g.GET or POST or PUT
. -
$urlPattern
- The regular expression to match HTTP request URL. -
$variableName
- The variable name to store results. If the variable name ismy-var
, the following variables will be created:-
${my-var.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. -
${my-var.requestBody.mimeType}
- The MIME type of posted data, the variable will not be created if MIME type is not present. -
${my-var.requestBody.text}
- The posted data as plain text, the variable will not be created if the request body is not present. -
${my-var.requestBodyParameters}
- The form data parameters are stored as a collection of key and value pairs, where key is the name of the form parameter and value is the list of form parameter values. The form parameter values are accessible via zero-based index. -
${my-var.responseStatus}
- The response status, the variable will not be created if the response is not present.
-
Given I am on a page with the URL 'http://httpbin.org/forms/post'
When I click on element located `By.xpath(//button)`
When I capture GET or HTTP POST request with URL pattern `http://httpbin\.org/post` and save request data to scenario variable `data`
Then `${data.query}` is equal to `{}`
Then `${data.requestBodyParameters}` is equal to `{delivery=, custtel=, comments=, custemail=, custname=}`
Then `${data.requestBody}` is not equal to `null`
Then `${data.responseStatus}` is equal to `200`
Proxy - Wait for the HTTP request
This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level. 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.
When I wait until HTTP $httpMethods request with URL pattern `$urlPattern` exists in proxy log
-
$httpMethods
- the "or"-separated HTTP methods to filter by, e.g. 'GET or POST or PUT' -
$urlPattern
- the regular expression to match HTTP request URL
Given I am on a page with the URL 'http://httpbin.org/get'
When I wait until HTTP GET or POST request with URL pattern `http://httpbin\.org/get` exists in proxy log
Then number of HTTP GET or POST requests with URL pattern `http://httpbin\.org/get` is equal to `1`
Proxy - Add headers to the HTTP request
This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level. Add headers to the proxied HTTP request satisfying the desired condition
When I add headers to proxied requests with URL pattern which $comparisonRule `$url`:$headers
-
$comparisonRule
- String comparison rule -
$url
- The input value of URL to filter by -
$headers
- ExamplesTable representing the list of the headers with columns "name" and "value" specifying HTTP header names and values respectively
When I add headers to proxied requests with URL pattern which is equal to `http://httpbin.org/headers`:
|name |value |
|testName1|testValue1|
|testName2|testValue2|
Given I am on a page with the URL 'http://httpbin.org/headers'
When I change context to element located `xpath(//pre)`
When I set the text found in search context to the 'SCENARIO' variable 'response'
Then a JSON element from '${response}' by the JSON path '$.headers' is equal to '
{
"Testname1": "testValue1",
"Testname2": "testValue2"
}
'ignoring extra fields
Proxy - Clear Log
This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level. The step clears the HTTP requests and responses recorded by the proxy
When I clear proxy log
Given I am on a page with the URL 'http:/httpbin.org/get'
When I clear proxy log
Then number of HTTP GET requests with URL pattern `http://httpbin\.org/get` is equal to `0`
Proxy - Clear Mocks
This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level. The step clears previously created mocks
When I clear proxy mocks
When I mock HTTP responses with request URL which CONTAINS `frames.html` using response code `200`, content `#{loadResource(page.html)}` and headers:
|name |value |
|Content-Type|text/html|
When I clear proxy mocks
Given I am on a page with the URL '${vividus-test-site-url}/frames.html'
Then number of elements found by `id(sw)` is = `0`
Proxy - Mock response by methods with content
This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level. Mocks HTTP response by methods with a provided content
No actual request will be executed. Short-circuited response will be returned. |
When I mock HTTP $httpMethods responses with request URL which $comparisonRule `$url` using response code `$responseCode`, content `$payload` and headers:$headers
-
$httpMethods
- The "or"-separated set of HTTP methods to filter by, e.g.GET or POST or PUT
. -
$rule
- String comparison rule -
$url
- The input value of URL to filter by -
$code
- The response status code -
$content
- The content to send within a response -
$headers
- ExamplesTable representing the list of the headers with columns "name" and "value" specifying HTTP header names and values respectively
When I mock HTTP POST responses with request URL which CONTAINS `example` using response code `202`, content `#{loadResource(mocked-example.json)}` and headers:
|name |value |
|Content-Type|application/json|
Proxy - Mock response with content
This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level. Mocks HTTP response with a provided content
No actual request will be executed. Short-circuited response will be returned. |
When I mock HTTP responses with request URL which $comparisonRule `$url` using response code `$responseCode`, content `$payload` and headers:$headers
-
$rule
- String comparison rule -
$url
- The input value of URL to filter by -
$code
- The response status code -
$content
- The content to send within a response -
$headers
- ExamplesTable representing the list of the headers with columns "name" and "value" specifying HTTP header names and values respectively
When I mock HTTP responses with request URL which CONTAINS `example.com` using response code `200`, content `#{loadResourceAsByteArray(page.html)}` and headers:
|name |value |
|Content-Type|text/html|
Proxy - Mock response without content
This step requires proxy to be turned on. It can be done in properties or by switching on @proxy meta tag at the story level. Mocks HTTP response
No actual request will be executed. Short-circuited response will be returned. |
When I mock HTTP responses with request URL which $comparisonRule `$url` using response code `$responseCode` and headers:$headers
-
$rule
- String comparison rule -
$url
- The input value of URL to filter by -
$code
- The response status code -
$headers
- ExamplesTable representing the list of the headers with columns "name" and "value" specifying HTTP header names and values respectively
When I mock HTTP responses with request URL which CONTAINS `example.com` using response code `404` and headers:
|name |value|
|Content-Length|0 |
Dynamic variables
Dynamic variables are variables available out of the box using standard approach ${name}
. The variables support both lower camel case (e.g. ${dynamicVariableName}
) and lower hyphen case (e.g. ${dynamic-variable-name}
) name formats. Usually the data provided by the dynamic variables calculated at the runtime.
Context element rectangle
Provides possibility to access context element coordinates, width and height.
Variable uses contextual approach. So it is necessary to switch context to a target element. |