Global

Members

(constant) COMMON_FORM_CONTROLS

Common form controls that user can change the value property interactively.

Source:
Source:

(constant) DISABLED_ATTRIBUTE_SUPPORTED_XUL

XUL elements that support disabled attribute.

Source:

event

Provides functionality for creating and sending DOM events.

Source:

(constant) INPUT_TYPES_NO_EVENT

Input elements that do not fire input and change events when value property changes.

Source:

(constant) KEY_LOCATION_LOOKUP

Map from raw key (codepoint) to key location

Source:

(constant) loadListener

The load listener singleton helps to keep track of active page load activities, and can be used by any command which might cause a navigation to happen. In the specific case of a reload of the frame script it allows to continue observing the current page load.

Source:

(constant) MODIFIER_NAME_LOOKUP

Map from normalized key value to UI Events modifier key name

Source:

(constant) NORMALIZED_KEY_LOOKUP

Map from raw key (codepoint) to normalized key value

Source:

(constant) WindowState :string

Marionette representation of the ChromeWindow window state.

Type:
  • string
Properties:
Name Type Description
Maximized string
Minimized string
Normal string
Fullscreen string
from string

Converts nsIDOMChromeWindow.windowState to WindowState.
Source:

(constant) XUL_CHECKED_ELS

XUL elements that support checked property.

Source:

(constant) XUL_SELECTED_ELS

XUL elements that support selected property.

Source:

Methods

actionChain()

Start action chain on one finger.

Source:

BulkPacket(transport)

With a bulk packet, data is transferred by temporarily handing over the transport's input or output stream to the application layer for writing data directly. This can be much faster for large data sets, and avoids various stages of copies and data duplication inherent in the JSON packet type. The bulk packet looks like:

bulk [actor] [type] [length]:[data]

The interpretation of the data portion depends on the kind of actor and the packet's type. See the Remote Debugging Protocol Stream Transport spec for more details.

Parameters:
Name Type Description
transport DebuggerTransport

Transport instance that will own the packet.
Source:

cancelRequest()

Cancel the polling and remove the event listener associated with a current navigation request in case we're interupted by an onbeforeunload handler and navigation doesn't complete.

Source:

checkExpectedEvent_()

Check if the event was fired or not. The provided event handler will be removed.

Source:

ChildDebuggerTransport()

A transport for the debugging protocol that uses nsIMessageManagers to exchange packets with servers running in child processes.

In the parent process, mm should be the nsIMessageSender for the child process. In a child process, |mm| should be the child process message manager, which sends packets to the parent.

prefix is a string included in the message names, to distinguish multiple servers running in the same child process.

This transport exchanges messages named debug:PREFIX:packet, where PREFIX is prefix, whose data is the protocol packet.

Source:

clearElement()

Clear the text of an element.

Source:

clickElement(commandID, el, pageTimeout)

Send click event to element.

Parameters:
Name Type Description
commandID number

ID of the currently handled message between the driver and listener.
el WebElement

Reference to the web element to click.
pageTimeout number

Timeout in milliseconds the method has to wait for the page being finished loading.
Source:

copyStream(input, output, length) → {Promise}

This helper function (and its companion object) are used by bulk senders and receivers to read and write data in and out of other streams. Functions that make use of this tool are passed to callers when it is time to read or write bulk data. It is highly recommended to use these copier functions instead of the stream directly because the copier enforces the agreed upon length. Since bulk mode reuses an existing stream, the sender and receiver must write and read exactly the agreed upon amount of data, or else the entire transport will be left in a invalid state. Additionally, other methods of stream copying (such as NetUtil.asyncCopy) close the streams involved, which would terminate the debugging transport, and so it is avoided here.

Overall, this works, but clearly the optimal solution would be able to just use the streams directly. If it were possible to fully implement nsIInputStream/nsIOutputStream in JS, wrapper streams could be created to enforce the length and avoid closing, and consumers could use familiar stream utilities like NetUtil.asyncCopy.

The function takes two async streams and copies a precise number of bytes from one to the other. Copying begins immediately, but may complete at some future time depending on data size. Use the returned promise to know when it's complete.

