JSDoc: Class: GeckoDriver

new GeckoDriver(appId, server)

Implements (parts of) the W3C WebDriver protocol. GeckoDriver lives in chrome space and mediates calls to the message listener of the current browsing context's content frame message listener via ListenerProxy.

Throughout this prototype, functions with the argument cmd's documentation refers to the contents of the cmd.parameter object.

Parameters:

Name	Type	Description
`appId`	string	Unique identifier of the application.
`server`	MarionetteServer	The instance of Marionette server.

Source:

driver.js, line 110

Methods

acceptConnections(state)

Enables or disables accepting new socket connections.

By calling this method with false the server will not accept any further connections, but existing connections will not be forcible closed. Use true to re-enable accepting connections.

Please note that when closing the connection via the client you can end-up in a non-recoverable state if it hasn't been enabled before.

This method is used for custom in application shutdowns via marionette.quit() or marionette.restart(), like File -> Quit.

Parameters:

Name	Type	Description
`state`	boolean	True if the server should accept new socket connections.

Source:

driver.js, line 3199

acceptDialog()

Accepts a currently displayed tab modal, or returns no such alert if no modal is displayed.

Source:

driver.js, line 3118

actionChain(value) → {number}

An action chain.

Parameters:

Name	Type	Description
`value`	Object	A nested array where the inner array represents each event, and the outer array represents a collection of events.

Source:

driver.js, line 1919

Throws:

Not applicable to application.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

Last touch ID.

Type: number

addBrowser(win) → {string}

Create a new browsing context for window and add to known browsers.

Parameters:

Name	Type	Description
`win`	ChromeWindow	Window for which we will create a browsing context.

Source:

driver.js, line 419

Returns:

Returns the unique server-assigned ID of the window.

Type: string

addCookie()

Add a single cookie to the cookie store associated with the active document's address.

Parameters:

Name	Type	Description
`{Map.`		(string\|number\|boolean)> cookie Cookie object.

Source:

driver.js, line 2601

Throws:

Not available in current context.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError
If cookie is for a different domain than the active document's host.

Type

InvalidCookieDomainError

clearElement(id)

Clear the text of an element.

Parameters:

Name	Type	Description
`id`	string	Reference ID to the element that will be cleared.

Source:

driver.js, line 2540

Throws:

If id is not a string.

Type

InvalidArgumentError
If element represented by reference id is unknown.

Type

NoSuchElementError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

clickElement(id)

Send click event to element.

Parameters:

Name	Type	Description
`id`	string	Reference ID to the element that will be clicked.

Source:

driver.js, line 2100

Throws:

If element id is not a string.

Type

InvalidArgumentError
If element represented by reference id is unknown.

Type

NoSuchElementError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

close() → {Array.<string>}

Close the currently selected tab/window.

With multiple open tabs present the currently selected tab will be closed. Otherwise the window itself will be closed. If it is the last window currently open, the window will not be closed to prevent a shutdown of the application. Instead the returned list of window handles is empty.

Source:

driver.js, line 2702

Throws:

Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

Unique window handles of remaining windows.

Type: Array.<string>

closeChromeWindow() → {Array.<string>}

Close the currently selected chrome window.

If it is the last window currently open, the chrome window will not be closed to prevent a shutdown of the application. Instead the returned list of chrome window handles is empty.

Source:

driver.js, line 2739

Returns:

Unique chrome window handles of remaining chrome windows.

Type: Array.<string>

deleteAllCookies()

Delete all cookies that are visible to a document.

Source:

driver.js, line 2650

Throws:

Not available in current context.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

deleteCookie()

Delete a cookie by name.

Source:

driver.js, line 2671

Throws:

Not available in current context.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

deleteSession()

Delete Marionette session.

Source:

driver.js, line 2765

dismissDialog()

Dismisses a currently displayed tab modal, or returns no such alert if no modal is displayed.

Source:

driver.js, line 3105

executeAsyncScript(script, args, scriptTimeout, sandboxopt, newSandboxopt, filenameopt, lineopt, debug_scriptopt, directInjectopt) → {string|boolean|number|object|WebElement}

