remote/doc/marionette/Testing.md

   1 # Testing
   2
   3 We verify and test Marionette in a couple of different ways, using
   4 a combination of unit tests and functional tests.  There are three
   5 distinct components that we test:
   6
   7 - the Marionette **server**, using a combination of xpcshell
   8 unit tests and functional tests written in Python spread across
   9 Marionette- and WPT tests;
  10
  11 - the Python **client** is tested with the same body of functional
  12 Marionette tests;
  13
  14 - and the **harness** that backs the Marionette, or `Mn` job on
  15 try, tests is verified using separate mock-styled unit tests.
  16
  17 All these tests can be run by using [mach].
  18
  19 [mach]: https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/mach
  20
  21 ## xpcshell unit tests
  22
  23 Marionette has a set of [xpcshell] unit tests located in
  24 _remote/marionette/test/xpcshell.  These can be run this way:
  25
  26     % ./mach test remote/marionette/test/unit
  27
  28 Because tests are run in parallel and xpcshell itself is quite
  29 chatty, it can sometimes be useful to run the tests sequentially:
  30
  31     % ./mach test --sequential remote/marionette/test/xpcshell/test_error.js
  32
  33 These unit tests run as part of the `X` jobs on Treeherder.
  34
  35 [xpcshell]: https://developer.mozilla.org/en-US/docs/Mozilla/QA/Writing_xpcshell-based_unit_tests
  36
  37 ## Marionette functional tests
  38
  39 We also have a set of [functional tests] that make use of the Marionette
  40 Python client.  These start a Firefox process and tests the Marionette
  41 protocol input and output, and will appear as `Mn` on Treeherder.
  42 The following command will run all tests locally:
  43
  44     % ./mach marionette-test
  45
  46 But you can also run individual tests:
  47
  48     % ./mach marionette-test testing/marionette/harness/marionette_harness/tests/unit/test_navigation.py
  49
  50 In case you want to run the tests with another binary like [Firefox Nightly]:
  51
  52     % ./mach marionette-test --binary /path/to/nightly/firefox TEST
  53
  54 When working on Marionette it is often useful to surface the stdout
  55 from Gecko, which can be achieved using the `--gecko-log` option.
  56 See [Debugging](Debugging.md) for usage instructions, but the gist is that
  57 you can redirect all Gecko output to stdout:
  58
  59     % ./mach marionette-test --gecko-log - TEST
  60
  61 Our functional integration tests pop up Firefox windows sporadically,
  62 and a helpful tip is to suppress the window can be to use Firefox’
  63 headless mode:
  64
  65     % ./mach marionette-test -z TEST
  66
  67 `-z` is an alias for the `--headless` flag and equivalent to setting
  68 the `MOZ_HEADLESS` output variable.  In addition to `MOZ_HEADLESS`
  69 there is also `MOZ_HEADLESS_WIDTH` and `MOZ_HEADLESS_HEIGHT` for
  70 controlling the dimensions of the no-op virtual display.  This is
  71 similar to using Xvfb(1) which you may know from the X windowing system,
  72 but has the additional benefit of also working on macOS and Windows.
  73
  74 [functional tests]: PythonTests.md
  75 [Firefox Nightly]: https://nightly.mozilla.org/
  76
  77 ### Android
  78
  79 Prerequisites:
  80
  81 - You have [built Fennec](https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Simple_Firefox_for_Android_build).
  82 - You can run an Android [emulator](https://wiki.mozilla.org/Mobile/Fennec/Android/Testing#Running_tests_on_the_Android_emulator),
  83     which means you have the AVD you need.
  84
  85 When running tests on Fennec, you can have Marionette runner take care of
  86 starting Fennec and an emulator, as shown below.
  87
  88     % ./mach marionette-test --emulator --app fennec
  89       --avd-home /path/to/.mozbuild/android-device/avd
  90       --emulator-binary /path/to/.mozbuild/android-sdk/emulator/emulator
  91       --avd=mozemulator-x86
  92
  93 For Fennec tests, if the appropriate `emulator` command is in your `PATH`, you may omit the `--emulator-binary` argument.  See `./mach marionette-test -h`
  94 for additional options.
  95
  96 Alternately, you can start an emulator yourself and have the Marionette runner
  97 start Fennec for you:
  98
  99     % ./mach marionette-test --emulator --app='fennec' --address=127.0.0.1:2828
 100
 101 To connect to an already-running Fennec in an emulator or on a device,
 102 you will need to have it started with the `-marionette` command line argument,
 103 or by setting the environment variable `MOZ_MARIONETTE=1` for the process.
 104
 105 Make sure port 2828 is forwarded:
 106
 107     % adb forward tcp:2828 tcp:2828
 108
 109 If Fennec is already started:
 110
 111     % ./mach marionette-test --app='fennec' --address=127.0.0.1:2828
 112
 113 If Fennec is not already started on the emulator/device, add the `--emulator`
 114 option. Marionette Test Runner will take care of forwarding the port and
 115 starting Fennec with the correct prefs. (You may need to run
 116 `adb forward --remove-all` to allow the runner to start.)
 117
 118     % ./mach marionette-test --emulator --app='fennec' --address=127.0.0.1:2828 --startup-timeout=300
 119
 120 If you need to troubleshoot the Marionette connection, the most basic check is
 121 to start Fennec with `-marionette` or the environment variable `MOZ_MARIONETTE=1`,
 122 make sure that the port 2828 is forwarded, and then see if you get any response from
 123 Marionette when you connect manually:
 124
 125     % telnet 127.0.0.1:2828
 126
 127 You should see output like `{"applicationType":"gecko","marionetteProtocol":3}`
 128
 129 [geckodriver]: /testing/geckodriver/index.rst
 130
 131 ## WPT functional tests
 132
 133 Marionette is also indirectly tested through [geckodriver] with WPT
 134 (`Wd` on Treeherder).  To run them:
 135
 136     % ./mach wpt testing/web-platform/tests/webdriver
 137
 138 WPT tests conformance to the [WebDriver] standard and uses
 139 [geckodriver].  Together with the Marionette remote protocol in
 140 Gecko, they make up Mozilla’s WebDriver implementation.
 141
 142 This command supports a `--webdriver-arg='-vv'` argument that
 143 enables more detailed logging, as well as `--jsdebugger` for opening
 144 the Browser Toolbox.
 145
 146 A particularly useful trick is to combine this with the headless
 147 mode for Firefox:
 148
 149     % ./mach wpt --webdriver-arg='-vv' --headless testing/web-platform/tests/webdriver
 150
 151 [WebDriver]: https://w3c.github.io/webdriver/
 152
 153 ## Harness tests
 154
 155 The Marionette harness Python package has a set of mock-styled unit
 156 tests that uses the [pytest] framework.  The following command will
 157 run all tests:
 158
 159     % ./mach python-test testing/marionette
 160
 161 To run a specific test specify the full path to the module:
 162
 163     % ./mach python-test testing/marionette/harness/marionette_harness/tests/harness_unit/test_serve.py
 164
 165 [pytest]: https://docs.pytest.org/en/latest/
 166
 167 ## One-click loaners
 168
 169 Additionally, for debugging hard-to-reproduce test failures in CI,
 170 one-click loaners from [Taskcluster](Taskcluster.md) can be particularly useful.
 171
 172 ## Out-of-tree testing
 173
 174 All the above examples show tests running _in-tree_, with a local
 175 checkout of _central_ and a local build of Firefox.  It is also
 176 possibly to run the Marionette tests _without_ a local build and
 177 with a downloaded test archive from [Taskcluster](Taskcluster.md)
 178
 179 If you want to run tests from a downloaded test archive, you will
 180 need to download the `target.common.tests.tar.gz` artifact attached to
 181 Treeherder [build jobs] `B` for your system.  Extract the archive
 182 and set up the Python Marionette client and harness by executing
 183 the following command in a virtual environment:
 184
 185     % pip install -r config/marionette_requirements.txt
 186
 187 The tests can then be found under
 188 _marionette/tests/testing/marionette/harness/marionette_harness/tests_
 189 and can be executed with the command `marionette`.  It supports
 190 the same options as described above for `mach`.
 191
 192 [build jobs]: https://treeherder.mozilla.org/#/jobs?repo=mozilla-central&filter-searchStr=build