remote/doc/marionette/Intro.md

   1 # Introduction to Marionette
   2
   3 Marionette is an automation driver for Mozilla's Gecko engine.
   4 It can remotely control either the UI or the internal JavaScript of
   5 a Gecko platform, such as Firefox.  It can control both the chrome
   6 (i.e. menus and functions) or the content (the webpage loaded inside
   7 the browsing context), giving a high level of control and ability
   8 to replicate user actions. In addition to performing actions on the
   9 browser, Marionette can also read the properties and attributes of
  10 the DOM.
  11
  12 If this sounds similar to [Selenium/WebDriver] then you're
  13 correct! Marionette shares much of the same ethos and API as
  14 Selenium/WebDriver, with additional commands to interact with
  15 Gecko's chrome interface.  Its goal is to replicate what Selenium
  16 does for web content: to enable the tester to have the ability to
  17 send commands to remotely control a user agent.
  18
  19 [Selenium/WebDriver]: https://dvcs.w3.org/hg/webdriver/raw-file/tip/webdriver-spec.html
  20
  21 ## How does it work?
  22
  23 Marionette consists of two parts: a server which takes requests and
  24 executes them in Gecko, and a client.  The client sends commands to
  25 the server and the server executes the command inside the browser.
  26
  27 ## When would I use it?
  28
  29 If you want to perform UI tests with browser chrome or content,
  30 Marionette is the tool you're looking for!  You can use it to
  31 control either web content, or Firefox itself.
  32
  33 A test engineer would typically import the Marionette client package
  34 into their test framework, import the classes and use the class
  35 functions and methods to control the browser.  After controlling
  36 the browser, Marionette can be used to return information about
  37 the state of the browser which can then be used to validate that
  38 the action was performed correctly.
  39
  40 ## Using Marionette
  41
  42 Marionette combines a gecko component (the Marionette server) with an
  43 outside component (the Marionette client), which drives the tests.
  44 The Marionette server ships with Firefox, and to use it you will
  45 need to download a Marionette client or use the in-tree client.
  46
  47 * [Download and setup the Python client for Marionette][1]
  48 * [Run Tests with Python][2] – How to run tests using the
  49   Python client
  50 * You might want to experiment with [using Marionette interactively
  51   at a Python command prompt][2]
  52 * Start [writing and running][3] tests
  53 * Tips on [debugging][4] Marionette code
  54 * [Download and setup the Marionette JS client][5]
  55 * [Protocol definition][6]
  56
  57 [1]: /python/marionette_driver.rst
  58 [2]: /python/marionette_driver.rst
  59 [3]: PythonTests.md
  60 [4]: Debugging.md
  61 [5]: https://github.com/mozilla-b2g/marionette_js_client
  62 [6]: Protocol.md
  63
  64 ## Bugs
  65
  66 Please file any bugs you may find in the `Testing :: Marionette`
  67 component in Bugzilla.  You can view a [list of current bugs]
  68 to see if your problem is already being addressed.
  69
  70 [list of current bugs]: https://bugzilla.mozilla.org/buglist.cgi?product=Testing&component=Marionette