Bug 1350887 - Add general overview documentation to Marionette; r=whimboo
MozReview-Commit-ID: HwMOQVxwIDN
new file mode 100644
--- /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