message module

Command

class Command(messageID, name, params)

A command is a request from the client to run a series of remote end steps and return a fitting response.

The command can be synthesised from the message passed over the Marionette socket using the {@link fromPacket} function. The format of a message is:

<pre>
[<var>type</var>, <var>id</var>, <var>name</var>, <var>params</var>]

</pre>

where

<dl>

<dt><var>type</var> (integer) <dd>

Must be zero (integer). Zero means that this message is a command.

<dt><var>id</var> (integer) <dd>

Integer used as a sequence number. The server replies with the same ID for the response.

<dt><var>name</var> (string) <dd>

String representing the command name with an associated set of remote end steps.

<dt><var>params</var> (JSON Object or null) <dd>

Object of command function arguments. The keys of this object must be strings, but the values can be arbitrary values.

</dl>

A command has an associated message <var>id</var> that prevents the dispatcher from sending responses in the wrong order.

The command may also have optional error- and result handlers that are called when the client returns with a response. These are <code>function onerror({Object})</code>, <code>function onresult({Object})</code>, and <code>function onresult({Response})</code>:

Arguments:
  • messageID (number) – Message ID unique identifying this message.
  • name (string) – Command name.
  • ?> params (Object.<string,) – Command parameters.
Command.fromPacket(payload)

Converts a data packet into {@link Command}.

Arguments:
  • number, ?, ?> data (Array.<number,) – A four element array where the elements, in sequence, signifies message type, message ID, command name, and parameters.
Throws:

TypeError – If the message type is not recognised.

Returns:

Command – Representation of packet.

Command.onresponse(resp)

Calls the error- or result handler associated with this command. This function can be replaced with a custom response handler.

Arguments:
  • resp (Response) – The response to pass on to the result or error to the <code>onerror</code> or <code>onresult</code> handlers to.
Command.toPacket()

Encodes the command to a packet.

Returns:Array – Packet.

Message

class Message(messageID)

Representation of the packets transproted over the wire.

Arguments:
  • messageID (number) – Message ID unique identifying this message.
Message.Origin

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.

Message.fromPacket(data)

Converts a data packet into a {@link Command} or {@link Response}.

Arguments:
  • number, ?, ?> data (Array.<number,) – A four element array where the elements, in sequence, signifies message type, message ID, method name or error, and parameters or result.
Throws:

TypeError – If the message type is not recognised.

Returns:

Message – Based on the message type, a {@link Command} or {@link Response} instance.

Response

class Response(messageID, respHandler)

Represents the response returned from the remote end after execution of its corresponding command.

The response is a mutable object passed to each command for modification through the available setters. To send data in a response, you modify the body property on the response. The body property can also be replaced completely.

The response is sent implicitly by {@link server.TCPConnection#execute when a command has finished executing, and any modifications made subsequent to that will have no effect.

Arguments:
  • messageID (number) – Message ID tied to the corresponding command request this is a response for.
  • respHandler (ResponseHandler) – Function callback called on sending the response.
Response.fromPacket(payload)

Converts a data packet into {@link Response}.

Arguments:
  • number, ?, ?> data (Array.<number,) – A four element array where the elements, in sequence, signifies message type, message ID, error, and result.
Throws:

TypeError – If the message type is not recognised.

Returns:

Response – Representation of packet.

Response.send()

Sends response using the response handler provided on construction.

Throws:RangeError – If the response has already been sent.
Response.sendConditionally(predicate)

Sends response conditionally, given a predicate.

Arguments:
  • predicate (function) – A predicate taking a Response object and returning a boolean.
Response.sendError(err)

Send error to client.

Turns the response into an error response, clears any previously set body data, and sends it using the response handler provided on construction.

Arguments:
  • err (Error) – The Error instance to send.
Throws:

Error – If <var>err</var> is not a {@link WebDriverError}, the error is propagated, i.e. rethrown.

Response.toPacket()

Encodes the response to a packet.

Returns:Array – Packet.