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

Name	Type	Description
`pattern`	`String`	Text pattern.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

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

Name	Type	Description
`locator`	`String`\|`Element`	An element locator.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

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

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.

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

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.

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

Name	Type	Description
`locator`	`String`\|`Element`	An element locator.
`pattern`	`String`	Text pattern.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

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

Name	Type	Description
`text`	`String`\|`Element`	Text.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

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

Name	Type	Description
`text`	`String`	Text.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

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

Name	Type	Description
`pattern`	`String`	The assertion pattern.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

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

Name	Type	Description
`locator`	`String`\|`Element`	An element locator.
`pattern`	`String`	Value pattern.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

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

Name	Type	Description
`locator`	`String`\|`Element`	An element locator.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

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

Name	Type	Description
`locator`	`String`\|`Element`	An element locator.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

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

Name	Type	Description
`locator`	`String`\|`Element`	An element locator.
`clickParent`	`Boolean`	`optional` If true, then parent of the element is clicked.

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

Name	Type	Description
`names`	`String`\|`Array.<String>`	`optional` Cookie name or a list of cookie names to delete.

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

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.

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

Name	Type	Description
`status`	`String`	`optional` Test status, either `passed` or `failed`.

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

Name	Type	Description
`locator`	`String`\|`Element`	An element locator.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

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

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.

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

Name	Type	Description
`script`	`String`\|`Function`	The JavaScript to execute.
`arg`	`...Object`	`optional` Optional arguments to be passed to the JavaScript function.

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

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.

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

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.

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

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.

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

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.

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

Name	Type	Description
`names`	`String`	Names of the cookies to retrieve.

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

Name	Type	Description
`locator`	`String`\|`Element`	An element locator.
`propertyName`	`String`	CSS property name.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

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

Name	Type	Description
`locator`	`String`\|`Element`	Element locator.

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

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.

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

Name	Type	Description
`locator`	`String`\|`Element`	An element locator.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

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

Name	Type	Description
`locator`	`String`\|`Element`	An element locator.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

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

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

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

Name	Type	Description
`locator`	`String`\|`Element`	Element locator.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

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

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.

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.

isInteractable

Returns true if the selected element is interactable.

Element is considered interactable only if it exists, is visible, is within viewport (if not try scroll to it), its center is not overlapped with another element, and is not disabled.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
if (web.isInteractable("id=SaveButton")) {
// the element is interactable
}

Parameters:

Name Type Description

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.

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 is interactable. False otherwise.

isSelected

Determines whether an option or input element of type checkbox or radio is currently selected or not.

** Usage example:**

web.init();
web.open('http://www.wikipedia.org');
var a = web.isSelected("id=Selection");
if (a) {
 ...
} else {
 ...
}

Parameters:

Name Type Description

Name	Type	Description
`locator`	`String`\|`Element`	Element locator.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

locator

String|Element

Element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

Returns:

Boolean - true if element is selected. false otherwise.

isVisible

Checks if element is present and visible. Returns false if element was not found or wasn't visible within the specified timeout.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.isVisible("id=SaveButton");// Returns true if  the element is displayed in page.

Parameters:

Name Type Description

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.

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 and it was visible. False otherwise.

makeVisible

Makes hidden element visible.

This a workaround command for situations which require manipulation of hiddenelements, such as when using web.type command for file input fields which tend to be hidden. Specifically makeVisible will apply following styles to the specified element and all theparent elements:

visibility = 'visible' if set to 'hidden'
opacity = 1 if set to 0
display = 'block' if set to 'none'
width/height = 1px if set to 0.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.makeVisible("id=SaveButton");// Makes an invisible/hidden element to become visible.

Parameters:

Name Type Description

Name	Type	Description
`locator`	`String`\|`Element`	An element locator. If multiple elements match the locator, visibility is applied to all.

locator

String|Element

An element locator. If multiple elements match the locator, visibility is applied to all.

maximizeWindow

Maximize Window.

** Usage example:**

web.init();//Opens browser session.
web.maximizeWindow();

minimizeWindow

Minimize Window.

** Usage example:**

web.init();//Opens browser session.
web.minimizeWindow();

newWindow

Opens new tab.

The newWindow command waits for the page to load before proceeding.

** Usage example:**

web.init();//Opens browser session.
web.newWindow("www.yourwebsite.com");// Opens a website on new window.

Parameters:

Name Type Description

Name	Type	Description
`url`	`String`	The URL to open; may be relative or absolute.

url

String

