remote/doc/marionette/Taskcluster.md

   1 # Testing with one-click loaners
   2
   3 [Taskcluster] is the task execution framework that supports Mozilla's
   4 continuous integration and release processes.
   5
   6 Build and test jobs (like Marionette) are executed across all supported
   7 platforms, and job results are pushed to [Treeherder] for observation.
   8
   9 The best way to debug issues for intermittent test failures of
  10 Marionette tests for Firefox and Fennec (Android) is to use a
  11 one-click loaner as provided by Taskcluster. Such a loaner creates
  12 an interactive task you can interact with via a shell and VNC.
  13
  14 To create an interactive task for a Marionette job which is shown
  15 as failed on Treeherder, select the job, click the ellipse in the lower
  16 left pane, and choose `Create Interactive Task`.
  17
  18 Please note that you need special permissions to actually request
  19 such a loaner.
  20
  21 When the task has been created you will receive an email with the connection
  22 details. Open the referenced shell and you will be connected via a WebSocket.
  23 Once that has been done a wizard will automatically launch and
  24 provide some options. Best here is to choose the second option,
  25 which will run all the setup steps, installs the Firefox or Fennec
  26 binary, and then exits.
  27
  28 [Taskcluster]: https://docs.taskcluster.net/
  29 [Treeherder]: https://treeherder.mozilla.org
  30
  31 ## Setting up the Marionette environment
  32
  33 Best here is to use a virtual environment, which has all the
  34 necessary packages installed. If no modifications to any Python
  35 package will be done, the already created environment by the
  36 wizard can be used:
  37
  38 ```shell
  39 % cd /builds/worker/workspace/build
  40 % source venv/bin/activate
  41 ```
  42
  43 Otherwise a new virtual environment needs to be created and
  44 populated with the mozbase and marionette packages installed:
  45
  46 ```shell
  47 % cd /builds/worker/workspace/build && rm -r venv
  48 % virtualenv venv && source venv/bin/activate
  49 % cd tests/mozbase && ./setup_development.py
  50 % cd ../marionette/client && python setup.py develop
  51 % cd ../harness && python setup.py develop
  52 % cd ../../../
  53 ```
  54
  55 ## Running Marionette tests
  56
  57 ### Firefox
  58
  59 To run the Marionette tests execute the `runtests.py` script. For all
  60 the required options as best search in the log file of the failing job
  61 the interactive task has been created from.  Then copy the complete
  62 command and run it inside the already sourced virtual environment:
  63
  64 ```shell
  65 % /builds/worker/workspace/build/venv/bin/python -u /builds/worker/workspace/build/tests/marionette/harness/marionette_harness/runtests.py --gecko-log=- -vv --binary=/builds/worker/workspace/build/application/firefox/firefox --address=127.0.0.1:2828 --symbols-path=https://queue.taskcluster.net/v1/task/GSuwee61Qyibujtxq4UV3A/artifacts/public/build/target.crashreporter-symbols.zip /builds/worker/workspace/build/tests/marionette/tests/testing/marionette/harness/marionette_harness/tests/unit-tests.ini
  66 ```
  67
  68 ### Fennec
  69
  70 The Marionette tests for Fennec are executed by using an Android
  71 emulator which runs on the host platform. As such some extra setup
  72 steps compared to Firefox on desktop are required.
  73
  74 The following lines set necessary environment variables before
  75 starting the emulator in the background, and to let Marionette
  76 know of various Android SDK tools.
  77
  78 ```shell
  79 % export ADB_PATH=/builds/worker/workspace/build/android-sdk-linux/platform-tools/adb
  80 % export ANDROID_AVD_HOME=/builds/worker/workspace/build/.android/avd/
  81 % /builds/worker/workspace/build/android-sdk-linux/tools/emulator -avd test-1 -show-kernel -debug init,console,gles,memcheck,adbserver,adbclient,adb,avd_config,socket &
  82 ```
  83
  84 The actual call to `runtests.py` is different per test job because
  85 those are using chunks on Android. As best search for the command
  86 and its options in the log file of the failing job the interactive
  87 task has been created from. Then copy the complete command and run
  88 it inside the already sourced virtual environment.
  89
  90 Here an example for chunk 1 which runs all the tests in the current
  91 chunk with some options for logs removed:
  92
  93 ```shell
  94 % /builds/worker/workspace/build/venv/bin/python -u /builds/worker/workspace/build/tests/marionette/harness/marionette_harness/runtests.py --emulator --app=fennec --package=org.mozilla.fennec_aurora --address=127.0.0.1:2828 /builds/worker/workspace/build/tests/marionette/tests/testing/marionette/harness/marionette_harness/tests/unit-tests.ini --gecko-log=- --symbols-path=/builds/worker/workspace/build/symbols --startup-timeout=300 --this-chunk 1 --total-chunks 10
  95 ```
  96
  97 To execute a specific test only simply replace `unit-tests.ini`
  98 with its name.