Global

Members

(constant) CHECKED_PROPERTY_SUPPORTED_XUL

XUL elements that support checked property.

Source:

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

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

Messages may originate from either the server or the client. Because the remote protocol is full duplex, both endpoints may be the origin of both commands and responses.

Properties:
Name Type Description
Client

Indicates that the message originates from the client.

Server

Indicates that the message originates from the server.

Source:
See:

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

XUL elements that support selected property.

Source:

Methods

actionChain()

Start action chain on one finger.

Source:

addMessageListenerId()

Add a message listener that's tied to our listenerId.

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(command_id, id, pageTimeout)

Send click event to element.

Parameters:
Name Type Description
command_id number

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

id 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:

deleteSession()

Removes all listeners

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, win) → {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.

win nsIDOMWindow

Current window.

Source:
Returns:

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

Type
Promise

dispatchKeyUp(a, inputState, win) → {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.

win nsIDOMWindow

Current window.

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, win) → {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.

win nsIDOMWindow

Current window.

Source:
Returns:

Promise to dispatch at least a pointerdown event.

Type
Promise

dispatchPointerMove(a, inputState, seenEls, container) → {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.

seenEls element.Store

Element store.

container Object.<string, nsIDOMWindow>

Object with frame property of type nsIDOMWindow.

Source:
Returns:

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

Type
Promise

dispatchPointerUp(a, inputState, win) → {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.

win nsIDOMWindow

Current window.

Source:
Returns:

Promise to dispatch at least a pointerup event.

Type
Promise

Filters all hyperlinks that are descendant of |node| by |predicate|.

Parameters:
Name Type Description
node DOMElement

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:

Sequence of link elements matching |predicate|.

Type
Array.<DOMAnchorElement>

findElement(using, value, rootNode, startNodeopt) → {DOMElement}

Finds a single element.

Parameters:
Name Type Attributes Description
using element.Strategy

Selector strategy to use.

value string

Selector expression.

rootNode DOMElement

Document root.

startNode DOMElement <optional>

Optional node from which to start searching.

Source:
Throws:
  • If strategy |using| is not recognised.

    Type
    InvalidSelectorError
  • If selector expression |value| is malformed.

    Type
    Error
Returns:

Found elements.

Type
DOMElement

(generator) findElementContent()

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

Source:

findElements(using, value, rootNode, startNodeopt) → {DOMElement}

Find multiple elements.

Parameters:
Name Type Attributes Description
using element.Strategy

Selector strategy to use.

value string

Selector expression.

rootNode DOMElement

Document root.

startNode DOMElement <optional>

Optional node from which to start searching.

Source:
Throws:
  • If strategy |using| is not recognised.

    Type
    InvalidSelectorError
  • If selector expression |value| is malformed.

    Type
    Error
Returns:

Found elements.

Type
DOMElement

(generator) findElementsContent()

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

Source:

focusElement(element)

Focus element and, if a textual input field and no previous selection state exists, move the caret to the end of the input field.

Parameters:
Name Type Description
element Element

Element to focus.

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:

get()

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

Source:

getActiveElement()

Find and return the active element on the page.

Source:

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

Get the position and dimensions of the element.

Parameters:
Name Type Description
id WebElement

Reference to web 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(id) → {string}

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

Parameters:
Name Type Description
id WebElement

Reference to web element.

Source:
Returns:

Text of element.

Type
string

getElementValueOfCssProperty(id, prop) → {String}

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

Parameters:
Name Type Description
id String

Web element reference.

prop String

The CSS property to get.

Source:
Returns:

Effective value of the requested CSS property.

Type
String

getOuterWindowId(win) → {string}

Get the outer window ID for the specified window.

Parameters:
Name Type Description
win nsIDOMWindow

Window whose browser we need to access.

Source:
Returns:

Returns the unique window ID.

Type
string

getPageSource()

Get source of the current browsing context's DOM.

Source:

goBack(command_id, pageTimeout)

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

Parameters:
Name Type Description
command_id 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(command_id, pageTimeout)

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

Parameters:
Name Type Description
command_id 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:

isElementEnabled(id) → {boolean}

Check if element is enabled.

Parameters:
Name Type Description
id WebElement

Reference to web element.

Source:
Returns:

True if enabled, false otherwise.

Type
boolean

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:

newSession()

Called when we start a new session. It registers the current environment, and resets all values

Source:

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

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(command_id, pageTimeout)

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

Parameters:
Name Type Description
command_id 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:

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

removeMessageListenerId()

Remove a message listener that's tied to our listenerId.

Source:

resetValues()

Clear test values after completion of test

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 {@code error} property on the body when {@code value}, {@code sessionId}, or {@code capabilities} have been set previously will cause an error.

Source:

restart()

Restarts all our listeners after this listener was put to sleep

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:

singleTap()

Function that perform a single tap

Source:

sleepSession()

Puts the current session to sleep, so all listeners are removed except for the 'restart' listener.

Source:

startListeners()

Start all message listeners

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

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

Parameters:
Name Type Description
id WebElement

Reference to web element.

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

toEvents(tickDuration, seenEls, container) → {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.

seenEls element.Store

Element store.

container Object.<string, nsIDOMWindow>

Object with frame property of type nsIDOMWindow.

Source:
Returns:

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

Type
function

waitForPageLoaded(command_id, 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
command_id 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:

Type Definitions

ResponseCallback(resp)

Parameters:
Name Type Description
resp Response

Response to handle.

Source:

WaitCondition(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
*