driver module

class GeckoDriver(server)

Implements (parts of) the W3C WebDriver protocol. GeckoDriver lives in chrome space and mediates calls to the current browsing context’s actor.

Throughout this prototype, functions with the argument <var>cmd</var>’s documentation refers to the contents of the <code>cmd.parameter</code> object.

Arguments
  • server (MarionetteServer()) – The instance of Marionette server.

GeckoDriver._getCurrentURL()

Get the current visible URL.

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

Arguments
  • state (boolean()) – True if the server should accept new socket connections.

GeckoDriver.acceptDialog()

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

Throws

NoSuchWindowError() – Top-level browsing context has been discarded.

GeckoDriver.addBrowser(win)

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

Arguments
  • win (ChromeWindow()) – Window for which we will create a browsing context.

Returns

string – Returns the unique server-assigned ID of the window.

GeckoDriver.addCookie({Map)

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

Arguments
  • {Map.<string, – (string|number|boolean)> cookie Cookie object.

Throws
  • InvalidCookieDomainError() – If <var>cookie</var> is for a different domain than the active document’s host.

  • NoSuchWindowError() – Bbrowsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

  • UnsupportedOperationError() – Not available in current context.

GeckoDriver.clearElement(id)

Clear the text of an element.

Arguments
  • id (string()) – Reference ID to the element that will be cleared.

Throws
  • InvalidArgumentError() – If <var>id</var> is not a string.

  • NoSuchElementError() – If element represented by reference <var>id</var> is unknown.

  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

GeckoDriver.clickElement(id)

Send click event to element.

Arguments
  • id (string()) – Reference ID to the element that will be clicked.

Throws
  • InvalidArgumentError() – If element <var>id</var> is not a string.

  • NoSuchElementError() – If element represented by reference <var>id</var> is unknown.

  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

GeckoDriver.close()

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.

Throws
  • NoSuchWindowError() – Top-level browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

Returns

Array.<string> – Unique window handles of remaining windows.

GeckoDriver.closeChromeWindow()

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.

Throws

NoSuchWindowError() – Top-level browsing context has been discarded.

Returns

Array.<string> – Unique chrome window handles of remaining chrome windows.

GeckoDriver.deleteAllCookies()

Delete all cookies that are visible to a document.

Throws
  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

  • UnsupportedOperationError() – Not available in current context.

GeckoDriver.deleteCookie(cmd)

Delete a cookie by name.

Throws
  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

  • UnsupportedOperationError() – Not available in current context.

GeckoDriver.deleteSession()

Delete Marionette session.

GeckoDriver.dismissDialog()

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

Throws

NoSuchWindowError() – Top-level browsing context has been discarded.

GeckoDriver.executeAsyncScript(script, args, sandbox, newSandbox, filename, line)

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 <var>arguments</var> list passed to the function scope of the script. It can be retrieved as such:

<pre><code>

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

</code></pre>

It is important to note that if the <var>sandboxName</var> 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.

Arguments
  • script (string()) – Script to evaluate as a function body.

  • args (Array.) – Arguments exposed to the script in <code>arguments</code>. The array items must be serialisable to the WebDriver protocol.

  • sandbox (string()) – Name of the sandbox to evaluate the script in. The sandbox is cached for later re-use on the same Window object if <var>newSandbox</var> 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()) – 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()) – Filename of the client’s program where this script is evaluated.

  • line (number()) – Line in the client’s program where this script is evaluated.

Throws
  • JavaScriptError() – If an Error was thrown whilst evaluating the script.

  • NoSuchWindowError() – Browsing context has been discarded.

  • ScriptTimeoutError() – If the script was interrupted due to reaching the session’s script timeout.

Returns

string|boolean|number|object|WebElement – Return value from the script, or null which signifies either the JavaScript notion of null or undefined.

GeckoDriver.executeScript(script, args, sandbox, newSandbox, filename, line)

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 <var>sandboxName</var> 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.

Arguments
  • script (string()) – Script to evaluate as a function body.

  • args (Array.) – Arguments exposed to the script in <code>arguments</code>. The array items must be serialisable to the WebDriver protocol.

  • sandbox (string()) – Name of the sandbox to evaluate the script in. The sandbox is cached for later re-use on the same Window object if <var>newSandbox</var> 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()) – 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()) – Filename of the client’s program where this script is evaluated.

  • line (number()) – Line in the client’s program where this script is evaluated.

