From ceccc2692a21e39fb7b6579aa4d370fef3ec2a11 Mon Sep 17 00:00:00 2001 From: Andreas Tolfsen Date: Mon, 3 Apr 2017 15:00:05 +0100 Subject: [PATCH] Bug 1350887 - Add general overview documentation to Marionette; r=whimboo MozReview-Commit-ID: HwMOQVxwIDN --HG-- extra : rebase_source : 39e98771948eb7baa8df3a68fc1023c573964374 --- testing/marionette/README | 174 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 testing/marionette/README diff --git a/testing/marionette/README b/testing/marionette/README new file mode 100644 index 000000000000..72247188e63b --- /dev/null +++ b/testing/marionette/README @@ -0,0 +1,174 @@ +MARIONETTE + + Marionette is the remote protocol that lets OOP programs communicate + with, instrument, and control Gecko. + +DESCRIPTION + + Marionette is an automation driver for Mozilla’s Gecko engine. + It can remotely control either the UI or the internal JavaScript of + the Gecko platform, such as Firefox. It can control both the chrome + and the content document, giving a high level of control and ability to + replicate user interaction. In addition to performing actions on the + browser, Marionette can also read properties and attributes of the DOM. + +USAGE + + It is included in Firefox, but not enabled by default unless the + --marionette flag is passed or the marionette.enabled preference is + set to true. + + To start Firefox with the remote protocol turned on: + + % firefox --marionette + … + 1491228343089 Marionette INFO Listening on port 2828 + + This binds to a TCP socket, over which CLIENTS can communicate with + Marionette using the PROTOCOL. + +PROTOCOL + + Marionette provides an asynchronous, parallel pipelining user-facing + interface. Message sequencing limits chances of payload race conditions + and provides a uniform way in which payloads are serialised. + + Clients that deliver a blocking WebDriver interface are still expected + to not send further command requests before the response from the last + command has come back, but if they still happen to do so because of + programming error, no harm will be done. This guards against bugs + such as https://bugzil.la/1207125. + + Schematic flow of messages: + + client server + | | + msgid=1 |----------->| + | command | + | | + msgid=2 |<-----------| + | command | + | | + msgid=2 |----------->| + | response | + | | + msgid=1 |<-----------| + | response | + | | + + The protocol consists of a COMMAND message and the corresponding + RESPONSE message. A RESPONSE message must always be sent in reply to + a COMMAND message. + + This means that the server implementation does not need to send the + reply precisely in the order of the received commands: if it receives + multiple messages, the server may even reply in random order. It is + therefore strongly adviced that clients take this into account when + implementing the client end of this wire protocol. + + This is required for pipelining messages. On the server side, some + functions are fast, and some less so. If the server must reply in + order, the slow functions delay the other replies even if its execution + is already completed. + +COMMAND + + The request, or command message, is a four element JSON array as shown + below, that may originate from either the client- or server remote ends: + + [type, message ID, command, parameters] + + type + Must be 0 (integer). This indicates that the message is the + COMMAND message. + + message ID + A 32-bit unsigned integer. This number is used as sequencing number + that uniquely identifies a pair of COMMAND and RESPONSE messages. + The other remote part will reply with a corresponding RESPONSE with + the same message ID. + + command + A string identifying the RPC method or command to execute. + + parameters + An arbitrary JSON serialisable object. + +RESPONSE + + The response message is also a four element array as shown below, + and must always be sent after receiving a COMMAND: + + [type, message ID, error, result] + + type + Must be 1 (integer). This indicates that the message is the RESPONSE + message. + + message ID + A 32-bit unsigned integer. This corresponds to the COMMAND + message’s message ID. + + error + If the command executed correctly, this field is null. If the error + occurre on the server-side, then this field is an ERROR object. + + result + The result object associated with the COMMAND, if it executed + correctly. If an error occurred on the server-side, this field + is null. + + The structure of the result entry can vary, but is documented + individually for each command in ./driver.js. + +ERROR OBJECTS + + An ERROR object is a serialisation of JavaScript error types, and is + structured like this: + + { + "error": "invalid session id", + "message": "No active session with ID 1234", + "stacktrace": "" + } + + All the fields of the error object are required, so the stacktrace and + message fields may be empty strings. The error field is on the other + hand guaranteed to be one of the JSON error codes as laid out by the + WebDriver standard: + + https://w3c.github.io/webdriver/webdriver-spec.html#handling-errors + +CLIENTS + + Clients may be implemented in any language that is capable of writing + and receiving data over TCP socket. A reference client is provided in + tree (under ./client). Clients may be implemented both synchronously + and asynchronously, although the latter is impossible in protocol + levels 2 and earlier due to the lack of message indexing. + +DOCUMENTATION + + General introduction: + + https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette + + Protocol definition: + + https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/Protocol + + Generated Python client API documentation: + + https://marionette-client.readthedocs.org/ + +BUGS + + Server and Python client bugs are tracked in the Testing :: Marionette + component in Bugzilla: + + https://bugzilla.mozilla.org/buglist.cgi?product=Testing&component=Marionette + + geckodriver (found in ../geckodriver), the HTTP proxy for using W3C + WebDriver-compatible clients with Marionette, tracks its bugs on GitHub: + + https://github.com/mozilla/geckodriver/issues