Links

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.

alertAccept

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.

alertDismiss

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.

assertAlert

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.

assertExist

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.

assertSelectedLabel

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.

assertSelectedValue

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.

assertText

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.

assertTextNotPresent

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.

assertTextPresent

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.

assertTitle

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.

assertValue

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.

back

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

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.

click

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.

clickHidden

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.

closeWindow

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.

debug

Stop test execution and allow interactive command execution (REPL).
** Usage example:**
web.init();
web.open("www.yourwebsite.com");
web.debug();

deleteCookies

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.

deselect

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.

dispose

Ends the current session.
Parameters:
Name
Type
Description
status
String
optional Test status, either passed or failed.

doubleClick

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.

dragAndDrop

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.

execute

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.

fileBrowse

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.

findElement

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.

findElements

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.

fullscreenWindow

Fullscreen Window.
** Usage example:**
web.init();//Opens browser session.
web.fullscreenWindow();

getAlertText

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.

getAttribute

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.

getBrowserLogs

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:

getCapabilities

Returns currently defined capabilities.
Returns:
Object - Current capabilities object.

getCookies

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.

getCssValue

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.

getDriver

Returns the underlying WDIO driver.
Returns:
Object - WDIO driver.

getElementCount

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.

getHTML

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.

getSource

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.

getText

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.
Returns:
String - The element's text.

getTitle

Returns the title of the currently active window.
Returns:
String - The page title.

getUrl

Gets the URL of the currently active window.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.getUrl();//Gets the url from the current page.
Returns:
String - The page URL.

getValue

Returns the (whitespace-trimmed) value of an input field.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.getValue("id=UserName");//Gets the value from an element.
Parameters:
Name
Type
Description
locator
String|Element
An element locator.
timeout
Number
optional Timeout in milliseconds. Default is 60 seconds.
Returns:
String - The value.

getWindowHandles

Gets handles of currently open windows.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.getWindowHandles();//Gets the window handles of currently open windows.
Returns:
Array.<String> - Array of all available window handles.

getWindowSize

Sets the size of the outer browser window.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
const sizeObject = web.getWindowSize();
Returns:
Object - Size object. Example: { height: 1056, width: 1936, x: -8, y: -8 }

getXMLPageSource

Gets the source of the currently active window which displays text/xml page.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
var src = web.getXMLPageSource();//Gets the source of currently active window which displays `text/xml` page.
Returns:
String - The XML page source.

init

Initializes new Selenium session.
Parameters:
Name
Type
Description
caps
String
optional Desired capabilities. If not specified capabilities will be taken from suite definition.
seleniumUrl
String
optional Remote server URL (default: http://localhost:4444/wd/hub).

isAlertPresent

Return true if alert dialog is currently present on the screen.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
var alertPresent = web.isAlertPresent();//Returns true if the alert dialog is displayed.
Returns:
Boolean - True if alert is present, false otherwise.

isChecked

deprecated Use isSelected instead. Determines if checkbox or radio element is checked.
** Usage example:**
web.init(caps);
var checked = web.isChecked("id=checkBox");
Parameters:
Name
Type
Description
locator
String|Element
Element locator.
timeout
Number
optional Timeout in milliseconds. Default is 60 seconds.
Returns:
Boolean - true if element is checked. false otherwise.
Supported On:

isExist

Checks if element is present in the DOM. Returns false if element was not found within the specified timeout.
** Usage example:**
web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.isExist("id=SaveButton");// Returns true if the element exists in page.
Parameters:
Name
Type
Description
locator
String|Element
An element locator.
timeout
Number
optional Timeout in milliseconds to wait for element to appear. Default is 60 seconds.
Returns:
Boolean - True if element was found. False otherwise.

isSelected