Throws
  • JavaScriptError() – If an {@link Error} was thrown whilst evaluating the script.

  • NoSuchWindowError() – Browsing context has been discarded.

  • ScriptTimeoutError() – If the script was interrupted due to reaching the session’s script timeout.

Returns

string|boolean|number|object|WebElement – Return value from the script, or null which signifies either the JavaScript notion of null or undefined.

GeckoDriver.findElement(using, value)

Find an element using the indicated search strategy.

Arguments
  • using (string()) – Indicates which search method to use.

  • value (string()) – Value the client is looking for.

Throws
  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

GeckoDriver.findElements(using, value)

Find elements using the indicated search strategy.

Arguments
  • using (string()) – Indicates which search method to use.

  • value (string()) – Value the client is looking for.

Throws

NoSuchWindowError() – Browsing context has been discarded.

GeckoDriver.fullscreenWindow()

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.

Throws
  • NoSuchWindowError() – Top-level browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

  • UnsupportedOperationError() – Not available for current application.

Returns

Map.<string, number> – Window rect.

GeckoDriver.getActiveElement()

Return the active element in the document.

Throws
  • NoSuchElementError() – If the document does not have an active element, i.e. if its document element has been deleted.

  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

  • UnsupportedOperationError() – Not available in current context.

Returns

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

GeckoDriver.getActor(options)

Get the current “MarionetteCommands” parent actor.

Arguments
  • options (Object()) –

  • options.top (boolean()) – If set to true use the window’s top-level browsing context for the actor, otherwise the one from the currently selected frame. Defaults to false.

Returns

MarionetteCommandsParent – The parent actor.

GeckoDriver.getBrowsingContext(options)

Get the selected BrowsingContext for the current context.

Arguments
  • options (Object()) –

  • options.context (Context()) – Context (content or chrome) for which to retrieve the browsing context. Defaults to the current one.

  • options.parent (boolean()) – If set to true return the window’s parent browsing context, otherwise the one from the currently selected frame. Defaults to false.

  • options.top (boolean()) – If set to true return the window’s top-level browsing context, otherwise the one from the currently selected frame. Defaults to false.

Returns

BrowsingContext – The browsing context, or null if none is available

GeckoDriver.getContext()

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

