JSDoc: Class: GeckoDriver

# Class: GeckoDriver

## GeckoDriver(appName, server)

#### new GeckoDriver(appName, 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
--- | --- | ---
`appName` | string | Description of the product, for example "Firefox".
`server` | MarionetteServer | The instance of Marionette server.

Source:
  - driver.js, line 124

### 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 3236

#### acceptDialog()

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

Source:
  - driver.js, line 3156

#### 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 2001

##### 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 460

##### 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 2622

##### 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 2569

##### Throws:

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

##### Throws:

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

##### 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 2769

##### 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 2674

##### 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 2695

##### 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 2799

#### dismissDialog()

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

Source:
  - driver.js, line 3143

#### 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 1013

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

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

##### 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 2063

##### 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 2109

#### 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 1600

##### 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 3120

##### 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 1095

##### 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 on the page.

Source:
  - driver.js, line 2159

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

##### Returns:

Active element of the current browsing context's document element.

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 1401

##### 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 1419

##### Returns:

Unique window handles.

Type
  Array.<string>

#### getContext()

Gets the context of the server, either "chrome" or "content".

Source:
  - driver.js, line 883

#### 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 2655

##### 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 1139

##### 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 406

##### 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 2237

##### Throws:

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

##### Throws:

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

##### Throws:

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

##### Throws:

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

##### Throws:

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

##### Throws:

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

##### 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 2939

#### 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 861

#### 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 3169

#### getTitle() → {string}

Gets the current title of the window.

Source:
  - driver.js, line 1157

##### 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 544

#### 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 1366

##### 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 1383

##### 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 1439

##### 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 1165

#### globalModalDialogHandler()

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

Source:
  - driver.js, line 300

#### goBack()

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

Source:
  - driver.js, line 1210

##### 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 1253

##### 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 2371

##### Throws:

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

##### Throws:

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

##### Throws:

- 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://global/locale/about.dtd"], "about.version")

##### 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 3424

##### 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 3453

##### 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 3034

##### 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 2997

##### 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 2039

##### 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 758

##### 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 1956

##### 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 3269

##### 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 1297

##### 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 565

#### releaseActions()

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

Source:
  - driver.js, line 1976

##### 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 3492

#### sendAsync(name, msgopt, 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 targetted message listener `Marionette:SUFFIX`.
`msg` | Object | <optional> | Optional JSON serialisable object to send to the listener.
`commandID` | number | <optional> | Optional command ID to ensure synchronisity.

Source:
  - driver.js, line 341

#### 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 3196

##### 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, value)

Send key presses to element after focusing on it.

##### Parameters:

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

Source:
  - driver.js, line 2538

##### Throws:

- 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 to be either "chrome" or "content".

##### 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 873

#### 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 2957

#### 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 1919

##### 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 3469

#### 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 1644

#### 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 1475

##### 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 1926

#### 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 485

#### 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 1730

##### Throws:

- Top-level browsing context has been discarded.

  Type
    NoSuchWindowError

- A modal dialog is open, blocking this operation.

  Type
    UnexpectedAlertOpenError

#### switchToGlobalMessageManager()

Switches to the global ChromeMessageBroadcaster, potentially replacing a frame-specific ChromeMessageSender. Has no effect if the global ChromeMessageBroadcaster is already in use. If this replaces a frame-specific ChromeMessageSender, it removes the message listeners from that sender, and then puts the corresponding frame script "to sleep", which removes most of the message listeners from it as well.

Source:
  - driver.js, line 317

#### switchToParentFrame()

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

Source:
  - driver.js, line 1709

##### 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 | element id.

Source:
  - driver.js, line 2597

#### 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 1560

#### 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 2887

##### 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 3514

#### updateIdForBrowser()

Forces an update for the given browser's id.

Source:
  - driver.js, line 1326

#### 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 502