Executes a JavaScript function in the context of the current browsing context, if in content space, or in chrome space otherwise, and returns the object passed to the callback.

The callback is always the last argument to the arguments list passed to the function scope of the script. It can be retrieved as such:


    let callback = arguments[arguments.length - 1];
    callback("foo");
    // "foo" is returned

It is important to note that if the sandboxName parameter is left undefined, the script will be evaluated in a mutable sandbox, causing any change it makes on the global state of the document to have lasting side-effects.

Parameters:

Name	Type	Attributes	Description
`script`	string		Script to evaluate as a function body.
`args`	Array.<(string\|boolean\|number\|object\|WebElement)>		Arguments exposed to the script in `arguments`. The array items must be serialisable to the WebDriver protocol.
`scriptTimeout`	number		Duration in milliseconds of when to interrupt and abort the script evaluation.
`sandbox`	string	<optional>	Name of the sandbox to evaluate the script in. The sandbox is cached for later re-use on the same Window object if `newSandbox` is false. If the parameter is undefined, the script is evaluated in a mutable sandbox. If the parameter is "system", it will be evaluted in a sandbox with elevated system privileges, equivalent to chrome space.
`newSandbox`	boolean	<optional>	Forces the script to be evaluated in a fresh sandbox. Note that if it is undefined, the script will normally be evaluted in a fresh sandbox.
`filename`	string	<optional>	Filename of the client's program where this script is evaluated.
`line`	number	<optional>	Line in the client's program where this script is evaluated.
`debug_script`	boolean	<optional>	Attach an `onerror` event handler on the `Window` object. It does not differentiate content errors from chrome errors.
`directInject`	boolean	<optional>	Evaluate the script without wrapping it in a function.

Source:

driver.js, line 951

Throws:

If the script was interrupted due to reaching the scriptTimeout or default timeout.

Type

ScriptTimeoutError
If an Error was thrown whilst evaluating the script.

Type

JavaScriptError

Returns:

Return value from the script, or null which signifies either the JavaScript notion of null or undefined.

Type: string | boolean | number | object | WebElement

executeScript(script, args, scriptTimeout, sandboxopt, newSandboxopt, filenameopt, lineopt, debug_scriptopt, directInjectopt) → {string|boolean|number|object|WebElement}

Executes a JavaScript function in the context of the current browsing context, if in content space, or in chrome space otherwise, and returns the return value of the function.

Parameters:

Name	Type	Attributes	Description
`script`	string		Script to evaluate as a function body.
`args`	Array.<(string\|boolean\|number\|object\|WebElement)>		Arguments exposed to the script in `arguments`. The array items must be serialisable to the WebDriver protocol.
`scriptTimeout`	number		Duration in milliseconds of when to interrupt and abort the script evaluation.
`sandbox`	string	<optional>	Name of the sandbox to evaluate the script in. The sandbox is cached for later re-use on the same Window object if `newSandbox` is false. If he parameter is undefined, the script is evaluated in a mutable sandbox. If the parameter is "system", it will be evaluted in a sandbox with elevated system privileges, equivalent to chrome space.
`newSandbox`	boolean	<optional>	Forces the script to be evaluated in a fresh sandbox. Note that if it is undefined, the script will normally be evaluted in a fresh sandbox.
`filename`	string	<optional>	Filename of the client's program where this script is evaluated.
`line`	number	<optional>	Line in the client's program where this script is evaluated.
`debug_script`	boolean	<optional>	Attach an `onerror` event handler on the `Window` object. It does not differentiate content errors from chrome errors.
`directInject`	boolean	<optional>	Evaluate the script without wrapping it in a function.

Source:

driver.js, line 874

Throws:

If the script was interrupted due to reaching the scriptTimeout or default timeout.

Type

ScriptTimeoutError
If an Error was thrown whilst evaluating the script.

Type

JavaScriptError

Returns:

Return value from the script, or null which signifies either the JavaScript notion of null or undefined.