The URL to open; may be relative or absolute.

open

Opens an URL.

The open command waits for the page to load before proceeding.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.

Parameters:

Name Type Description

Name	Type	Description
`url`	`String`	The URL to open; may be relative or absolute.

url

String

The URL to open; may be relative or absolute.

pause

Pause test execution for the given amount of milliseconds.

** Usage example:**

web.init();//Opens browser session.
web.pause(10*1000);//Pauses the execution for 10 seconds (10000ms)

Parameters:

Name Type Description

Name	Type	Description
`ms`	`Number`	Milliseconds to pause the execution for.

ms

Number

Milliseconds to pause the execution for.

point

Points the mouse cursor over the specified element.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.point("id=Selection");//Hovers a mouse over an element.

Parameters:

Name Type Description

Name	Type	Description
`locator`	`String`\|`Element`	An element locator. If the element is not visible, it will be scrolled into view.
`xOffset`	`Number`	`optional` X offset to move to, relative to the top-left corner of the element.If not specified, the mouse will move to the middle of the element.
`yOffset`	`Number`	`optional` Y offset to move to, relative to the top-left corner of the element.If not specified, the mouse will move to the middle of the element.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

locator

String|Element

An element locator. If the element is not visible, it will be scrolled into view.

xOffset

Number

optional X offset to move to, relative to the top-left corner of the element.If not specified, the mouse will move to the middle of the element.

yOffset

Number

optional Y offset to move to, relative to the top-left corner of the element.If not specified, the mouse will move to the middle of the element.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

pointJS

Points the mouse cursor over the specified element.

This method is similar to web.point, however it simulates the action using JavaScript instead of using WebDriver's functionality which doesn't work in all cases.

Parameters:

Name Type Description

Name	Type	Description
`locator`	`String`\|`Element`	An element locator.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

locator

String|Element

An element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

refresh

Causes the browser to reload the page.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.refresh();//Reloads the page

rightClick

Perform right click on an element.

** Usage example:**

web.init();
web.open("www.yourwebsite.com");
web.rightClick("id=someElement");

Parameters:

Name Type Description

Name	Type	Description
`locator`	`String`\|`Element`	An element locator.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

locator

String|Element

An element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

rightClickActions

Perform right click on an element.

** Usage example:**

web.init();
web.open("www.yourwebsite.com");
web.rightClickActions("id=someElement", 10, -5);

Parameters:

Name Type Description

Name	Type	Description
`locator`	`String`\|`Element`	An element locator.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.
`xOffset`	`Number`	`optional` x offset in pixels. Default is 0.
`yOffset`	`Number`	`optional` y offset in pixels. Default is 0.

locator

String|Element

An element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

xOffset

Number

optional x offset in pixels. Default is 0.

yOffset

Number

optional y offset in pixels. Default is 0.

scrollToElement

Scrolls the page or a container element to the location of the specified element.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.scrollToElement("id=Button", true);// Scrolls to an element.

Parameters:

Name Type Description

Name	Type	Description
`locator`	`String`\|`Element`	An element locator.
`alignToTop`	`Boolean`	`optional` If true, the top of the element will be aligned to the top of the visible area of the scrollable ancestor. This is the default. If false, the bottom of the element will be aligned to the bottom of the visible area of the scrollable ancestor.
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

locator

String|Element

An element locator.

alignToTop

Boolean

optional If true, the top of the element will be aligned to the top of the visible area of the scrollable ancestor. This is the default. If false, the bottom of the element will be aligned to the bottom of the visible area of the scrollable ancestor.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

select

Selects an option from a drop-down list using an option locator. This command works with multiple-choice lists as well.

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.select("id=Selection","label=United States");// Selects an option from a list.

Parameters:

Name Type Description

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.

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.

selectFrame

Selects a frame or an iframe within the current window.

Available frame locators: - 'parent' - Select parent frame. - 'top' - Select top window. - NUMBER - Select frame by its 0-based index. - LOCATOR - Locator identifying the frame (relative to the top window). Multiple locators can be passed in order to switch between nested frames.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");
web.selectFrame("//iframe[@id='frame1']", "//iframe[@id='nested_frame']");
web.click("id=SaveButton");//Clicks on element that exists in the second iframe

Parameters:

Name Type Description

Name	Type	Description
`frameLocator`	`...String`\|`Number`	`optional` A locator identifying the frame or iframe. Or a series of locators.

frameLocator

...String|Number

optional A locator identifying the frame or iframe. Or a series of locators.

