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

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

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

Returns

<Object> timeouts: Object containing timeout durations for script, pageLoad and implicit 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

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

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.

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)

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

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

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

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

Returns

<string> title: Returns a string which is the same as document.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()

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

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.

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

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.

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

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.

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 `[]`

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

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

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.

Usage

browser.getWindowRect()

Returns

<Object> windowRect: A JSON representation of a "window rect" object. This has 4 properties: x, y, width and height.

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.

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

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

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.

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

Asynchronous Mode
Synchronous Mode

// get element
const elementRef = await browser.findElement('xpath', '//div')
const element = await $(elementRef)
await element.click()

// get element
const elementRef = browser.findElement('xpath', '//div')
const element = $(elementRef)
element.click()

caution

Synchronous Mode will depcrecated with Node.js v16. With an update to the
underlying Chromium version it became technically impossible to provide the
same synchronous behavior. We recommend to start transition to asynchronous
command execution. For more information, see our <a href="https://github.com/webdriverio/webdriverio/discussions/6702">RFC</a>.

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.

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

Asynchronous Mode
Synchronous Mode

// get shadow root
const element = await browser.findElement('xpath', '//div')
const shadowRoot = await browser.getElementShadowRoot(
    element['element-6066-11e4-a52e-4f735466cecf']
)
// fetch element within that shadow root
const elementRef = await browser.findElementFromShadowRoot(
    shadowRoot['shadow-6066-11e4-a52e-4f735466cecf'],
    'xpath',
    '//div'
)

// get shadow root
const element = browser.findElement('xpath', '//div')
const shadowRoot = browser.getElementShadowRoot(
    element['element-6066-11e4-a52e-4f735466cecf']
)
// fetch element within that shadow root
const elementRef = browser.findElementFromShadowRoot(
    shadowRoot['shadow-6066-11e4-a52e-4f735466cecf'],
    'xpath',
    '//div'
)

caution

Synchronous Mode will depcrecated with Node.js v16. With an update to the
underlying Chromium version it became technically impossible to provide the
same synchronous behavior. We recommend to start transition to asynchronous
command execution. For more information, see our <a href="https://github.com/webdriverio/webdriverio/discussions/6702">RFC</a>.

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.

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

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.

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

Asynchronous Mode
Synchronous Mode

// get shadow root
const element = await browser.findElement('xpath', '//div')
const shadowRoot = await browser.getElementShadowRoot(
    element['element-6066-11e4-a52e-4f735466cecf']
)
// fetch elements within that shadow root
const elementRef = await browser.findElementsFromShadowRoot(
    shadowRoot['shadow-6066-11e4-a52e-4f735466cecf'],
    'xpath',
    '//div'
)

// get shadow root
const element = browser.findElement('xpath', '//div')
const shadowRoot = browser.getElementShadowRoot(
    element['element-6066-11e4-a52e-4f735466cecf']
)
// fetch elements within that shadow root
const elementRef = browser.findElementsFromShadowRoot(
    shadowRoot['shadow-6066-11e4-a52e-4f735466cecf'],
    'xpath',
    '//div'
)

caution

Synchronous Mode will depcrecated with Node.js v16. With an update to the
underlying Chromium version it became technically impossible to provide the
same synchronous behavior. We recommend to start transition to asynchronous
command execution. For more information, see our <a href="https://github.com/webdriverio/webdriverio/discussions/6702">RFC</a>.

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.

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

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.

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

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.

Usage

browser.getElementShadowRoot(elementId)

Parameters

Name	Type	Details
`elementId`	String	the id of an element returned in a previous call to Find Element(s)

Returns

<string> element: 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()

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.

Usage

browser.isElementSelected(elementId)

Parameters

Name	Type	Details
`elementId`	String	the id of an element returned in a previous call to Find Element(s)

Returns

<Boolean> isSelected: true or false 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.

Usage

browser.isElementDisplayed(elementId)

Parameters

Name	Type	Details
`elementId`	String	the id of an element returned in a previous call to Find Element(s)

Returns