Parameters:
Name Type Description
input nsIAsyncInputStream

Stream to copy from.
output nsIAsyncOutputStream

Stream to copy to.
length number

Amount of data that needs to be copied.
Source:
Returns:

Promise is resolved when copying completes or rejected if any (unexpected) errors occur.

Type
Promise

createATouch()

Function to create a touch based on the element corx and cory are relative to the viewport, id is the touchId

Source:

delimitedRead(stream, delimiter, count) → {string}

Read from a stream, one byte at a time, up to the next delimiter character, but stopping if we've read |count| without finding it. Reading also terminates early if there are less than count bytes available on the stream. In that case, we only read as many bytes as the stream currently has to offer.

Parameters:
Name Type Description
stream nsIInputStream

Input stream to read from.
delimiter string

Character we're trying to find.
count number

Max number of characters to read while searching.
Source:
Returns:

Collected data. If the delimiter was found, this string will end with it.

Type
string

dispatchKeyDown(a, inputState, window) → {Promise}

Dispatch a keyDown action equivalent to pressing a key on a keyboard.

Parameters:
Name Type Description
a action.Action

Action to dispatch.
inputState action.InputState

Input state for this action's input source.
window WindowProxy

Current window global.
Source:
Returns:

Promise to dispatch at least a keydown event, and keypress if appropriate.

Type
Promise

dispatchKeyUp(a, inputState, window) → {Promise}

Dispatch a keyUp action equivalent to releasing a key on a keyboard.

Parameters:
Name Type Description
a action.Action

Action to dispatch.
inputState action.InputState

Input state for this action's input source.
window WindowProxy

Current window global.
Source:
Returns:

Promise to dispatch a keyup event.

Type
Promise

dispatchPause(a, tickDuration) → {Promise}

Dispatch a pause action equivalent waiting for |a.duration| milliseconds, or a default time interval of |tickDuration|.

Parameters:
Name Type Description
a action.Action

Action to dispatch.
tickDuration number

Duration in milliseconds of this tick.
Source:
Returns:

Promise that is resolved after the specified time interval.

Type
Promise

dispatchPointerDown(a, inputState, window) → {Promise}

Dispatch a pointerDown action equivalent to pressing a pointer-device button.

Parameters:
Name Type Description
a action.Action

Action to dispatch.
inputState action.InputState

Input state for this action's input source.
window WindowProxy

Current window global.
Source:
Returns:

Promise to dispatch at least a pointerdown event.

Type
Promise

dispatchPointerMove(a, inputState, window) → {Promise}

Dispatch a pointerMove action equivalent to moving pointer device in a line.

If the action duration is 0, the pointer jumps immediately to the target coordinates. Otherwise, events are synthesized to mimic a pointer travelling in a discontinuous, approximately straight line, with the pointer coordinates being updated around 60 times per second.

Parameters:
Name Type Description
a action.Action

Action to dispatch.
inputState action.InputState

Input state for this action's input source.
window WindowProxy

Current window global.
Source:
Returns:

Promise to dispatch at least one pointermove event, as well as mousemove events as appropriate.

Type
Promise

dispatchPointerUp(a, inputState, window) → {Promise}

Dispatch a pointerUp action equivalent to releasing a pointer-device button.

Parameters:
Name Type Description
a action.Action

Action to dispatch.
inputState action.InputState

Input state for this action's input source.
window WindowProxy

Current window global.
Source:
Returns:

Promise to dispatch at least a pointerup event.

Type
Promise

(async) exitFullscreen(window)

Exit fullscreen and wait for window to resize.

Parameters:
Name Type Description
window ChromeWindow

Window to exit fullscreen.
Source:

Filters all hyperlinks that are descendant of startNode by predicate.

Parameters:
Name Type Description
startNode Element

Where in the DOM hierarchy to begin searching.
predicate function

Function that determines if given link should be included in return value or filtered away.
Source:
Returns:

Iterator of link elements matching predicate.

Type
Iterable.<HTMLAnchorElement>

findElement(strategy, selector, document, startNodeopt) → {Element}

Finds a single element.

Parameters:
Name Type Attributes Description
strategy element.Strategy