You may choose a context through the {@link #setContext} command.

The default browsing context is {@link Context.Content}.

Returns

Context – Current context.

GeckoDriver.getCookies()

Get all the cookies for the current domain.

This is the equivalent of calling <code>document.cookie</code> and parsing the result.

Throws
  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

  • UnsupportedOperationError() – Not available in current context.

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

Throws
  • NoSuchWindowError() – Top-level browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

GeckoDriver.getCurrentWindow(options)

Get the currently selected window.

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

Arguments
  • options (Object()) –

  • options.context (Context()) – 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.

Returns

ChromeWindow – The current top-level browsing context.

GeckoDriver.getElementAttribute(id, name)

Get a given attribute of an element.

Arguments
  • id (string()) – Web element reference ID to the element that will be inspected.

  • name (string()) – Name of the attribute which value to retrieve.

Throws
  • InvalidArgumentError() – If <var>id</var> or <var>name</var> are not strings.

  • NoSuchElementError() – If element represented by reference <var>id</var> is unknown.

  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

Returns

string – Value of the attribute.

GeckoDriver.getElementProperty(id, name)

Returns the value of a property associated with given element.

Arguments
  • id (string()) – Web element reference ID to the element that will be inspected.

  • name (string()) – Name of the property which value to retrieve.

Throws
  • InvalidArgumentError() – If <var>id</var> or <var>name</var> are not strings.

  • NoSuchElementError() – If element represented by reference <var>id</var> is unknown.

  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

Returns

string – Value of the property.

GeckoDriver.getElementRect(cmd)
Throws
  • InvalidArgumentError() – If <var>id</var> is not a string.

  • NoSuchElementError() – If element represented by reference <var>id</var> is unknown.

  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

GeckoDriver.getElementTagName(id)

Get the tag name of the element.

Arguments
  • id (string()) – Reference ID to the element that will be inspected.

Throws
  • InvalidArgumentError() – If <var>id</var> is not a string.

  • NoSuchElementError() – If element represented by reference <var>id</var> is unknown.

  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

Returns

string – Local tag name of element.

GeckoDriver.getElementText(id)

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

Arguments
  • id (string()) – Reference ID to the element that will be inspected.

Throws
  • InvalidArgumentError() – If <var>id</var> is not a string.

  • NoSuchElementError() – If element represented by reference <var>id</var> is unknown.

  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

Returns

string – Element’s text “as rendered”.

GeckoDriver.getElementValueOfCssProperty(id, propertyName)

Return the property of the computed style of an element.

Arguments
  • id (string()) – Reference ID to the element that will be checked.

  • propertyName (string()) – CSS rule that is being requested.

Throws
  • InvalidArgumentError() – If <var>id</var> or <var>propertyName</var> are not strings.

  • NoSuchElementError() – If element represented by reference <var>id</var> is unknown.

  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

Returns

string – Value of |propertyName|.

GeckoDriver.getPageSource()

Gets the page source of the content document.

Throws
  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

Returns

string – String serialisation of the DOM of the current browsing context’s active document.

GeckoDriver.getScreenOrientation()

Get the current browser orientation.

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

Throws

NoSuchWindowError() – Top-level browsing context has been discarded.

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

GeckoDriver.getTextFromDialog()

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

Throws

NoSuchWindowError() – Top-level browsing context has been discarded.

GeckoDriver.getTitle()

Gets the current title of the window.

Throws
  • NoSuchWindowError() – Top-level browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

Returns

string – Document title of the top-level browsing context.

GeckoDriver.getVisibleText(el, lines)

Recursively get all labeled text.

Arguments
  • el (Element()) – The parent element.

  • lines (Array.) – Array that holds the text lines.

GeckoDriver.getWindowHandle()

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

For chrome scope it returns the window identifier for the current chrome window for tests interested in managing the chrome window and tab separately.

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.

Throws

NoSuchWindowError() – Top-level browsing context has been discarded.

Returns

string – Unique window handle.

GeckoDriver.getWindowHandles()

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.

For chrome scope it returns identifiers for each open chrome window for tests interested in managing a set of chrome windows and tabs separately.

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

Returns

Array.<string> – Unique window handles.

GeckoDriver.getWindowRect()

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.

Throws
  • NoSuchWindowError() – Top-level browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

Returns

Object.<string, number> – Object with |x| and |y| coordinates, and |width| and |height| of browser window.

GeckoDriver.getWindowType()

Gets the current type of the window.

Throws

NoSuchWindowError() – Top-level browsing context has been discarded.

Returns

string – Type of window

GeckoDriver.goBack()

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

Throws
  • NoSuchWindowError() – Top-level browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

  • UnsupportedOperationError() – Not available in current context.

GeckoDriver.goForward()

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

Throws
  • NoSuchWindowError() – Top-level browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

  • UnsupportedOperationError() – Not available in current context.

GeckoDriver.handleModalDialog(action, dialog)

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

GeckoDriver.isElementDisplayed(id)

Check if element is displayed.

Arguments
  • id (string()) – Reference ID to the element that will be inspected.

Throws
  • InvalidArgumentError() – If <var>id</var> is not a string.

  • NoSuchElementError() – If element represented by reference <var>id</var> is unknown.

  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

Returns

boolean – True if displayed, false otherwise.

GeckoDriver.isElementEnabled(id)

Check if element is enabled.

Arguments
  • id (string()) – Reference ID to the element that will be checked.

Throws
  • InvalidArgumentError() – If <var>id</var> is not a string.

  • NoSuchElementError() – If element represented by reference <var>id</var> is unknown.

  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

Returns

boolean – True if enabled, false if disabled.

GeckoDriver.isElementSelected(id)

Check if element is selected.

Arguments
  • id (string()) – Reference ID to the element that will be checked.

Throws
  • InvalidArgumentError() – If <var>id</var> is not a string.

  • NoSuchElementError() – If element represented by reference <var>id</var> is unknown.

  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

Returns

boolean – True if selected, false if unselected.

GeckoDriver.localizeEntity(urls, id)

Retrieve the localized string for the specified entity id.

Example:

localizeEntity([“chrome://branding/locale/brand.dtd”], “brandShortName”)

Arguments
  • urls (Array.) – Array of .dtd URLs.

  • id (string()) – The ID of the entity to retrieve the localized string for.

Returns

string – The localized string for the requested entity.

GeckoDriver.localizeProperty(urls, id)

Retrieve the localized string for the specified property id.

Example:

localizeProperty(

[“chrome://global/locale/findbar.properties”], “FastFind”);

Arguments
  • urls (Array.) – Array of .properties URLs.

  • id (string()) – The ID of the property to retrieve the localized string for.

Returns

string – The localized string for the requested property.

GeckoDriver.maximizeWindow()

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.

Throws
  • NoSuchWindowError() – Top-level browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

  • UnsupportedOperationError() – Not available for current application.

Returns

Object.<string, number> – Window rect.

GeckoDriver.minimizeWindow()

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.

Throws
  • NoSuchWindowError() – Top-level browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

  • UnsupportedOperationError() – Not available for current application.

Returns

Object.<string, number> – Window rect and window state.

GeckoDriver.navigateTo(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.

Arguments
  • url (string()) – URL to navigate to.

Throws
  • NoSuchWindowError() – Top-level browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

  • UnsupportedOperationError() – Not available in current context.

GeckoDriver.newSession(cmd)

Create a new WebDriver session.

Arguments
  • cmd (Object()) –

  • cmd.parameters (Object.) – JSON Object containing any of the recognised capabilities as listed on the WebDriverSession class.

Throws

SessionNotCreatedError() – If, for whatever reason, a session could not be created.

Returns

Object – Session ID and capabilities offered by the WebDriver service.

GeckoDriver.newWindow(type, focus, private)

Open a new top-level browsing context.

Arguments
  • type (string()) – Optional type of the new top-level browsing context. Can be one of tab or window. Defaults to tab.

  • focus (boolean()) – Optional flag if the new top-level browsing context should be opened in foreground (focused) or background (not focused). Defaults to false.

  • private (boolean()) – Optional flag, which gets only evaluated for type window. True if the new top-level browsing context should be a private window. Defaults to false.

Throws

NoSuchWindowError() – Top-level browsing context has been discarded.

Returns

Object.<string, string> – Handle and type of the new browsing context.

GeckoDriver.performActions(actions)

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

Arguments
  • actions (Array.) – Array of objects that each represent an action sequence.

Throws
  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

  • UnsupportedOperationError() – Not yet available in current context.

GeckoDriver.print(landscape, margin, pageRanges, page, shrinkToFit, printBackground, scale)

Print page as PDF.

Arguments
  • landscape (boolean()) – Paper orientation. Defaults to false.

  • margin.bottom (number()) – Bottom margin in cm. Defaults to 1cm (~0.4 inches).

  • margin.left (number()) – Left margin in cm. Defaults to 1cm (~0.4 inches).

  • margin.right (number()) – Right margin in cm. Defaults to 1cm (~0.4 inches).

  • margin.top (number()) – Top margin in cm. Defaults to 1cm (~0.4 inches).

  • pageRanges (string()) – (not supported) Paper ranges to print, e.g., ‘1-5, 8, 11-13’. Defaults to the empty string, which means print all pages.

  • page.height (number()) – Paper height in cm. Defaults to US letter height (11 inches / 27.94cm)

  • page.width (number()) – Paper width in cm. Defaults to US letter width (8.5 inches / 21.59cm)

  • shrinkToFit (boolean()) – Whether or not to override page size as defined by CSS. Defaults to true, in which case the content will be scaled to fit the paper size.

  • printBackground (boolean()) – Print background graphics. Defaults to false.

  • scale (number()) – Scale of the webpage rendering. Defaults to 1.

Throws

NoSuchWindowError() – Top-level browsing context has been discarded.

Returns

string – Base64 encoded PDF representing printed document

GeckoDriver.quit(flags)

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 {@link 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.

Arguments
Throws

InvalidArgumentError() – If <var>flags</var> contains unknown or incompatible flags, for example multiple Quit flags.

Returns

Object.<string, boolean> – Dictionary containing information that explains the shutdown reason. The value for cause contains the shutdown kind like “shutdown” or “restart”, while forced will indicate if it was a normal or forced shutdown of the application.

GeckoDriver.refresh()

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

Throws
  • NoSuchWindowError() – Top-level browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

  • UnsupportedOperationError() – Not available in current context.

GeckoDriver.registerBrowser(browserElement)

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

Arguments
  • browserElement (xul:browser()) –

GeckoDriver.registerListenersForWindow(win)

Register event listeners for the specified window.

Arguments
  • win (ChromeWindow()) – Chrome window to register event listeners for.

GeckoDriver.releaseActions()

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

Throws
  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

  • UnsupportedOperationError() – Not available in current context.

GeckoDriver.runReftest(cmd)

Run a reftest.

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

Arguments
  • text (string()) – Input to the user prompt’s value field.

Throws
  • ElementNotInteractableError() – If the current user prompt is an alert or confirm.

  • NoSuchAlertError() – If there is no current user prompt.

  • NoSuchWindowError() – Top-level browsing context has been discarded.

  • UnsupportedOperationError() – If the current user prompt is something other than an alert, confirm, or a prompt.

GeckoDriver.sendKeysToElement(id, text)

Send key presses to element after focusing on it.

Arguments
  • id (string()) – Reference ID to the element that will be checked.

  • text (string()) – Value to send to the element.

Throws
  • InvalidArgumentError() – If id or text are not strings.

  • NoSuchElementError() – If element represented by reference id is unknown.

  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

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

Arguments
  • value (string()) – Name of the context to be switched to. Must be one of “chrome” or “content”.

Throws
  • InvalidArgumentError() – If <var>value</var> is not a string.

  • WebDriverError() – If <var>value</var> is not a valid browsing context.

GeckoDriver.setScreenOrientation(cmd)

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

Throws

NoSuchWindowError() – Top-level browsing context has been discarded.

GeckoDriver.setTimeouts(Dictionary)

Set timeout for page loading, searching, and scripts.

Arguments
  • Dictionary (Object.) – of timeout types and their new value, where all timeout types are optional.

Throws

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

GeckoDriver.setWindowHandle(winProperties, focus)

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

Arguments
  • winProperties (Object()) – Object containing window properties such as returned from GeckoDriver#getWindowProperties()

  • focus (boolean()) – A boolean value which determines whether to focus the window. Defaults to true.

GeckoDriver.setWindowRect(x, y, width, height)

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.

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

Throws
  • NoSuchWindowError() – Top-level browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

  • UnsupportedOperationError() – Not applicable to application.

Returns

Object.<string, number> – Object with x and y coordinates and width and height dimensions.

GeckoDriver.setupReftest(cmd)

Initialize the reftest mode

GeckoDriver.singleTap(cmd)

Single tap.

GeckoDriver.switchToFrame(element, id)

Switch to a given frame within the current window.

Arguments
  • element (string|Object()) – A web element reference of the frame or its element id.

  • id (number()) – The index of the frame to switch to. If both element and id are not defined, switch to top-level frame.

Throws
  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

GeckoDriver.switchToParentFrame()

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

Throws
  • NoSuchWindowError() – Browsing context has been discarded.

  • UnexpectedAlertOpenError() – A modal dialog is open, blocking this operation.

GeckoDriver.switchToWindow(handle, focus)

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

Arguments
  • handle (string()) – Handle of the window to switch to.

  • focus (boolean()) – A boolean value which determines whether to focus the window. Defaults to true.

Throws

NoSuchWindowError() – Top-level browsing context has been discarded.

GeckoDriver.takeScreenshot(id, full, hash, scroll)

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.

Arguments
  • id (string()) – Optional web element reference to take a screenshot of. If undefined, a screenshot will be taken of the document element.

  • full (boolean()) – True to take a screenshot of the entire document element. Is only considered if <var>id</var> is not defined. Defaults to true.

  • hash (boolean()) – True if the user requests a hash of the image data. Defaults to false.

  • scroll (boolean()) – Scroll to element if |id| is provided. Defaults to true.

Throws

NoSuchWindowError() – Top-level browsing context has been discarded.

Returns

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

GeckoDriver.teardownReftest()

End a reftest run.

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

GeckoDriver.unregisterListenersForWindow(win)

Unregister event listeners for the specified window.

Arguments
  • win (ChromeWindow()) – Chrome window to unregister event listeners for.