<Boolean> isDisplayed: true or false 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.

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

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.

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

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.

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

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.

Usage

browser.getElementText(elementId)

Parameters

Name	Type	Details
`elementId`	String	the id of an element returned in a previous call to Find Element(s)

Returns

<string> text: The visible text of the element (including child elements), following the algorithm defined in the Selenium Atoms for bot.dom.getVisibleText.

getElementTagName

The Get Element Tag Name command returns the qualified element name of the given web element.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.getElementTagName(elementId)

Parameters

Name	Type	Details
`elementId`	String	the id of an element returned in a previous call to Find Element(s)

Returns

<string> text: The tagName attribute of the element.

getElementRect

The Get Element Rect command returns the dimensions and coordinates of the given web element.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.getElementRect(elementId)

Parameters

Name	Type	Details
`elementId`	String	the id of an element returned in a previous call to Find Element(s)

Returns

<Object> elementRect: A JSON object representing the position and bounding rect of the element.

isElementEnabled

Is Element Enabled determines if the referenced element is enabled or not. This operation only makes sense on form controls.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.isElementEnabled(elementId)

Parameters

Name	Type	Details
`elementId`	String	the id of an element returned in a previous call to Find Element(s)

Returns

<Boolean> isEnabled: If the element is in an xml document, or is a disabled form control: false, otherwise, true.

elementClick

The Element Click command scrolls into view the element if it is not already pointer-interactable, and clicks its in-view center point. If the element's center point is obscured by another element, an element click intercepted error is returned. If the element is outside the viewport, an element not interactable error is returned.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.elementClick(elementId)

Parameters

Name	Type	Details
`elementId`	String	the id of an element returned in a previous call to Find Element(s)

elementClear

The Element Clear command scrolls into view an editable or resettable element and then attempts to clear its selected files or text content.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.elementClear(elementId)

Parameters

Name	Type	Details
`elementId`	String	the id of an element returned in a previous call to Find Element(s)

elementSendKeys

The Element Send Keys command scrolls into view the form control element and then sends the provided keys to the element. In case the element is not keyboard-interactable, an element not interactable error is returned.

The key input state used for input may be cleared mid-way through "typing" by sending the null key, which is U+E000 (NULL).

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.elementSendKeys(elementId, text)

Parameters

Name	Type	Details
`elementId`	String	the id of an element returned in a previous call to Find Element(s)
`text`	string	string to send as keystrokes to the element

getPageSource

The Get Page Source command returns a string serialization of the DOM of the current browsing context active document.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.getPageSource()

Returns

<string> pageSource: the DOM of the current browsing context active document

executeScript

The Execute Script command executes a JavaScript function in the context of the current browsing context and returns the return value of the function.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.executeScript(script, args)

Parameters

Name	Type	Details
`script`	string	a string, the Javascript function body you want executed
`args`	string, object, number, boolean, undefined[]	an array of JSON values which will be deserialized and passed as arguments to your function

Returns

<*> result: Either the return value of your script, the fulfillment of the Promise returned by your script, or the error which was the reason for your script's returned Promise's rejection.

executeAsyncScript

The Execute Async Script command causes JavaScript to execute as an anonymous function. Unlike the Execute Script command, the result of the function is ignored. Instead an additional argument is provided as the final argument to the function. This is a function that, when called, returns its first argument as the response.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.executeAsyncScript(script, args)

Parameters

Name	Type	Details
`script`	string	a string, the Javascript function body you want executed
`args`	string, object, number, boolean, undefined[]	an array of JSON values which will be deserialized and passed as arguments to your function

Returns

<*> result: Either the return value of your script, the fulfillment of the Promise returned by your script, or the error which was the reason for your script's returned Promise's rejection.

getAllCookies

The Get All Cookies command returns all cookies associated with the address of the current browsing context’s active document.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.getAllCookies()

Returns

<Object[]> cookies: A list of serialized cookies. Each serialized cookie has a number of optional fields which may or may not be returned in addition to name and value.

addCookie

The Add Cookie command adds a single cookie to the cookie store associated with the active document's address.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.addCookie(cookie)