Type: string | boolean | number | object | WebElement

findElement(using, value)

Find an element using the indicated search strategy.

Parameters:

Name	Type	Description
`using`	string	Indicates which search method to use.
`value`	string	Value the client is looking for.

Source:

driver.js, line 1978

Throws:

Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

findElements(using, value)

Find elements using the indicated search strategy.

Parameters:

Name	Type	Description
`using`	string	Indicates which search method to use.
`value`	string	Value the client is looking for.

Source:

driver.js, line 2024

findWindow(winIterable, filter) → {Object}

Find a specific window according to some filter function.

Parameters:

Name	Type	Description
`winIterable`	Iterable.<Window>	Iterable that emits Windows.
`filter`	function	A callback function taking two arguments; the window and the outerId of the window, and returning a boolean indicating whether the window is the target.

Source:

driver.js, line 1534

Returns:

A window handle object containing the window and some associated metadata.

Type: Object

fullscreenWindow() → {Map.<string, number>}

Synchronously sets the user agent window to full screen as if the user had done "View > Enter Full Screen".

No action is taken if the window is already in full screen mode.

Not supported on Fennec.

Source:

driver.js, line 3082

Throws:

Not available for current application.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

Window rect.

Type: Map.<string, number>

get(url)

Navigate to given URL.

Navigates the current browsing context to the given URL and waits for the document to load or the session's page timeout duration to elapse before returning.

The command will return with a failure if there is an error loading the document or the URL is blocked. This can occur if it fails to reach host, the URL is malformed, or if there is a certificate issue to name some examples.

The document is considered successfully loaded when the DOMContentLoaded event on the frame element associated with the current window triggers and document.readyState is "complete".

In chrome context it will change the current window's location to the supplied URL and wait until document.readyState equals "complete" or the page timeout duration has elapsed.

Parameters:

Name	Type	Description
`url`	string	URL to navigate to.

Source:

driver.js, line 1033

Throws:

Not available in current context.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

getActiveElement() → {WebElement}

Return the active element in the document.

Source:

driver.js, line 2077

Throws:

Not available in current context.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError
If the document does not have an active element, i.e. if its document element has been deleted.

Type

NoSuchElementError

Returns:

Active element of the current browsing context's document element, if the document element is non-null.

Type: WebElement

getChromeWindowHandle() → {string}

Get the current window's handle. This corresponds to a window that may itself contain tabs.

Return an opaque server-assigned identifier to this window that uniquely identifies it within this Marionette instance. This can be used to switch to this window at a later point.

Source:

driver.js, line 1335

Throws:

Top-level browsing context has been discarded.
Type NoSuchWindowError

Returns:

Unique window handle.

Type: string

getChromeWindowHandles() → {Array.<string>}

Returns identifiers for each open chrome window for tests interested in managing a set of chrome windows and tabs separately.

Source:

driver.js, line 1353

Returns:

Unique window handles.

Type: Array.<string>

getContext() → {Context}

Gets the context type that is Marionette's current target for browsing context scoped commands.

You may choose a context through the #setContext command.

The default browsing context is Context.Content.

Source:

driver.js, line 821

Returns:

Current context.

Type: Context

getCookies()

Get all the cookies for the current domain.

This is the equivalent of calling document.cookie and parsing the result.

Source:

driver.js, line 2631

Throws:

Not available in current context.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

getCurrentUrl()

Get a string representing the current URL.

On Desktop this returns a string representation of the URL of the current top level browsing context. This is equivalent to document.location.href.

When in the context of the chrome, this returns the canonical URL of the current resource.

Source:

driver.js, line 1076

Throws:

Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

getCurrentWindow(forcedContextopt) → {ChromeWindow}

Get the session's current top-level browsing context.

It will return the outer ChromeWindow previously selected by window handle through #switchToWindow, or the first window that was registered.

Parameters:

Name	Type	Attributes	Description
`forcedContext`	Context	<optional>	Optional name of the context to use for finding the window. It will be required if a command always needs a specific context, whether which context is currently set. Defaults to the current context.

Source:

driver.js, line 366

Returns:

The current top-level browsing context.

Type: ChromeWindow

getElementAttribute(id, name) → {string}

Get a given attribute of an element.

Parameters:

Name	Type	Description
`id`	string	Web element reference ID to the element that will be inspected.
`name`	string	Name of the attribute which value to retrieve.

Source:

driver.js, line 2156

Throws:

If id or name are not strings.

Type

InvalidArgumentError
If element represented by reference id is unknown.

Type

NoSuchElementError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

Value of the attribute.

Type: string

getElementProperty(id, name) → {string}

Returns the value of a property associated with given element.

Parameters:

Name	Type	Description
`id`	string	Web element reference ID to the element that will be inspected.
`name`	string	Name of the property which value to retrieve.

Source:

driver.js, line 2196

Throws:

If id or name are not strings.

Type

InvalidArgumentError
If element represented by reference id is unknown.

Type

NoSuchElementError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

Value of the property.

Type: string

getElementRect()

Source:

driver.js, line 2463

Throws:

If id is not a string.

Type

InvalidArgumentError
If element represented by reference id is unknown.

Type

NoSuchElementError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

getElementTagName(id) → {string}

Get the tag name of the element.

Parameters:

Name	Type	Description
`id`	string	Reference ID to the element that will be inspected.

Source:

driver.js, line 2275

Throws:

If id is not a string.

Type

InvalidArgumentError
If element represented by reference id is unknown.

Type

NoSuchElementError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

Local tag name of element.

Type: string

getElementText(id) → {string}

Get the text of an element, if any. Includes the text of all child elements.

Parameters:

Name	Type	Description
`id`	string	Reference ID to the element that will be inspected.

Source:

driver.js, line 2235

Throws:

If id is not a string.

Type

InvalidArgumentError
If element represented by reference id is unknown.

Type

NoSuchElementError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

Element's text "as rendered".

Type: string

getElementValueOfCssProperty(id, propertyName) → {string}

Return the property of the computed style of an element.

Parameters:

Name	Type	Description
`id`	string	Reference ID to the element that will be checked.
`propertyName`	string	CSS rule that is being requested.

Source:

driver.js, line 2352

Throws:

If id or propertyName are not strings.

Type

InvalidArgumentError
If element represented by reference id is unknown.

Type

NoSuchElementError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

Value of |propertyName|.

Type: string

getPageSource() → {string}

Gets the page source of the content document.

Source:

driver.js, line 1120

Throws:

Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

String serialisation of the DOM of the current browsing context's active document.

Type: string

getScreenOrientation()

Get the current browser orientation.

Will return one of the valid primary orientation values portrait-primary, landscape-primary, portrait-secondary, or landscape-secondary.

Source:

driver.js, line 2901

getSessionCapabilities()

Send the current session's capabilities to the client.

Capabilities informs the client of which WebDriver features are supported by Firefox and Marionette. They are immutable for the length of the session.

The return value is an immutable map of string keys ("capabilities") to values, which may be of types boolean, numerical or string.

Source:

driver.js, line 785

getTextFromDialog()

Returns the message shown in a currently displayed modal, or returns a no such alert error if no modal is currently displayed.

Source:

driver.js, line 3131

getTitle() → {string}

Gets the current title of the window.

Source:

driver.js, line 1094

Throws:

Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

Document title of the top-level browsing context.

Type: string

getVisibleText(el, lines)

Recursively get all labeled text.

Parameters:

Name	Type	Description
`el`	Element	The parent element.
`lines`	Array.<string>	Array that holds the text lines.

Source:

driver.js, line 502

getWindowHandle() → {string}

Get the current window's handle. On desktop this typically corresponds to the currently selected tab.

Return an opaque server-assigned identifier to this window that uniquely identifies it within this Marionette instance. This can be used to switch to this window at a later point.

Source:

driver.js, line 1300

Throws:

Top-level browsing context has been discarded.
Type NoSuchWindowError

Returns:

Unique window handle.

Type: string

getWindowHandles() → {Array.<string>}

