WebDriver Protocol
newSession
The New Session command creates a new WebDriver session with the endpoint node. If the creation fails, a session not created error is returned.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.newSession(capabilities)
Parameters
Name | Type | Details |
---|---|---|
capabilities | object | a JSON object, the set of capabilities that was ultimately merged and matched in the capability processing algorithm |
Returns
- <Object>
session
: Object containing sessionId and capabilities of created WebDriver session.
deleteSession
The Delete Session command closes any top-level browsing contexts associated with the current session, terminates the connection, and finally closes the current session.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.deleteSession(deleteSessionOpts)
Parameters
Name | Type | Details |
---|---|---|
deleteSessionOpts optional | object | Object containing options for the deleteSession command, e.g. { shutdownDriver: boolean } |
status
The Status command returns information about whether a remote end is in a state in which it can create new sessions and can additionally include arbitrary meta information that is specific to the implementation.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.status()
Example
loading...
Returns
- <Object>
status
: Object containing status of the driver status.
getTimeouts
The Get Timeouts command gets timeout durations associated with the current session.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.getTimeouts()
Example
loading...
Returns
- <Object>
timeouts
: Object containing timeout durations forscript
,pageLoad
andimplicit
timeouts.
setTimeouts
The Set Timeouts command sets timeout durations associated with the current session. The timeouts that can be controlled are listed in the table of session timeouts below.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.setTimeouts(implicit, pageLoad, script)
Parameters
Name | Type | Details |
---|---|---|
implicit optional | number | integer in ms for session implicit wait timeout |
pageLoad optional | number | integer in ms for session page load timeout |
script optional | number | integer in ms for session script timeout |
Example
loading...
getUrl
The Get Current URL command returns the URL of the current top-level browsing context.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.getUrl()
Example
loading...
Returns
- <string>
url
: current top-level browsing context’s active document’s document URL
navigateTo
The navigateTo (go) command is used to cause the user agent to navigate the current top-level browsing context a new location.
WebDriver Protocol command. More details can be found in the official protocol docs.
This protocol command is embedded in the following convenient method: url}. It is recommended to use this command instead.
Usage
browser.navigateTo(url)
Parameters
Name | Type | Details |
---|---|---|
url | string | string representing an absolute URL (beginning with http(s)), possibly including a fragment (#...), could also be a local scheme (about: etc) |
Example
loading...
Returns
- <string>
url
: current document URL of the top-level browsing context.
back
The Back command causes the browser to traverse one step backward in the joint session history of the current top-level browsing context. This is equivalent to pressing the back button in the browser chrome or calling window.history.back
.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.back()
Example
loading...
forward
The Forward command causes the browser to traverse one step forwards in the joint session history of the current top-level browsing context.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.forward()
Example
loading...
refresh
The Refresh command causes the browser to reload the page in current top-level browsing context.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.refresh()
Example
loading...
getTitle
The Get Title command returns the document title of the current top-level browsing context, equivalent to calling document.title
.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.getTitle()
Example
loading...
Returns
- <string>
title
: Returns a string which is the same asdocument.title
of the current top-level browsing context.
getWindowHandle
The Get Window Handle command returns the window handle for the current top-level browsing context. It can be used as an argument to Switch To Window.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.getWindowHandle()
Example
loading...
Returns
- <string>
handle
: Returns a string which is the window handle for the current top-level browsing context.
closeWindow
The Close Window command closes the current top-level browsing context. Once done, if there are no more top-level browsing contexts open, the WebDriver session itself is closed.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.closeWindow()
Example
loading...
switchToWindow
The Switch To Window command is used to select the current top-level browsing context for the current session, i.e. the one that will be used for processing commands.
WebDriver Protocol command. More details can be found in the official protocol docs.
This protocol command is embedded in the following convenient method: switchWindow}. It is recommended to use this command instead.
Usage
browser.switchToWindow(handle)
Parameters
Name | Type | Details |
---|---|---|
handle | string | a string representing a window handle, should be one of the strings that was returned in a call to getWindowHandles |
Example
loading...
createWindow
Create a new top-level browsing context.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.createWindow(type)
Parameters
Name | Type | Details |
---|---|---|
type | string | Set to 'tab' if the newly created window shares an OS-level window with the current browsing context, or 'window' otherwise. |
Example
loading...
Returns
- <Object>
window
: New window object containing 'handle' with the value of the handle and 'type' with the value of the created window type
getWindowHandles
The Get Window Handles command returns a list of window handles for every open top-level browsing context. The order in which the window handles are returned is arbitrary.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.getWindowHandles()
Example
loading...
Returns
- <String[]>
handles
: An array which is a list of window handles.
printPage
The Print Page command renders the document to a paginated PDF document. Note: Chrome currently only supports this in headless mode, see crbug753118
).
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.printPage(orientation, scale, background, width, height, top, bottom, left, right, shrinkToFit, pageRanges)
Parameters
Name | Type | Details |
---|---|---|
orientation optional | string | page orientation. Default: portrait |
scale optional | number | page scale. Default: 1 |
background optional | boolean | page background. Default: false |
width optional | number | page width in cm. Default: 21.59 from page |
height optional | number | page height in cm. Default: 27.94 from page |
top optional | number | page margin in cm from top margin. Default: 1 |
bottom optional | number | page margin in cm from bottom margin. Default: 1 |
left optional | number | page margin in cm from left margin. Default: 1 |
right optional | number | page margin in cm from right margin. Default: 1 |
shrinkToFit optional | boolean | shrink pdf to fit in page. Default: true |
pageRanges optional | object[] | page ranges. Default [] |
Example
loading...
Returns
- <string>
pdf
: The base64-encoded PDF representation of the paginated document.
switchToFrame
The Switch To Frame command is used to select the current top-level browsing context or a child browsing context of the current browsing context to use as the current browsing context for subsequent commands.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.switchToFrame(id)
Parameters
Name | Type | Details |
---|---|---|
id | number, object, null | one of three possible types: null: this represents the top-level browsing context (i.e., not an iframe), a Number, representing the index of the window object corresponding to a frame, an Element object received using findElement . |
Example
loading...
switchToParentFrame
The Switch to Parent Frame command sets the current browsing context for future commands to the parent of the current browsing context.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.switchToParentFrame()
Example
loading...
getWindowRect
The Get Window Rect command returns the size and position on the screen of the operating system window corresponding to the current top-level browsing context.
WebDriver Protocol command. More details can be found in the official protocol docs.
This protocol command is embedded in the following convenient method: getWindowSize}. It is recommended to use this command instead.
Usage
browser.getWindowRect()
Example
loading...
Returns
- <Object>
windowRect
: A JSON representation of a "window rect" object. This has 4 properties:x
,y
,width
andheight
.
setWindowRect
The Set Window Rect command alters the size and the position of the operating system window corresponding to the current top-level browsing context.
WebDriver Protocol command. More details can be found in the official protocol docs.
This protocol command is embedded in the following convenient method: setWindowSize}. It is recommended to use this command instead.
Usage
browser.setWindowRect(x, y, width, height)
Parameters
Name | Type | Details |
---|---|---|
x | number, null | the screenX attribute of the window object |
y | number, null | the screenY attribute of the window object |
width | number, null | the width of the outer dimensions of the top-level browsing context, including browser chrome etc... |
height | number, null | the height of the outer dimensions of the top-level browsing context, including browser chrome etc... |
Example
loading...
Returns
- <Object>
windowRect
: A JSON representation of a "window rect" object based on the new window state.
maximizeWindow
The Maximize Window command invokes the window manager-specific "maximize" operation, if any, on the window containing the current top-level browsing context. This typically increases the window to the maximum available size without going full-screen.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.maximizeWindow()
Example
loading...
Returns
- <Object>
windowRect
: A JSON representation of a "window rect" object based on the new window state.
minimizeWindow
The Minimize Window command invokes the window manager-specific "minimize" operation, if any, on the window containing the current top-level browsing context. This typically hides the window in the system tray.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.minimizeWindow()
Returns
- <Object>
windowRect
: A JSON representation of a "window rect" object of the (new) current top-level browsing context.
fullscreenWindow
The Fullscreen Window command invokes the window manager-specific “full screen” operation, if any, on the window containing the current top-level browsing context. This typically increases the window to the size of the physical display and can hide browser chrome elements such as toolbars.
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.fullscreenWindow()
Returns
- <Object>
windowRect
: A JSON representation of a "window rect" object of the (new) current top-level browsing context.
findElement
The Find Element command is used to find an element in the current browsing context that can be used for future commands. This command returns JSON representation of the element that can be passed to $ command to transform the reference to an extended WebdriverIO element.
WebDriver Protocol command. More details can be found in the official protocol docs.
This protocol command is embedded in the following convenient method: $}. It is recommended to use this command instead.
Usage
browser.findElement(using, value)
Parameters
Name | Type | Details |
---|---|---|
using | string | a valid element location strategy |
value | string | the actual selector that will be used to find an element |
Example
loading...
Returns
- <object>
element
: A JSON representation of an element object, e.g.{ 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }
.
findElementFromShadowRoot
The Find Element From Shadow Root command is used to find an element within the shadow root of an element that can be used for future commands. This command returns JSON representation of the element that can be passed to $ command to transform the reference to an extended WebdriverIO element.
WebDriver Protocol command. More details can be found in the official protocol docs.
This protocol command is embedded in the following convenient method: shadow$}. It is recommended to use this command instead.
Usage
browser.findElementFromShadowRoot(shadowId, using, value)
Parameters
Name | Type | Details |
---|---|---|
shadowId | String | element id of a shadow root element |
using | string | a valid element location strategy |
value | string | the actual selector that will be used to find an element |
Example
loading...
Returns
- <object>
element
: A JSON representation of an element shadow object, e.g.{ 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }
.
findElements
The Find Elements command is used to find elements in the current browsing context that can be used for future commands. This command returns array of JSON representation of the elements that can be passed to $ command to transform the reference to an extended WebdriverIO element (See findElement).
WebDriver Protocol command. More details can be found in the official protocol docs.
This protocol command is embedded in the following convenient method: $$}. It is recommended to use this command instead.
Usage
browser.findElements(using, value)
Parameters
Name | Type | Details |
---|---|---|
using | string | a valid element location strategy |
value | string | the actual selector that will be used to find an element |
Example
loading...
Returns
- <object[]>
elements
: A (possibly empty) JSON list of representations of an element object, e.g.[{ 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }]
.
findElementsFromShadowRoot
The Find Elements command is used to find elements within the shadow root of an element that can be used for future commands. This command returns array of JSON representation of the elements that can be passed to $ command to transform the reference to an extended WebdriverIO element (See findElement).
WebDriver Protocol command. More details can be found in the official protocol docs.
This protocol command is embedded in the following convenient method: shadow$$}. It is recommended to use this command instead.
Usage
browser.findElementsFromShadowRoot(shadowId, using, value)
Parameters
Name | Type | Details |
---|---|---|
shadowId | String | element id of a shadow root element |
using | string | a valid element location strategy |
value | string | the actual selector that will be used to find an element |
Example
loading...
Returns
- <object[]>
elements
: A (possibly empty) JSON list of representations of an element object, e.g.{ 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }
.
findElementFromElement
The Find Element From Element command is used to find an element from a web element in the current browsing context that can be used for future commands. This command returns JSON representation of the element that can be passed to $ command to transform the reference to an extended WebdriverIO element (See findElement).
WebDriver Protocol command. More details can be found in the official protocol docs.
This protocol command is embedded in the following convenient method: $}. It is recommended to use this command instead.
Usage
browser.findElementFromElement(elementId, using, value)
Parameters
Name | Type | Details |
---|---|---|
elementId | String | the id of an element returned in a previous call to Find Element(s) |
using | string | a valid element location strategy |
value | string | the actual selector that will be used to find an element |
Example
loading...
Returns
- <object>
element
: A JSON representation of an element object, e.g.{ 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }
.
findElementsFromElement
The Find Elements From Element command is used to find elements from a web element in the current browsing context that can be used for future commands. This command returns array of JSON representation of the elements that can be passed to $ command to transform the reference to an extended WebdriverIO element (See findElement).
WebDriver Protocol command. More details can be found in the official protocol docs.
This protocol command is embedded in the following convenient method: $$}. It is recommended to use this command instead.
Usage
browser.findElementsFromElement(elementId, using, value)
Parameters
Name | Type | Details |
---|---|---|
elementId | String | the id of an element returned in a previous call to Find Element(s) |
using | string | a valid element location strategy |
value | string | the actual selector that will be used to find an element |
Example
loading...
Returns
- <object[]>
elements
: A (possibly empty) JSON list of representations of an element object, e.g.[{ 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }]
.
getElementShadowRoot
Get the shadow root object of an element. The result object can be used to fetch elements within this shadow root using e.g. findElementFromShadowRoots or findElementsFromShadowRoots.
WebDriver Protocol command. More details can be found in the official protocol docs.
This protocol command is embedded in the following convenient method: shadow$}. It is recommended to use this command instead.
Usage
browser.getElementShadowRoot(elementId)
Parameters
Name | Type | Details |
---|---|---|
elementId | String | the id of an element returned in a previous call to Find Element(s) |
Example
loading...
Returns
- <string>
shadowRoot
: A JSON representation of an element shadow root, e.g.{ 'shadow-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }
.
getActiveElement
Get Active Element returns the active element of the current browsing context’s document element. This command returns JSON representation of the element that can be passed to $ command to transform the reference to an extended WebdriverIO element (See findElement).
WebDriver Protocol command. More details can be found in the official protocol docs.
Usage
browser.getActiveElement()
Example
loading...
Returns
- <string>
element
: A JSON representation of an element object, e.g.{ 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }
.
isElementSelected
Is Element Selected determines if the referenced element is selected or not. This operation only makes sense on input elements of the Checkbox- and Radio Button states, or option elements.
WebDriver Protocol command. More details can be found in the official protocol docs.
This protocol command is embedded in the following convenient method: isSelected}. It is recommended to use this command instead.
Usage
browser.isElementSelected(elementId)
Parameters
Name | Type | Details |
---|---|---|
elementId | String | the id of an element returned in a previous call to Find Element(s) |
Example
loading...
Returns
- <Boolean>
isSelected
:true
orfalse
based on the selected state.
isElementDisplayed
Is Element Displayed determines the visibility of an element which is guided by what is perceptually visible to the human eye. In this context, an element's displayedness does not relate to the visibility
or display
style properties.
WebDriver Protocol command. More details can be found in the official protocol docs.
This protocol command is embedded in the following convenient method: isDisplayed}. It is recommended to use this command instead.
Usage
browser.isElementDisplayed(elementId)
Parameters
Name | Type | Details |
---|---|---|
elementId | String | the id of an element returned in a previous call to Find Element(s) |
Example
loading...
Returns
- <Boolean>
isDisplayed
:true
orfalse
based on the visible state.
getElementAttribute
The Get Element Attribute command will return the attribute of a web element.
WebDriver Protocol command. More details can be found in the official protocol docs.
This protocol command is embedded in the following convenient method: getAttribute}. It is recommended to use this command instead.
Usage
browser.getElementAttribute(elementId, name)
Parameters
Name | Type | Details |
---|---|---|
elementId | String | the id of an element returned in a previous call to Find Element(s) |
name | String | name of the attribute value to retrieve |
Example
loading...
Returns
- <string>
attribute
: The named attribute of the element.
getElementProperty
The Get Element Property command will return the result of getting a property of an element.
WebDriver Protocol command. More details can be found in the official protocol docs.
This protocol command is embedded in the following convenient method: getProperty}. It is recommended to use this command instead.
Usage
browser.getElementProperty(elementId, name)
Parameters
Name | Type | Details |
---|---|---|
elementId | String | the id of an element returned in a previous call to Find Element(s) |
name | String | name of the attribute property to retrieve |
Example
loading...
Returns
- <string>
property
: The named property of the element, accessed by calling GetOwnProperty on the element object.
getElementCSSValue
The Get Element CSS Value command retrieves the computed value of the given CSS property of the given web element.
WebDriver Protocol command. More details can be found in the official protocol docs.
This protocol command is embedded in the following convenient method: getCSSProperty}. It is recommended to use this command instead.
Usage
browser.getElementCSSValue(elementId, propertyName)
Parameters
Name | Type | Details |
---|---|---|
elementId | String | the id of an element returned in a previous call to Find Element(s) |
propertyName | String | name of the CSS property to retrieve |
Example
loading...
Returns
- <string>
cssValue
: The computed value of the parameter corresponding to property name from the element's style declarations (unless the document type is xml, in which case the return value is simply the empty string).
getElementText
The Get Element Text command intends to return an element’s text "as rendered". An element's rendered text is also used for locating a elements by their link text and partial link text.
WebDriver Protocol command. More details can be found in the official protocol docs.