Parameters

Name	Type	Details
`cookie`	object	A JSON object representing a cookie. It must have at least the name and value fields and could have more, including expiry-time and so on

deleteAllCookies

The Delete All Cookies command allows deletion of all cookies associated with the active document's address.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.deleteAllCookies()

getNamedCookie

The Get Named Cookie command returns the cookie with the requested name from the associated cookies in the cookie store of the current browsing context's active document. If no cookie is found, a no such cookie error is returned.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.getNamedCookie(name)

Parameters

Name	Type	Details
`name`	String	name of the cookie to retrieve

Returns

<Object> cookie: A serialized cookie, with name and value fields. There are a number of optional fields like path, domain, and expiry-time which may also be present.

deleteCookie

The Delete Cookie command allows you to delete either a single cookie by parameter name, or all the cookies associated with the active document's address if name is undefined.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.deleteCookie(name)

Parameters

Name	Type	Details
`name`	String	name of the cookie to delete

performActions

The Perform Actions command is used to execute complex user actions. See spec for more details.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.performActions(actions)

Parameters

Name	Type	Details
`actions`	object[]	a list of objects, each of which represents an input source and its associated actions

releaseActions

The Release Actions command is used to release all the keys and pointer buttons that are currently depressed. This causes events to be fired as if the state was released by an explicit series of actions. It also clears all the internal state of the virtual devices.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.releaseActions()

dismissAlert

The Dismiss Alert command dismisses a simple dialog if present, otherwise error. A request to dismiss an alert user prompt, which may not necessarily have a dismiss button, has the same effect as accepting it.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.dismissAlert()

acceptAlert

The Accept Alert command accepts a simple dialog if present, otherwise error.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.acceptAlert()

getAlertText

The Get Alert Text command returns the message of the current user prompt. If there is no current user prompt, it returns an error.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.getAlertText()

Returns

<string> alertText: The message of the user prompt.

sendAlertText

The Send Alert Text command sets the text field of a window.prompt user prompt to the given value.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.sendAlertText(text)

Parameters

Name	Type	Details
`text`	string	string to set the prompt to

takeScreenshot

The Take Screenshot command takes a screenshot of the top-level browsing context's viewport.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.takeScreenshot()

Returns

<string> screenshot: The base64-encoded PNG image data comprising the screenshot of the initial viewport.

takeElementScreenshot

The Take Element Screenshot command takes a screenshot of the visible region encompassed by the bounding rectangle of an element.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.takeElementScreenshot(elementId, scroll)

Parameters

Name	Type	Details
`elementId`	String	the id of an element returned in a previous call to Find Element(s)
`scroll` optional	boolean	scroll into view the element. Default: true

Returns

<string> screenshot: The base64-encoded PNG image data comprising the screenshot of the visible region of an element’s bounding rectangle after it has been scrolled into view.

getElementComputedRole

Get the computed WAI-ARIA role of an element.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.getElementComputedRole(elementId)

Parameters

Name	Type	Details
`elementId`	String	the id of an element returned in a previous call to Find Element(s)

Returns

<string> role: The result of computing the WAI-ARIA role of element.

getElementComputedLabel

Get the accessible name of the element.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.getElementComputedLabel(elementId)

Parameters

Name	Type	Details
`elementId`	String	the id of an element returned in a previous call to Find Element(s)

Returns

<string> label: The result of a Accessible Name and Description Computation for the Accessible Name of the element.

setPermissions

Simulates user modification of a PermissionDescriptor's permission state. Note: this feature has not landed in all browsers yet.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.setPermissions(descriptor, state, oneRealm)

Parameters

Name	Type	Details
`descriptor`	object	Each powerful feature has one or more aspects that websites can request permission to access. To describe these aspects, each feature defines a subtype of PermissionDescriptor to be its permission descriptor type. Note: this feature has not landed in all browsers yet.
`state`	string	Determines whether permission is granted, denied or prompted.
`oneRealm` optional	boolean	Whether or not to apply permissions to all execution contexts.

Example

Asynchronous Mode
Synchronous Mode

// set midi permissions
browser.setPermissions({
  name: 'midi',
  sysex; true
, 'granted'); // can be also 'denied' or 'prompt'

// set midi permissions
browser.setPermissions({
  name: 'midi',
  sysex; true
, 'granted'); // can be also 'denied' or 'prompt'

caution

Synchronous Mode will depcrecated with Node.js v16. With an update to the
underlying Chromium version it became technically impossible to provide the
same synchronous behavior. We recommend to start transition to asynchronous
command execution. For more information, see our <a href="https://github.com/webdriverio/webdriverio/discussions/6702">RFC</a>.

generateTestReport

Generates a report for testing. Extension for Reporting API. Note: this feature has not landed in all browsers yet.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.generateTestReport(message, group)

Parameters

Name	Type	Details
`message`	string	Message to be displayed in the report.
`group` optional	string	Specifies the endpoint group to deliver the report to.

createMockSensor

Creates a mock sensor to emulate sensors like Ambient Light Sensor. Note: this feature has not landed in all browsers yet.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.createMockSensor(mockSensorType, maxSamplingFrequency, minSamplingFrequency)

Parameters

Name	Type	Details
`mockSensorType`	string	Type of sensor API to mock, e.g. 'ambient-light'
`maxSamplingFrequency` optional	number	A double representing frequency in Hz that is used to set maximum supported sampling frequency for the associated mock sensor.
`minSamplingFrequency` optional	number	A double representing frequency in Hz that is used to set minimum supported sampling frequency for the associated mock sensor.

getMockSensor

Retrieves information about a given type of mock sensor. Note: this feature has not landed in all browsers yet.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.getMockSensor(type)

Parameters

Name	Type	Details
`type`	String	Mock sensor type to retrieve information from.

Returns

<object> sensorReading: Values of the mock sensor reading.

updateMockSensor

Updates the mock sensor type. Note: this feature has not landed in all browsers yet.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.updateMockSensor(type, mockSensorType, maxSamplingFrequency, minSamplingFrequency)

Parameters

Name	Type	Details
`type`	String	Mock sensor type to update information for.
`mockSensorType`	string	Type of sensor API to mock, e.g. 'ambient-light'
`maxSamplingFrequency` optional	number	A double representing frequency in Hz that is used to set maximum supported sampling frequency for the associated mock sensor.
`minSamplingFrequency` optional	number	A double representing frequency in Hz that is used to set minimum supported sampling frequency for the associated mock sensor.

deleteMockSensor

The Delete Session command closes any top-level browsing contexts associated with the current session, terminates the connection, and finally closes the current session. Note: this feature has not landed in all browsers yet.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.deleteMockSensor(type)

Parameters

Name	Type	Details
`type`	String	Mock sensor type to delete.

setTimeZone

Simulates the changing of a time zone for the purposes of testing. Note: this feature has not landed in all browsers yet.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.setTimeZone(time_zone)

Parameters

Name	Type	Details
`time_zone`	string	Name of the timezone, e.g. Asia/Tokyo

addVirtualAuthenticator

Creates a software Virtual Authenticator.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.addVirtualAuthenticator(protocol, transport, hasResidentKey, hasUserVerification, isUserConsenting, isUserVerified, extensions, uvm)

Parameters

Name	Type	Details
`protocol` optional	string	Valid values: 'ctap1/u2f', 'ctap2', 'ctap2_1'
`transport` optional	string	Valid values: 'usb', 'nfc', 'ble' or 'internal'
`hasResidentKey` optional	boolean
`hasUserVerification` optional	boolean
`isUserConsenting` optional	boolean
`isUserVerified` optional	boolean
`extensions` optional	object[]
`uvm` optional	object[]

removeVirtualAuthenticator

Removes a previously created Virtual Authenticator.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.removeVirtualAuthenticator(authenticatorId)

Parameters

Name	Type	Details
`authenticatorId`	String	id of authenticator

addCredential

Injects a Public Key Credential Source into an existing Virtual Authenticator.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.addCredential(credentialId, isResidentCredential, rpId, privateKey, userHandle, signCount, largeBlob)

Parameters

Name	Type	Details
`credentialId`	string	The Credential ID encoded using Base64url Encoding.
`isResidentCredential`	boolean	If set to true, a client-side discoverable credential is created. If set to false, a server-side credential is created instead.
`rpId`	string	The Relying Party ID the credential is scoped to.
`privateKey`	string	An asymmetric key package containing a single private key per [RFC5958], encoded using Base64url Encoding.
`userHandle`	string	The userHandle associated to the credential encoded using Base64url Encoding. This property may not be defined.
`signCount`	number	The initial value for a signature counter associated to the public key credential source.
`largeBlob`	string	The large, per-credential blob associated to the public key credential source, encoded using Base64url Encoding. This property may not be defined.

getCredentials

Returns one Credential Parameters object for every Public Key Credential Source stored in a Virtual Authenticator, regardless of whether they were stored using Add Credential or navigator.credentials.create().

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.getCredentials(authenticatorId)

Parameters

Name	Type	Details
`authenticatorId`	String	id of authenticator

removeAllCredentials

Removes all Public Key Credential Sources stored on a Virtual Authenticator.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.removeAllCredentials(authenticatorId)

Parameters

Name	Type	Details
`authenticatorId`	String	id of authenticator

removeCredential

Removes a Public Key Credential Source stored on a Virtual Authenticator.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.removeCredential(authenticatorId, credentialId)

Parameters

Name	Type	Details
`authenticatorId`	String	id of authenticator
`credentialId`	String	id of credential

setUserVerified

The Set User Verified extension command sets the isUserVerified property on the Virtual Authenticator.

WebDriver Protocol command. More details can be found in the official protocol docs.

Usage

browser.setUserVerified(authenticatorId, credentialId)

Parameters

Name	Type	Details
`authenticatorId`	String	id of authenticator
`credentialId`	String	id of credential

newSession​

Usage​

Parameters​

Returns​

deleteSession​

Usage​

status​

Usage​

Returns​

getTimeouts​

Usage​

Returns​

setTimeouts​

Usage​

Parameters​

getUrl​

Usage​

Returns​

navigateTo​

Usage​

Parameters​

Returns​

back​

Usage​

forward​

Usage​

refresh​

Usage​

getTitle​

Usage​

Returns​

getWindowHandle​

Usage​

Returns​

closeWindow​

Usage​

switchToWindow​

Usage​

Parameters​

createWindow​

Usage​

Parameters​

Returns​

getWindowHandles​

Usage​

Returns​

printPage​

Usage​

Parameters​

Returns​

switchToFrame​

Usage​

Parameters​

switchToParentFrame​

Usage​

getWindowRect​

Usage​

Returns​

setWindowRect​

Usage​

Parameters​

Returns​

maximizeWindow​

Usage​

Returns​

minimizeWindow​

Usage​

Returns​

fullscreenWindow​

Usage​

Returns​

findElement​

Usage​

Parameters​

Example​

caution

Returns​

findElementFromShadowRoot​

Usage​

Parameters​

newSession

Usage

Parameters

Returns

deleteSession

Usage

status

Usage

Returns

getTimeouts

Usage

Returns

setTimeouts

Usage

Parameters

getUrl

Usage

Returns

navigateTo

Usage

Parameters

Returns

back

Usage

forward

Usage

refresh

Usage

getTitle

Usage

Returns

getWindowHandle

Usage

Returns

closeWindow

Usage

switchToWindow

Usage

Parameters

createWindow

Usage

Parameters

Returns

getWindowHandles

Usage

Returns

printPage

Usage

Parameters

Returns

switchToFrame

Usage

Parameters

switchToParentFrame

Usage

getWindowRect

Usage

Returns

setWindowRect

Usage

Parameters

Returns

maximizeWindow

Usage

Returns

minimizeWindow

Usage

Returns

fullscreenWindow

Usage

Returns

findElement

Usage

Parameters

Example

Returns

findElementFromShadowRoot

Usage

Parameters

Example