gecko-dev/testing/marionette
Andreas Tolfsen 545d5ec9f4 Bug 1275273 - Make WebDriver:IsElementSelected conform to spec. r=maja_zf
Splits interaction.isElementSelected into two parts: one checking
whether the element DOM properties are selected/checked, and the
other checking accessibility.  This so this so that the selectedness
can be unit tested, as we do not have the capability of standing
up accessibility in the xpcshell tests.

The second part of this change moves us away from atom.isElementSelected
in favour of a specification conforming implementation in Marionette.
This is a word-by-word implementation of the Is Element Selected
command from WebDriver.

MozReview-Commit-ID: 93WDKbPcEIB
2017-10-11 15:24:03 +01:00
..
chrome
client Bug 1350897 - Tested quit shutdown/restart cause in Marionette Python client. r=whimboo 2017-10-03 10:48:30 +05:30
components Bug 1405279 - Remove unused variables. r=whimboo 2017-10-03 14:35:47 +01:00
doc Bug 1375660 - Add instructions for updating the Selenium atoms. r=ato 2017-10-05 12:10:57 +02:00
harness Bug 1375660 - Remove duplicate button 9 reference in test_accessibility. r=ato 2017-10-02 23:58:01 +02:00
prefs
puppeteer Bug 1364349 - Removed platform property of Firefox Puppeteer. r=whimboo 2017-09-25 14:30:11 +05:30
.eslintrc.js Bug 1405279 - Lint for unused variables. r=whimboo 2017-10-03 14:36:09 +01:00
.jsdoc.js Bug 1405757 - Generate Marionette API docs to testing/marionette/doc/api. r=me 2017-10-04 18:35:12 +01:00
accessibility.js Bug 1405279 - Remove unused variables. r=whimboo 2017-10-03 14:35:47 +01:00
action.js Bug 1405018 - Consider current browsing context on staleness check. r=whimboo 2017-10-10 15:06:21 +01:00
addon.js Bug 1405279 - Remove unused variables. r=whimboo 2017-10-03 14:35:47 +01:00
assert.js Bug 1405279 - Remove unused variables. r=whimboo 2017-10-03 14:35:47 +01:00
atom.js Bug 1275273 - Remove isElementSelected atom. r=maja_zf 2017-10-11 15:24:03 +01:00
browser.js Bug 1405279 - Remove unused variables. r=whimboo 2017-10-03 14:35:47 +01:00
capture.js
cert.js Bug 1405279 - Remove unused variables. r=whimboo 2017-10-03 14:35:47 +01:00
cookie.js Bug 1402978 - Add cookie domain field to WebDriver:AddCookie r=ato 2017-09-29 15:22:50 +01:00
dom.js Bug 1405279 - Remove unused variables. r=whimboo 2017-10-03 14:35:47 +01:00
driver.js Bug 1405325 - Align WebDriver:DeleteCookie with specification. r=maja_zf 2017-10-03 16:25:57 +01:00
element.js Bug 1275273 - Make WebDriver:IsElementSelected conform to spec. r=maja_zf 2017-10-11 15:24:03 +01:00
error.js
evaluate.js Bug 1405018 - Consider current browsing context on staleness check. r=whimboo 2017-10-10 15:06:21 +01:00
event.js Bug 1405279 - Remove unused variables. r=whimboo 2017-10-03 14:35:47 +01:00
frame.js
interaction.js Bug 1275273 - Make WebDriver:IsElementSelected conform to spec. r=maja_zf 2017-10-11 15:24:03 +01:00
jar.mn Bug 1404946 - Rename wait module to sync. r=whimboo 2017-10-02 16:38:33 +01:00
l10n.js Bug 1405279 - Remove unused variables. r=whimboo 2017-10-03 14:35:47 +01:00
legacyaction.js
listener.js Bug 1405018 - Consider current browsing context on staleness check. r=whimboo 2017-10-10 15:06:21 +01:00
mach_commands.py
mach_test_package_commands.py
message.js Bug 1405279 - Remove unused variables. r=whimboo 2017-10-03 14:35:47 +01:00
modal.js
moz.build Backed out changeset ddfc127526b2 (bug 1403222) for failing python/mozbuild/mozbuild/test/frontend/test_reader.py::TestBuildReader::test_schedules, at least for Linux asan opt builds. r=backout on a CLOSED TREE 2017-10-02 16:03:12 +02:00
navigate.js Bug 1406150 - Always throw exceptions by using 'new'. r=maja_zf 2017-10-06 14:07:13 +02:00
packets.js Bug 1406150 - Always throw exceptions by using 'new'. r=maja_zf 2017-10-06 14:07:13 +02:00
proxy.js
README.html
reftest.js Bug 1405279 - Remove unused variables. r=whimboo 2017-10-03 14:35:47 +01:00
reftest.xul
server.js Bug 1405279 - Remove unused variables. r=whimboo 2017-10-03 14:35:47 +01:00
session.js Bug 1405279 - Remove unused variables. r=whimboo 2017-10-03 14:35:47 +01:00
stream-utils.js Bug 1405279 - Remove unused variables. r=whimboo 2017-10-03 14:35:47 +01:00
sync.js Bug 1404946 - Have PollPromise accept an options dictionary. r=whimboo 2017-10-02 17:13:57 +01:00
test_action.js
test_assert.js
test_cookie.js Bug 1405240 - Fix test_cookie.js unit test assertions r=ato 2017-10-03 16:28:17 +01:00
test_dom.js Bug 1400225 - Subscribe to and relay web content DOM events. r=automatedtester,whimboo 2017-09-15 17:07:41 +01:00
test_element.js Bug 1275273 - Make WebDriver:IsElementSelected conform to spec. r=maja_zf 2017-10-11 15:24:03 +01:00
test_error.js
test_message.js
test_navigate.js
test_session.js
test_sync.js Bug 1404946 - Have PollPromise accept an options dictionary. r=whimboo 2017-10-02 17:13:57 +01:00
transport.js Bug 1405279 - Remove unused variables. r=whimboo 2017-10-03 14:35:47 +01:00
unit.ini Bug 1404946 - Rename wait module to sync. r=whimboo 2017-10-02 16:38:33 +01:00

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<h1>Marionette</h1>

<p>Marionette is the remote protocol that lets OOP programs
 communicate with, instrument, and control Gecko.


<h2>Description</h2>

<p>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.


<h2>Usage</h2>

<p>Marionette can be activated by passing the -marionette flag.
 To start Firefox with the remote protocol turned on:

<pre>
% firefox -marionette
…
1491228343089	Marionette	INFO	Listening on port 2828
</pre>

<p>This binds to a TCP socket, over which <a href=#clients>clients</a>
 can communicate with Marionette using the <a href=#protocol>protocol</a>.


<h2 id=protocol>Protocol</h2>

<p>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.

<p>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 <a href=https://bugzil.la/1207125>mixing up responses</a>.

<p>Schematic flow of messages:

<pre>
               client      server
                 |            |
      msgid=1    |----------->|
                 |  command   |
                 |            |
      msgid=2    |<-----------|
                 |  command   |
                 |            |
      msgid=2    |----------->|
                 |  response  |
                 |            |
      msgid=1    |<-----------|
                 |  response  |
                 |            |
</pre>

<p>The protocol consists of a <a href=#command>command</a> message
 and the corresponding <a href=#response>response</a> message.
 A <a href=#response>response</a> message must always be sent
 in reply to a <a href=#command>command</a> message.

<p>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.

<p>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.


<h2 id=command>Command</h2>

<p>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:

<pre>[type, message ID, command, parameters]</pre>

<dl>
 <dt>type
 <dd><p>Must be 0 (integer).
  This indicates that the message
  is the <a href=#command>command</a> message.

 <dt>message ID
 <dd><p>A 32-bit unsigned integer.
  This number is used as sequencing number
  that uniquely identifies a pair of <a href=#command>command</a>
  and <a href=#response>response</a> messages.
  The other remote part will reply
  with a corresponding <a href=#response>response</a>
  with the same message ID.

 <dt>command
 <dd><p>A string identifying the RPC method or command to execute.

 <dt>parameters
 <dd><p>An arbitrary JSON serialisable object.
</dl>

<h2 id=response>Response</h2>

<p>The response message is also a four element array as shown below,
 and must always be sent after receiving a <a href=#command>command</a>:

<pre>[type, message ID, error, result]</pre>

<dl>
 <dt>type
 <dd><p>Must be 1 (integer).
  This indicates that the message is
  the <a href=#response>response</a> message.

 <dt>message ID
 <dd><p>A 32-bit unsigned integer.
  This corresponds to the <a href=#command>command</a> messages
  message ID.

 <dt>error
 <dd><p>If the command executed correctly, this field is null.
  If the error occurred on the server-side,
  then this field is an <a href=#error>error</a> object.

 <dt>result
 <dd><p>The result object associated with the <a href=#command>command</a>,
  if it executed correctly.
  If an error occurred on the server-side, this field is null.

  <p>The structure of the result entry can vary,
   but is documented individually for each command.
</dl>


<h3 id=error>Error object</h3>

<p>An error object is a serialisation of JavaScript error types,
 and is structured like this:

<pre>
{
	"error": "invalid session id",
	"message": "No active session with ID 1234",
	"stacktrace": ""
}
</pre>

<p>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 <a href=https://w3c.github.io/webdriver/webdriver-spec.html#handling-errors>WebDriver standard</a>.


<h2 id=clients>Clients</h2>

<p>Clients may be implemented in any language
 that is capable of writing and receiving data over TCP socket.
 A <a href=https://searchfox.org/mozilla-central/source/testing/marionette/client>reference client is provided</a>.
 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.


<h2 id=bugs>Bugs</h2>

<p>Bugs are tracked
 in various <a href=https://bugzilla.mozilla.org/>Bugzilla</a> components:

<dl>
 <dt>Marionette server
 <dt>Marionette reference client
 <dt>Marionette test harness
 <dd><a href="https://bugzilla.mozilla.org/buglist.cgi?product=Testing&component=Marionette">Testing :: Marionette</a>

 <dt>geckodriver
 <dd><a href="https://bugzilla.mozilla.org/buglist.cgi?product=Testing&component=geckodriver">Testing :: geckodriver</a>
</dl>