Bug 1350887 - Add general overview documentation to Marionette; r=whimboo

MozReview-Commit-ID: HwMOQVxwIDN

--HG--
extra : rebase_source : 39e98771948eb7baa8df3a68fc1023c573964374

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