Get a list of top-level browsing contexts. On desktop this typically corresponds to the set of open tabs for browser windows, or the window itself for non-browser chrome windows.

Each window handle is assigned by the server and is guaranteed unique, however the return array does not have a specified ordering.

Source:

driver.js, line 1317

Returns:

Unique window handles.

Type: Array.<string>

getWindowRect() → {Object.<string, number>}

Get the current position and size of the browser window currently in focus.

Will return the current browser window size in pixels. Refers to window outerWidth and outerHeight values, which include scroll bars, title bars, etc.

Source:

driver.js, line 1373

Throws:

Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

Object with |x| and |y| coordinates, and |width| and |height| of browser window.

Type: Object.<string, number>

getWindowType()

Gets the current type of the window.

Source:

driver.js, line 1102

globalModalDialogHandler()

Callback used to observe the creation of new modal or tab modal dialogs during the session's lifetime.

Source:

driver.js, line 302

goBack()

Cause the browser to traverse one step backward in the joint history of the current browsing context.

Source:

driver.js, line 1147

Throws:

Not available in current context.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

goForward()

Cause the browser to traverse one step forward in the joint history of the current browsing context.

Source:

driver.js, line 1189

Throws:

Not available in current context.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

isElementDisplayed(id) → {boolean}

Check if element is displayed.

Parameters:

Name	Type	Description
`id`	string	Reference ID to the element that will be inspected.

Source:

driver.js, line 2312

Throws:

If id is not a string.

Type

InvalidArgumentError
If element represented by reference id is unknown.

Type

NoSuchElementError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

True if displayed, false otherwise.

Type: boolean

isElementEnabled(id) → {boolean}

Check if element is enabled.

Parameters:

Name	Type	Description
`id`	string	Reference ID to the element that will be checked.

Source:

driver.js, line 2393

Throws:

If id is not a string.

Type

InvalidArgumentError
If element represented by reference id is unknown.

Type

NoSuchElementError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

True if enabled, false if disabled.

Type: boolean

isElementSelected(id) → {boolean}

Check if element is selected.

Parameters:

Name	Type	Description
`id`	string	Reference ID to the element that will be checked.

Source:

driver.js, line 2432

Throws:

If id is not a string.

Type

InvalidArgumentError
If element represented by reference id is unknown.

Type

NoSuchElementError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

True if selected, false if unselected.

Type: boolean

localizeEntity(urls, id) → {string}

Retrieve the localized string for the specified entity id.

Example: localizeEntity(["chrome://branding/locale/brand.dtd"], "brandShortName")

Parameters:

Name	Type	Description
`urls`	Array.<string>	Array of .dtd URLs.
`id`	string	The ID of the entity to retrieve the localized string for.

Source:

driver.js, line 3371

Returns:

The localized string for the requested entity.

Type: string

localizeProperty(urls, id) → {string}

Retrieve the localized string for the specified property id.

Example:

localizeProperty(
    ["chrome://global/locale/findbar.properties"], "FastFind");

Parameters:

Name	Type	Description
`urls`	Array.<string>	Array of .properties URLs.
`id`	string	The ID of the property to retrieve the localized string for.

Source:

driver.js, line 3400

Returns:

The localized string for the requested property.

Type: string

maximizeWindow() → {Object.<string, number>}

Synchronously maximizes the user agent window as if the user pressed the maximize button.

No action is taken if the window is already maximized.

Not supported on Fennec.

Source:

driver.js, line 2996

Throws:

Not available for current application.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

Window rect.

Type: Object.<string, number>

minimizeWindow() → {Object.<string, number>}

Synchronously minimizes the user agent window as if the user pressed the minimize button.

No action is taken if the window is already minimized.

Not supported on Fennec.

Source:

driver.js, line 2959

Throws:

Not available for current application.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

Window rect and window state.

Type: Object.<string, number>

multiAction(value)

A multi-action chain.

Parameters:

Name	Type	Description
`value`	Object	A nested array where the inner array represents eache vent, the middle array represents a collection of events for each finger, and the outer array represents all fingers.