selectWindow

Selects window. Once window has been selected, all commands go to that window.

windowLocator can be:

title=TITLE Switch to the first window which matches the specified title. TITLE can be any ofthe supported string matching patterns (see top of the page). When using title locator, this commandwill wait for the window to appear first similarly to waitForWindow command.
url=URL Switch to the first window which matches the specified URL. URL can be any ofthe supported string matching patterns (see top of the page). When using url locator, this commandwill wait for the window to appear first similarly to waitForWindow command.
windowHandle Switch to a window using its unique handle.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.selectWindow("title=Website");// Selects and focus a window.

Parameters:

Name Type Description

Name	Type	Description
`windowLocator`	`String`	`optional` Window locator.
`timeout`	`Number`	`optional` Timeout in milliseconds when using 'title' window locating strategy. Default is 60 seconds.

windowLocator

String

optional Window locator.

timeout

Number

optional Timeout in milliseconds when using 'title' window locating strategy. Default is 60 seconds.

Returns:

String - windowHandle of the previously selected window.

sendKeys

Send a sequence of keyboard strokes to the active window or element.

Refer to Key Codes for the list of supported raw keyboard key codes.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.sendKeys("Hello World");
web.sendKeys(["Backspace", "Backspace", "Enter"]); // send two Backspace key codes and Enter.
// Unicode representation can be used directly as well:
web.sendKeys("Hello World\uE003\uE003\uE007");

Parameters:

Name Type Description

Name	Type	Description
`value`	`String`\|`Array.<String>`	Sequence of key strokes to send. Can be either a string or an array of strings for sending raw key codes.

value

String|Array.<String>

Sequence of key strokes to send. Can be either a string or an array of strings for sending raw key codes.

setAutoWaitForAngular

Wait for Angular based app will be loaded

** Usage example:**

web.init();
web.open("www.yourwebsite.com");
web.setAutoWaitForAngular(true);

Parameters:

Name Type Description

Name	Type	Description
`autoWaitForAngular`	`Boolean`	new autoWait value. Dafault is false;
`rootSelector`	`String`	`optional` Selector for root element, need only for Angular 1
`timeout`	`Number`	`optional` Timeout in milliseconds. Default is 60 seconds.

autoWaitForAngular

Boolean

new autoWait value. Dafault is false;

rootSelector

String

optional Selector for root element, need only for Angular 1

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

setTimeout

Specifies the amount of time that Oxygen will wait for actions to complete.

This includes the open command, waitFor* commands, and commands which wait for elements to appear in DOM or become visible before operating on them. If command wasn't able to complete within the specified period it will fail the test. The default time-out is 60 seconds.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.setTimeout(60000);//Sets the time out to amount of milliseconds .

Parameters:

Name Type Description

Name	Type	Description
`timeout`	`Number`	A time-out in milliseconds.

timeout

Number

A time-out in milliseconds.

setWindowSize

Sets the size of the outer browser window.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.setWindowSize(100,40);//Sets the window size (width and height) in pixels.

Parameters:

Name Type Description

Name	Type	Description
`width`	`Number`	Width in pixels.
`height`	`Number`	Height in pixels.

width

Number

Width in pixels.

height

Number

Height in pixels.

takeScreenshot

Take a screenshot of the current page or screen and return it as base64 encoded string.

** Usage example:**

web.init();
web.open("www.yourwebsite.com");
var ss = web.takeScreenshot();
require("fs").writeFileSync("c:\\screenshot.png", ss, 'base64');

Returns:

String - Screenshot image encoded as a base64 string.

transaction

Opens new transaction.

The transaction will persist till a new one is opened. Transaction names must be unique.

Parameters:

Name Type Description

name

String

The transaction name.

type

Send a sequence of key strokes to an element (clears value before).

Refer to Key Codes for the list of supported raw keyboard key codes.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.type("id=UserName","User1");//Types a string to field.

Parameters:

Name Type Description

locator

String|Element

An element locator.

value

String

The value to type.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

verifyAlert

Verifies 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). If alert is not present then NO_ALERT_OPEN_ERROR error will be thrown and the test terminated.

** 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.verifyAlert("Your Alert's text");//Verifies the alert's text.

Parameters:

Name Type Description

pattern

String

Text pattern.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

verifyExist

Verifies whether element exists in the DOM.

** Usage example:**

web.init();//Opens browser session
web.open("www.yourwebsite.com");// Opens a website.
web.verifyExist ("id=Username");// Verifies 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.

verifySelectedLabel

Verifies 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).If element is not present then ELEMENT_NOT_FOUND error will be thrown and the test terminated.

** Usage example:**

web.init();//Opens browser session
web.open("www.yourwebsite.com");// Opens a website.
web.verifySelectedLabel("id=Selection", "United States");// Verifies 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.

verifySelectedValue

Verifies 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).If element is not present then ELEMENT_NOT_FOUND error will be thrown and the test terminated.

** Usage example:**

web.init();//Opens browser session
web.open("www.yourwebsite.com");// Opens a website.
web.verifySelectedValue("id=Selection", "3");// Verifies 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.

verifyText

Verifies 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. If element is not present then ELEMENT_NOT_FOUND error will be thrown and the test terminated.

** Usage example:**

web.init();//Opens browser session
web.open("www.yourwebsite.com");// Opens a website.
web.verifyText ("id=UserName","John Doe");// Verifies 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.

verifyTextNotPresent

Verifies 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.verifyTextNotPresent("John Doe");// Verifies 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.

verifyTextPresent

Verifies 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.verifyTextPresent("John Doe");// Verifies 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.

verifyTitle

Verifies 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.verifyTitle("Your websites title!");// Verifies the title of the page.

Parameters:

Name Type Description

pattern

String

The assertion pattern.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

verifyValue

Verifies element's value.

Value pattern can be any of the supported string matching patterns (on the top of page).If element is not present then ELEMENT_NOT_FOUND error will be thrown and the test terminated.

** Usage example:**

web.init();//Opens browser session
web.open("www.yourwebsite.com");// Opens a website.
web.verifyValue("id=UserName", "John Doe");// Verifies 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.

waitForAngular

Wait for Angular based app will be loaded

** Usage example:**

web.init();
web.open("www.yourwebsite.com");
web.waitForAngular();

Parameters:

Name Type Description

rootSelector

String

optional Selector for root element, need only for Angular 1

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

waitForExist

Waits for element to become available in the DOM.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.waitForExist("id=UserName");//Waits for an element to exist in DOM.

Parameters:

Name Type Description

locator

String|Element

An element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

waitForInteractable

Waits for element to become interactable.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.waitForInteractable("id=UserName");//Waits for an element is clickable in DOM.

Parameters:

Name Type Description

locator

String|Element

An element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

waitForNotExist

Waits for element to become unavailable in the DOM.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.waitForNotExist("id=UserName");//Waits for an element to not exist in DOM.

Parameters:

Name Type Description

locator

String|Element

An element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

waitForNotText

Waits for inner text of the given element to stop matching the specified pattern.

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.waitForNotText("id=Title","Website");//Waits for an element’s text to not match to expected string.

Parameters:

Name Type Description

locator

String|Element

An element locator.

pattern

String

Text pattern.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

waitForNotValue

Waits for input element's value to stop matching the specified pattern.

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.waitForNotValue("id=UserName","User");//Waits for an element’s value to not match to expected string.

Parameters:

Name Type Description

locator

String|Element

An element locator.

pattern

String

Value pattern.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

waitForText

Waits for inner text of the given element to match the specified pattern.

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.waitForText("id=Title","Website");//Waits for an element’s text to  match to expected string.

Parameters:

Name Type Description

locator

String|Element

An element locator.

pattern

String

Text pattern.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

waitForValue

Waits for input element's value to match the specified pattern.

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.waitForValue("id=Title","Website");//Waits for an element’s value to  match to expected string.

Parameters:

Name Type Description

locator

String|Element

An element locator.

pattern

String

Value pattern.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

waitForVisible

Waits for element to become visible.

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.waitForVisible("id=Title", 45*1000);//Waits for an element to  be visible.

Parameters:

Name Type Description

locator

String|Element

An element locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

waitForWindow

Waits for a window to appear, but doesn't actually switches to it.

windowLocator can be:

title=TITLE Wait for the first window which matches the specified title. TITLE can be any of the supported string matching patterns(see top of the page).
url=URL Wait for the first window which matches the specified URL. URL can be any of the supported string matching patterns(see top of the page).

** Usage example:**

web.init();//Opens browser session.
web.open("www.yourwebsite.com");// Opens a website.
web.waitForWindow("title=Website");//Waits for a window to appear.

Parameters:

Name Type Description

windowLocator

String

A window locator.

timeout

Number

optional Timeout in milliseconds. Default is 60 seconds.

Previousutils Nextwin

Last updated 7 months ago