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

MozReview-Commit-ID: HwMOQVxwIDN

--HG--
extra : rebase_source : ee1321347ce4af5960afcab0e083d510ad296adf
This commit is contained in:
Andreas Tolfsen 2017-04-03 15:00:05 +01:00
Родитель 90caadb8dd
Коммит 068598e0e5
1 изменённых файлов: 174 добавлений и 0 удалений

174
testing/marionette/README Normal file
Просмотреть файл

@ -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 Mozillas 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
messages 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