web
Provides methods for browser automation.
Notes:
Commands which operate on elements such as click, assert, waitFor, type, select, and others will automatically wait for a period of time for the element to appear in DOM and become visible. By default this period equals to 60 seconds, but can be changed using the
setTimeoutcommand.String matching patterns:
Commands which expect a string matching pattern in their arguments, support following patterns unless specified otherwise:
regex:PATTERN- Match using regular expression.regexi:PATTERN- Match using case-insensitive regular expression.exact:STRING- Match the string verbatim.glob:PATTERN- Match using case-insensitive glob pattern.?will match any single character except new line (\n).*will match any sequence (0 or more) of characters except new line. Empty PATTERN will match only other empty strings.PATTERN- Same as glob matching.
Locators:
Commands which expect an element locator in their arguments, support following locator types unless specified otherwise:
id=ID- Locates element by its ID attribute.css=CSS_SELECTOR- Locates element using a CSS selector.link=TEXT- Locates link element whose visible text matches the given string.link-contains=TEXT- Locates link element whose visible text contains the given string.name=NAME- Locates element by its NAME attribute.tag=NAME- Locates element by its tag name./XPATH- Locates element using an XPath 1.0 expression.(XPATH)[]- Locates element using an XPath 1.0 expression.
Accepts an alert or a confirmation dialog.
In case of an alert box this command is identical to
alertDismiss.** Usage example:**
web.init();//Opens browser session
web.open("www.yourwebsite.com");// Opens a website.
web.click("id=SaveButton");//Clicks on save – an alert would pop up
web.alertAccept();//Clicks on "OK" in the alert dialog.
Dismisses an alert or a confirmation dialog.
In case of an alert box this command is identical to
alertAccept.** Usage example:**
web.init();//Opens browser session
web.open("www.yourwebsite.com");// Opens a website.
web.click("id=SaveButton");//Clicks on save – an alert would pop up
web.alertDismiss();//Clicks on Cancel in the alert dialog.
Asserts whether alert matches the specified pattern and dismisses it.
Text pattern can be any of the supported string matching patterns(on the top of page).
** Usage example:**
web.init();//Opens browser session
web.open("www.yourwebsite.com");// Opens a website.
web.click("id=SaveButton");//Clicks on save – an alert would pop up
web.assertAlert("Your Alert's text");//Asserts the alert's text.
Parameters:
Name | Type | Description |
|---|---|---|
pattern | String | Text pattern. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Asserts whether element exists in the DOM.
** Usage example:**
web.init();//Opens browser session
web.open("www.yourwebsite.com");// Opens a website.
web.assertExist ("id=Username");// Asserts if an element exists in the DOM.
Parameters:
Name | Type | Description |
|---|---|---|
locator | String|Element | An element locator. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Asserts text of the currently selected option in a drop-down list.
Assertion pattern can be any of the supported string matching patterns(on the top of page).
** Usage example:**
web.init();//Opens browser session
web.open("www.yourwebsite.com");// Opens a website.
web.assertSelectedLabel("id=Selection", "United States");// Asserts if an element's label is selected in the drop down list.
Parameters:
Name | Type | Description |
|---|---|---|
locator | String|Element | An element locator. |
pattern | String | The assertion pattern. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
waitForVisible | Boolean | optional Wait for visible. |
Asserts value of the currently selected option in a drop-down list.
Assertion pattern can be any of the supported string matching patterns(on the top of page).
** Usage example:**
web.init();//Opens browser session
web.open("www.yourwebsite.com");// Opens a website.
web.assertSelectedValue("id=Selection", "3");// Asserts if an element's value is selected in the drop down list.
Parameters:
Name | Type | Description |
|---|---|---|
locator | String|Element | An element locator. |
pattern | String | The assertion pattern. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
waitForVisible | Boolean | optional Wait for visible. |
Asserts element's inner text.
Text pattern can be any of the supported string matching patterns(on the top of page). If the element is not interactable, then it will allways return empty string as its text.
** Usage example:**
web.init();//Opens browser session
web.open("www.yourwebsite.com");// Opens a website.
web.assertText ("id=UserName","John Doe");// Asserts if an element's text is as expected.
Parameters:
Name | Type | Description |
|---|---|---|
locator | String|Element | An element locator. |
pattern | String | Text pattern. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Asserts whether the given text is not present on the page. That is, whether there are no elements containing this text on the page.
** Usage example:**
web.init();//Opens browser session
web.open("www.yourwebsite.com");// Opens a website.
web.assertTextNotPresent("John Doe");// Asserts if a text is not presented somewhere on the page.
Parameters:
Name | Type | Description |
|---|---|---|
text | String|Element | Text. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Asserts whether the given text is present somewhere on the page. That is whether an element containing this text exists on the page.
** Usage example:**
web.init();//Opens browser session
web.open("www.yourwebsite.com");// Opens a website.
web.assertTextPresent("John Doe");// Asserts if a text is presented somewhere on the page.
Parameters:
Name | Type | Description |
|---|---|---|
text | String | Text. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Asserts the page title.
Assertion pattern can be any of the supported string matching patterns(on the top of page).
** Usage example:**
web.init();//Opens browser session
web.open("www.yourwebsite.com");// Opens a website.
web.assertTitle("Your websites title!");// Asserts the title of the page.
Parameters:
Name | Type | Description |
|---|---|---|
pattern | String | The assertion pattern. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Asserts element's value.
Value pattern can be any of the supported string matching patterns(on the top of page).
** Usage example:**
web.init();//Opens browser session
web.open("www.yourwebsite.com");// Opens a website.
web.assertValue("id=UserName", "John Doe");// Asserts the value of an element.
Parameters:
Name | Type | Description |
|---|---|---|
locator | String|Element | An element locator. |
pattern | String | Value pattern. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Navigate backwards in the browser history.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.click("id=NextPage");//Clicks on next page link.
web.back();//Navigate back to previous page.
Clear the value of an input field.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.type("id=Password", "Password");//Types a password to a field.
web.clear("id=Password");//Clears the characters from the field of an element.
Parameters:
Name | Type | Description |
|---|---|---|
locator | String|Element | An element locator. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Clicks on an element.
If the click causes new page to load, the command waits for page to load before proceeding.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.click("id=NextPage");//Clicks on next page link.
Parameters:
Name | Type | Description |
|---|---|---|
locator | String|Element | An element locator. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Clicks on a non-visible element.
If the click causes new page to load, the command waits for page to load before proceeding.
** Usage example:**
web.clickHidden("id=HiddenLink");
Parameters:
Name | Type | Description |
|---|---|---|
locator | String|Element | An element locator. |
clickParent | Boolean | optional If true, then parent of the element is clicked. |
Closes the currently active window.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.closeWindow();//Closes the current window.
Stop test execution and allow interactive command execution (REPL).
** Usage example:**
web.init();
web.open("www.yourwebsite.com");
web.debug();
Delete cookies visible to the current page.
Parameters:
Name | Type | Description |
|---|---|---|
names | String|Array.<String> | optional Cookie name or a list of cookie names to delete. |
Deselects an option from multiple-choice drop-down list.
Option locator can be one of the following (No prefix is same as label matching):
-
label=STRING Matches option based on the visible text.
- value=STRING Matches option based on its value.
- index=STRING Matches option based on its index. The index is 0-based.** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.deselect("id=Selection","label=United States");//Deselect option from multiple choice drop down list.
Parameters:
Name | Type | Description |
|---|---|---|
selectLocator | String | An element locator identifying a drop-down menu. |
optionLocator | String | An option locator. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Ends the current session.
Parameters:
Name | Type | Description |
|---|---|---|
status | String | optional Test status, either passed or failed. |
Double clicks on an element.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.doubleClick("id=Mark");//Double clicks on a element.
Parameters:
Name | Type | Description |
|---|---|---|
locator | String|Element | An element locator. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Drag and Drop element into another element
** Usage example. Drops grey rectangle into red square.:**
web.init();
web.open('http://webdriverjs.christian-bromann.com/');
web.dragAndDrop('id=overlay', '/html/body/section/div[1]');
web.pause(10*1000);
Parameters:
Name | Type | Description |
|---|---|---|
srcElement | String | Element to drag and drop. |
dstElement | String | Destination element to drop into. |
duration | Number | optional How long the drag should take place. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Executes JavaScript in the context of the currently selected frame or window.
If return value is null or there is no return value,
null is returned.** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.execute(function()
{
angular.element(".password").trigger("ng-click").click()
}
);//Executes/injects JavaScript code.
Parameters:
Name | Type | Description |
|---|---|---|
script | String|Function | The JavaScript to execute. |
arg | ...Object | optional Optional arguments to be passed to the JavaScript function. |
Returns:
Object - The return value.Uploads a local file
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.fileBrowse("id=ProfilePicture","C:\\picture.jpg");//Uploads a file to an element.
Parameters:
Name | Type | Description |
|---|---|---|
locator | String|Element | Locator for a input type=file element. |
filepath | String | Path to a local file. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Finds an element.
** Usage example:**
web.open('https://www.wikipedia.org');
var el = web.findElement("id=js-link-box-en");
web.click(el);
Parameters:
Name | Type | Description |
|---|---|---|
locator | String | Element locator. |
parent | Element | optional Optional parent element for relative search. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Returns:
Element - A Element object.Finds elements.
** Usage example:**
web.open('https://www.wikipedia.org');
var els = web.findElements("//div");
for (let el of els) {
var text = web.getText(el);
log.info(text);
}
Parameters:
Name | Type | Description |
|---|---|---|
locator | String | Element locator. |
parent | Element | optional Optional parent element for relative search. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Returns:
Array.<Element> - Collection of Element objects.Fullscreen Window.
** Usage example:**
web.init();//Opens browser session.
web.fullscreenWindow();
Gets the text displayed by an alert or confirm dialog.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
var text = web.getAlertText();//Gets the text in the alert dialog.
Returns:
String - The alert's text.Returns the element's attribute.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.getAttribute("id=UserName","value");//Gets an attribute from an element.
Parameters:
Name | Type | Description |
|---|---|---|
locator | String|Element | An element locator. |
attribute | String | The name of the attribute to retrieve. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Returns:
String - The attribute's value or null if no such attribute.Collects logs from the browser console. Works only in Chrome.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
var logs = web.getBrowserLogs(); //Collects logs from the browser console
Returns:
Array.<Object> - An array of browser console logs.Supported On:
Returns currently defined capabilities.
Returns:
Object - Current capabilities object.Returns a specific cookie or a list of cookies visible to the current page.
Parameters:
Name | Type | Description |
|---|---|---|
names | String | Names of the cookies to retrieve. |
Returns:
String - The attribute's value.Returns the value of a CSS property of an element.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.getCssValue("id=UserName","color");//Gets a CSS value from an element.
Parameters:
Name | Type | Description |
|---|---|---|
locator | String|Element | An element locator. |
propertyName | String | CSS property name. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Returns:
String - CSS property value or null if no such property.Returns the underlying WDIO driver.
Returns:
Object - WDIO driver.Retrieves the count of elements matching the given locator.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
var count = web.getElementCount("//*[@class=Title]");//Gets the element count.
Parameters:
Name | Type | Description |
|---|---|---|
locator | String|Element | Element locator. |
Returns:
Number - Element count or 0 if no elements were found.Gets source code of specified DOM element.
** Usage example:**
web.getHTML("id=Username", false);
Parameters:
Name | Type | Description |
|---|---|---|
locator | String|Element | An element locator. |
includeElementTag | Boolean | If true, it includes the element tag. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |
Returns:
String - Source code of the element.Gets the source of the currently active window.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.getSource();//Gets the source of the page.
Returns:
String - The page source.Returns the text (rendered text shown to the user; whitespace-trimmed) of an element.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
var text = web.getText("id=Title");//Gets the text from an element.
Parameters:
Name | Type | Description |
|---|---|---|
locator | String|Element | An element locator. |
timeout | Number | optional Timeout in milliseconds. Default is 60 seconds. |