Selector strategy to use.
selector string

Selector expression.
document HTMLDocument

Document root.
startNode Element <optional>

Optional node from which to start searching.
Source:
Throws:

  • If strategy using is not recognised.

    Type
    InvalidSelectorError

  • If selector expression selector is malformed.

    Type
    Error
Returns:

Found elements.

Type
Element

(async) findElementContent()

Find an element in the current browsing context's document using the given search strategy.

Source:

findElements(strategy, selector, document, startNodeopt) → {Array.<Element>}

Find multiple elements.

Parameters:
Name Type Attributes Description
strategy element.Strategy

Selector strategy to use.
selector string

Selector expression.
document HTMLDocument

Document root.
startNode Element <optional>

Optional node from which to start searching.
Source:
Throws:

  • If strategy strategy is not recognised.

    Type
    InvalidSelectorError

  • If selector expression selector is malformed.

    Type
    Error
Returns:

Found elements.

Type
Array.<Element>

(async) findElementsContent()

Find elements in the current browsing context's document using the given search strategy.

Source:

get()

Gets the object (not the serialized string) being read or written.

Source:

get()

Navigate to the given URL. The operation will be performed on the current browsing context, which means it handles the case where we navigate within an iframe. All other navigation is handled by the driver (in chrome space).

Source:

getActiveElement() → {WebElement}

Return the active element in the document.

Source:
Throws:

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

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

Get the position and dimensions of the element.

Source:
Returns:

The x, y, width, and height properties of the element.

Type
Object.<string, number>

getElementTagName(id) → {string}

Get the tag name of an element.

Parameters:
Name Type Description
id WebElement

Reference to web element.
Source:
Returns:

Tag name of element.

Type
string

getElementText()

Get the text of this element. This includes text from child elements.

Source:

getElementValueOfCssProperty()

Retrieves the computed value of the given CSS property of the given web element.

Source:

getPageSource()

Get source of the current browsing context's DOM.

Source:

goBack(commandID, pageTimeout)

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

Parameters:
Name Type Description
commandID number

ID of the currently handled message between the driver and listener.
pageTimeout number

Timeout in milliseconds the method has to wait for the page being finished loading.
Source:

goForward(commandID, pageTimeout)

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

Parameters:
Name Type Description
commandID number

ID of the currently handled message between the driver and listener.
pageTimeout number

Timeout in milliseconds the method has to wait for the page being finished loading.
Source:

hex(buffer) → {string}

Convert buffer into to hex.

Parameters:
Name Type Description
buffer ArrayBuffer

The buffer containing the data to convert to hex.
Source:
Returns:

A hex digest of the input buffer.

Type
string

isElementDisplayed()

Determine the element displayedness of the given web element.

Also performs additional accessibility checks if enabled by session capability.

Source:

isElementSelected()

Determines if the referenced element is selected or not.

This operation only makes sense on input elements of the Checkbox- and Radio Button states, or option elements.

Source:

JSONPacket(transport)

With a JSON packet (the typical packet type sent via the transport), data is transferred as a JSON packet serialized into a string, with the string length prepended to the packet, followed by a colon ([length]:[packet]). The contents of the JSON packet are specified in the Remote Debugging Protocol specification.

Parameters:
Name Type Description
transport DebuggerTransport

Transport instance that will own the packet.
Source:

LocalDebuggerTransport(other)

An adapter that handles data transfers between the debugger client and server when they both run in the same process. It presents the same API as DebuggerTransport, but instead of transmitting serialized messages across a connection it merely calls the packet dispatcher of the other side.

Parameters:
Name Type Description
other LocalDebuggerTransport

The other endpoint for this debugger connection.
Source:
See:

multiAction(maxLen)

Start multi-action.

Parameters:
Name Type Description
maxLen Number

Longest action chain for one finger.
Source:

(async) performActions(msg)

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

Parameters:
Name Type Description
msg obj

Object with an |actions| attribute that is an Array of objects each of which represents an action sequence.
Source:

PollPromise(func, timeoutopt, intervalopt) → {Promise.<*>}