Source:

driver.js, line 1956

Throws:

Not available in current context.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

newSession(sessionIdopt, capabilitiesopt) → {Object}

Create a new WebDriver session.

It is expected that the caller performs the necessary checks on the requested capabilities to be WebDriver conforming. The WebDriver service offered by Marionette does not match or negotiate capabilities beyond type- and bounds checks.

Capabilities

pageLoadStrategy (string): The page load strategy to use for the current session. Must be one of "none", "eager", and "normal".
acceptInsecureCerts (boolean): Indicates whether untrusted and self-signed TLS certificates are implicitly trusted on navigation for the duration of the session.
timeouts (Timeouts object): Describes the timeouts imposed on certian session operations.
proxy (Proxy object): Defines the proxy configuration.
moz:accessibilityChecks (boolean): Run a11y checks when clicking elements.
moz:webdriverClick (boolean): Use a WebDriver conforming WebDriver::ElementClick.

Timeouts object

script (number): Determines when to interrupt a script that is being evaluates.
pageLoad (number): Provides the timeout limit used to interrupt navigation of the browsing context.
implicit (number): Gives the timeout of when to abort when locating an element.

Proxy object

proxyType (string): Indicates the type of proxy configuration. Must be one of "pac", "direct", "autodetect", "system", or "manual".
proxyAutoconfigUrl (string): Defines the URL for a proxy auto-config file if proxyType is equal to "pac".
ftpProxy (string): Defines the proxy host for FTP traffic when the proxyType is "manual".
httpProxy (string): Defines the proxy host for HTTP traffic when the proxyType is "manual".
noProxy (string): Lists the adress for which the proxy should be bypassed when the proxyType is "manual". Must be a JSON List containing any number of any of domains, IPv4 addresses, or IPv6 addresses.
sslProxy (string): Defines the proxy host for encrypted TLS traffic when the proxyType is "manual".
socksProxy (string): Defines the proxy host for a SOCKS proxy traffic when the proxyType is "manual".
socksVersion (string): Defines the SOCKS proxy version when the proxyType is "manual". It must be any integer between 0 and 255 inclusive.

Example

Input:


    {"capabilities": {"acceptInsecureCerts": true}}

Parameters:

Name	Type	Attributes	Description
`sessionId`	string	<optional>	Normally a unique ID is given to a new session, however this can be overriden by providing this field.
`capabilities`	Object.<string, *>	<optional>	JSON Object containing any of the recognised capabilities listed above.

Source:

driver.js, line 685

Throws:

If, for whatever reason, a session could not be created.
Type SessionNotCreatedError

Returns:

Session ID and capabilities offered by the WebDriver service.

Type: Object

performActions(actions)

Perform a series of grouped actions at the specified points in time.

Parameters:

Name	Type	Description
`actions`	Array.<?>	Array of objects that each represent an action sequence.

Source:

driver.js, line 1874

Throws:

Not yet available in current context.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

quit(flagsopt) → {string}

Quits the application with the provided flags.

Marionette will stop accepting new connections before ending the current session, and finally attempting to quit the application.

Optional nsIAppStartup flags may be provided as an array of masks, and these will be combined by ORing them with a bitmask. The available masks are defined in https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIAppStartup.

Crucially, only one of the Quit flags can be specified. The |eRestart| flag may be bit-wise combined with one of the Quit flags to cause the application to restart after it quits.

Parameters:

Name	Type	Attributes	Description
`flags`	Array.<string>	<optional>	Constant name of masks to pass to \|Services.startup.quit\|. If empty or undefined, \|nsIAppStartup.eAttemptQuit\| is used.

Source:

driver.js, line 3232

Throws:

If flags contains unknown or incompatible flags, for example multiple Quit flags.
Type InvalidArgumentError

Returns:

Explaining the reason why the application quit. This can be in response to a normal shutdown or restart, yielding "shutdown" or "restart", respectively.

Type: string

refresh()

Causes the browser to reload the page in current top-level browsing context.

Source:

driver.js, line 1232

Throws:

Not available in current context.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

registerBrowser()

Handles registration of new content listener browsers. Depending on their type they are either accepted or ignored.

Source:

driver.js, line 523

releaseActions()

Release all the keys and pointer buttons that are currently depressed.

Source:

driver.js, line 1894

Throws:

Not available in current context.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

runReftest()

Run a reftest.

Source:

driver.js, line 3439

sendAsync(name, dataopt, commandIDopt)

Helper method to send async messages to the content listener. Correct usage is to pass in the name of a function in listener.js, a serialisable object, and optionally the current command's ID when not using the modern dispatching technique.

Parameters:

Name	Type	Attributes	Description
`name`	string		Suffix of the target message handler `Marionette:SUFFIX`.
`data`	Object	<optional>	Data that must be serialisable using `evaluate.toJSON`.
`commandID`	number	<optional>	Optional command ID to ensure synchronisity.

Source:

driver.js, line 329

Throws:

If data could not be marshaled.

Type

JavaScriptError
If there is no current target frame.

Type

NoSuchWindowError

sendKeysToDialog(text)

Set the user prompt's value field.

Sends keys to the input field of a currently displayed modal, or returns a no such alert error if no modal is currently displayed. If a tab modal is currently displayed but has no means for text input, an element not visible error is returned.

Parameters:

Name	Type	Description
`text`	string	Input to the user prompt's value field.

Source:

driver.js, line 3158

Throws:

If the current user prompt is an alert or confirm.

Type

ElementNotInteractableError
If there is no current user prompt.

Type

NoSuchAlertError
If the current user prompt is something other than an alert, confirm, or a prompt.

Type

UnsupportedOperationError

sendKeysToElement(id, text)

Send key presses to element after focusing on it.

Parameters:

Name	Type	Description
`id`	string	Reference ID to the element that will be checked.
`text`	string	Value to send to the element.

Source:

driver.js, line 2505

Throws:

If id or text are not strings.

Type

InvalidArgumentError
If element represented by reference id is unknown.

Type

NoSuchElementError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

setContext(value)

Sets the context of the subsequent commands.

All subsequent requests to commands that in some way involve interaction with a browsing context will target the chosen browsing context.

Parameters:

Name	Type	Description
`value`	string	Name of the context to be switched to. Must be one of "chrome" or "content".

Source:

driver.js, line 805

Throws:

If value is not a string.

Type

InvalidArgumentError
If value is not a valid browsing context.

Type

WebDriverError

setScreenOrientation()

Set the current browser orientation.

The supplied orientation should be given as one of the valid orientation values. If the orientation is unknown, an error will be raised.

Valid orientations are "portrait" and "landscape", which fall back to "portrait-primary" and "landscape-primary" respectively, and "portrait-secondary" as well as "landscape-secondary".

Source:

driver.js, line 2919

setTimeouts(Dictionary)

Set timeout for page loading, searching, and scripts.

Parameters:

Name	Type	Description
`Dictionary`	Object.<string, number>	of timeout types and their new value, where all timeout types are optional.

Source:

driver.js, line 1837

Throws:

If timeout type key is unknown, or the value provided with it is not an integer.
Type InvalidArgumentError

setupReftest()

Initialize the reftest mode

Source:

driver.js, line 3416

setWindowHandle(winProperties, focusopt)

Switch the marionette window to a given window. If the browser in the window is unregistered, registers that browser and waits for the registration is complete. If |focus| is true then set the focus on the window.

Parameters:

Name	Type	Attributes	Description
`winProperties`	Object		Object containing window properties such as returned from GeckoDriver#findWindow
`focus`	boolean	<optional>	A boolean value which determines whether to focus the window. Defaults to true.

Source:

driver.js, line 1578

setWindowRect(x, y, width, height) → {Object.<string, number>}

Set the window position and size of the browser on the operating system window manager.

The supplied |width| and |height| values refer to the window outerWidth and outerHeight values, which include browser chrome and OS-level window borders.

Parameters:

Name	Type	Description
`x`	number	X coordinate of the top/left of the window that it will be moved to.
`y`	number	Y coordinate of the top/left of the window that it will be moved to.
`width`	number	Width to resize the window to.
`height`	number	Height to resize the window to.

Source:

driver.js, line 1409

Throws:

Not applicable to application.

Type

UnsupportedOperationError
Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

Returns:

Object with |x| and |y| coordinates and |width| and |height| dimensions.

Type: Object.<string, number>

singleTap()

Single tap.

Source:

driver.js, line 1844

startBrowser(win, falseopt)

Registers a new browser, win, with Marionette.

If we have not seen the browser content window before, the listener frame script will be loaded into it. If isNewSession is true, we will switch focus to the start frame when it registers.

Parameters:

Name	Type	Attributes	Description
`win`	ChromeWindow		Window whose browser we need to access.
`false`	boolean	<optional>	isNewSession True if this is the first time we're talking to this browser.

Source:

driver.js, line 444

switchToFrame(element, id)

Switch to a given frame within the current window.

Parameters:

Name	Type	Description
`element`	Object	A web element reference to the element to switch to.
`id`	string \| number	If element is not defined, then this holds either the id, name, or index of the frame to switch to.

Source:

driver.js, line 1661

Throws:

Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

switchToParentFrame()

Set the current browsing context for future commands to the parent of the current browsing context.

Source:

driver.js, line 1640

Throws:

Top-level browsing context has been discarded.

Type

NoSuchWindowError
A modal dialog is open, blocking this operation.

Type

UnexpectedAlertOpenError

switchToShadowRoot(id)

Switch to shadow root of the given host element.

Parameters:

Name	Type	Description
`id`	string	Reference ID to the element.

Source:

driver.js, line 2575

Throws:

If id is not a string.

Type

InvalidArgumentError
If element represented by reference id is unknown.

Type

NoSuchElementError

switchToWindow(name, focusopt)

Switch current top-level browsing context by name or server-assigned ID. Searches for windows by name, then ID. Content windows take precedence.

Parameters:

Name	Type	Attributes	Description
`name`	string		Target name or ID of the window to switch to.
`focus`	boolean	<optional>	A boolean value which determines whether to focus the window. Defaults to true.

Source:

driver.js, line 1494

takeScreenshot(idopt, highlightsopt, full, hashopt, scrollopt) → {string}

Takes a screenshot of a web element, current frame, or viewport.

The screen capture is returned as a lossless PNG image encoded as a base 64 string.

If called in the content context, the |id| argument is not null and refers to a present and visible web element's ID, the capture area will be limited to the bounding box of that element. Otherwise, the capture area will be the bounding box of the current frame.

If called in the chrome context, the screenshot will always represent the entire viewport.

Parameters:

Name	Type	Attributes	Description
`id`	string	<optional>	Optional web element reference to take a screenshot of. If undefined, a screenshot will be taken of the document element.
`highlights`	Array.<string>	<optional>	List of web elements to highlight.
`full`	boolean		True to take a screenshot of the entire document element. Is not considered if `id` is not defined. Defaults to true.
`hash`	boolean	<optional>	True if the user requests a hash of the image data.
`scroll`	boolean	<optional>	Scroll to element if \|id\| is provided. If undefined, it will scroll to the element.

Source:

driver.js, line 2847

Returns:

If hash is false, PNG image encoded as Base64 encoded string. If hash is true, hex digest of the SHA-256 hash of the Base64 encoded string.

Type: string

teardownReftest()

End a reftest run.

Closes the reftest window (without changing the current window handle), and removes cached canvases.

Source:

driver.js, line 3461

updateIdForBrowser()

Forces an update for the given browser's id.

Source:

driver.js, line 1260

whenBrowserStarted(window, isNewSession)

Callback invoked after a new session has been started in a browser. Loads the Marionette frame script into the browser if needed.

Parameters:

Name	Type	Description
`window`	ChromeWindow	Window whose browser we need to access.
`isNewSession`	boolean	True if this is the first time we're talking to this browser.

Source:

driver.js, line 460