Runs a promise-like function off the main thread until it is resolved through resolve or rejected callbacks. The function is guaranteed to be run at least once, irregardless of the timeout.

The func is evaluated every interval for as long as its runtime duration does not exceed interval. Evaluations occur sequentially, meaning that evaluations of func are queued if the runtime evaluation duration of func is greater than interval.

func is given two arguments, resolve and reject, of which one must be called for the evaluation to complete. Calling resolve with an argument indicates that the expected wait condition was met and will return the passed value to the caller. Conversely, calling reject will evaluate func again until the timeout duration has elapsed or func throws. The passed value to reject will also be returned to the caller once the wait has expired.

Usage:


    let els = new PollPromise((resolve, reject) => {
      let res = document.querySelectorAll("p");
      if (res.length > 0) {
        resolve(Array.from(res));
      } else {
        reject([]);
      }
    });

Parameters:
Name Type Attributes Default Description
func Condition

Function to run off the main thread.
timeout number <optional>
 2000

timeout Desired timeout. If 0 or less than the runtime evaluation time of func, func is guaranteed to run at least once. The default is 2000 milliseconds.
interval number <optional>
 10

interval Duration between each poll of func in milliseconds. Defaults to 10 milliseconds.
Source:
Throws:

If func throws, its error is propagated.

Type
*
Returns:

Yields the value passed to func's resolve or reject callbacks.

Type
Promise.<*>

pprint()

Pretty-print values passed to template strings.

Usage:


    const {pprint} = Cu.import("chrome://marionette/content/error.js", {});
    let bool = {value: true};
    pprint`Expected boolean, got ${bool}`;
    => 'Expected boolean, got [object Object] {"value": true}'

    let htmlElement = document.querySelector("input#foo");
    pprint`Expected element ${htmlElement}`;
    => 'Expected element '

    pprint`Current window: ${window}`;
    => '[object Window https://www.mozilla.org/]'
Source:

RawPacket(transport, data)

RawPacket is used to test the transport's error handling of malformed packets, by writing data directly onto the stream.

Parameters:
Name Type Description
transport

DebuggerTransport The transport instance that will own the packet.
data

string The raw string to send out onto the stream.
Source:

refresh(commandID, pageTimeout)

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

Parameters:
Name Type Description
commandID number

ID of the currently handled message between the driver and listener.
pageTimeout number

Timeout in milliseconds the method has to wait for the page being finished loading.
Source:

registerSelf()

Called when listener is first started up. The listener sends its unique window ID and its current URI to the actor. If the actor returns an ID, we start the listeners. Otherwise, nothing happens.

Source:

(async) releaseActions()

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

Source:

ResponseBody()

The response body is exposed as an argument to commands. Commands can set fields on the body through defining properties.

Setting properties invokes a validator that performs tests for mutually exclusionary fields on the input against the existing data in the body.

For example setting the error property on the body when value, sessionId, or capabilities have been set previously will cause an error.

Source:

(async) restoreWindow(chromWindow, contentWindow)

Restore window and wait for the window state to change.

Parameters:
Name Type Description
chromWindow ChromeWindow

Window to restore.
contentWindow WebElementEventTarget

Content window to listen for events in.
Source:

sendError(err, uuid)

Send asynchronous error reply to chrome.

Parameters:
Name Type Description
err Error

Error to notify chrome of.
uuid UUID

Unique identifier of the request.
Source:

sendOk(uuid)

Send asynchronous reply to chrome.

Parameters:
Name Type Description
uuid UUID

Unique identifier of the request.
Source:

sendResponse(obj, uuid)

Send asynchronous reply with value to chrome.

Parameters:
Name Type Description
obj Object

JSON serialisable object of arbitrary type and complexity.
uuid UUID

Unique identifier of the request.
Source:

sendToServer(uuid, type, Objectopt)

Send asynchronous reply to chrome.

Parameters:
Name Type Attributes Description
uuid UUID

Unique identifier of the request.
type AsyncContentSender.ResponseType

Type of response.
Object * <optional>

data JSON serialisable object to accompany the message. Defaults to an empty dictionary.
Source:

set()

Sets the object to be sent when write() is called.

Source:

(async) singleTap()

Function that perform a single tap

Source:

stack()

Create a stacktrace to the current line in the program.

Source:

switchToFrame()

Switch to frame given either the server-assigned element id, its index in window.frames, or the iframe's name or id.

Source:

switchToParentFrame()

Switch to the parent frame of the current frame. If the frame is the top most is the current frame then no action will happen.

Source:

switchToShadowRoot()

Switch the current context to the specified host's Shadow DOM.

Source:

takeScreenshot(idopt, fullopt, highlightsopt, scrollopt, format, opts) → {string}

Perform a screen capture in content context.

Accepted values for |opts|:

Parameters:
Name Type Attributes Description
id UUID <optional>

Optional web element reference of an element to take a screenshot of.
full boolean <optional>

True to take a screenshot of the entire document element. Is not considered if {@code id} is not defined. Defaults to true.
highlights Array.<UUID> <optional>

Draw a border around the elements found by their web element references.
scroll boolean <optional>

When |id| is given, scroll it into view before taking the screenshot. Defaults to true.
format capture.Format

Format to return the screenshot in.
opts Object.<string, ?>

Options.
Source:
Returns:

Base64 encoded string or a SHA-256 hash of the screenshot.

Type
string

TimedPromise(func, timeoutopt, throwsopt) → {Promise.<*>}

The TimedPromise object represents the timed, eventual completion (or failure) of an asynchronous operation, and its resulting value.

In contrast to a regular Promise, it times out after timeout.

Parameters:
Name Type Attributes Default Description
func Condition

Function to run, which will have its reject callback invoked after the timeout duration is reached. It is given two callbacks: resolve(value) and reject(error).
timeout timeout <optional>
 1500

timeout condition's reject callback will be called after this timeout.
throws Error <optional>
 TimeoutError

throws When the timeout is hit, this error class will be thrown. If it is null, no error is thrown and the promise is instead resolved on timeout.
Source:
Returns:

Timed promise.

Type
Promise.<*>

toEvents(tickDuration, window) → {function}

Create a closure to use as a map from action definitions to Promise events.

Parameters:
Name Type Description
tickDuration number

Duration in milliseconds of this tick.
window WindowProxy

Current window global.
Source:
Returns:

Function that takes an action and returns a Promise for dispatching the event that corresponds to that action.

Type
function

truncate()

Template literal that truncates string values in arbitrary objects.

Given any object, the template will walk the object and truncate any strings it comes across to a reasonable limit. This is suitable when you have arbitrary data and data integrity is not important.

The strings are truncated in the middle so that the beginning and the end is preserved. This will make a long, truncated string look like "X <...> Y", where X and Y are half the number of characters of the maximum string length from either side of the string.

Usage:


    truncate`Hello ${"x".repeat(260)}!`;
    // Hello xxx ... xxx!

Functions named toJSON or toString on objects will be called.

Source:

waitForPageLoaded(commandID, pageTimeout, startTime)

This implements the latter part of a get request (for the case we need to resume one when the frame script has been reloaded in the middle of a navigate request). This is most of of the work of a navigate request, but doesn't assume DOMContentLoaded is yet to fire.

Parameters:
Name Type Description
commandID number

ID of the currently handled message between the driver and listener.
pageTimeout number

Timeout in seconds the method has to wait for the page being finished loading.
startTime number

Unix timestap when the navitation request got triggred.
Source:

whenIdle(window, callback) → {function}

Throttle callback until the main thread is idle and window has performed an animation frame.

Parameters:
Name Type Description
window ChromeWindow

Window to request the animation frame from.
callback function

Called when done.
Source:
Returns:

Anonymous function that when invoked will wait for the main thread to clear up and request an animation frame before calling callback.

Type
function

Type Definitions

Condition(resolve, reject) → {*}

Parameters:
Name Type Description
resolve function

To be called when the condition has been met. Will return the resolved value.
reject function

To be called when the condition has not been met. Will cause the condition to be revaluated or time out.
Source:
Returns:

The value from calling resolve.

Type
*

ResponseCallback(resp)

Parameters:
Name Type Description
resp Response

Response to handle.
Source: