testing/condprofile/README.rst

   1 Conditioned Profile
   2 ===================
   3
   4 This project provides a command-line tool that is used to generate and maintain
   5 a collection of Gecko profiles.
   6
   7 Unlike testing/profiles, the **conditioned profiles** are a collection of full
   8 Gecko profiles that are dynamically updated every day.
   9
  10 Each profile is created or updated using a **scenario** and a
  11 **customization**, and eventually uploaded as an artifact in TaskCluster.
  12
  13 The goal of the project is to build a collection of profiles that we can use in
  14 our performance or functional tests instead of the empty profile that we
  15 usually create on the fly with **mozprofile**.
  16
  17 Having a collection of realistic profiles we can use when running some tests
  18 gives us the ability to check the impact of user profiles on page loads or
  19 other tests.
  20
  21 A full cycle of how this tool is used in Taskcluster looks like this:
  22
  23 For each combination of scenario, customization and platform:
  24
  25 - grabs an existing profile in Taskcluster
  26 - browses the web using the scenario, via the WebDriver client
  27 - recreates a tarball with the updated profile
  28 - uploads it as an index artifact into TaskCluster - maintains a changelog of each change
  29
  30 It's based on the Arsenic webdriver client https://github.com/HDE/arsenic
  31
  32 The project provides two **Mach** commands to interact with the conditioned
  33 profile:
  34
  35 - **fetch-condprofile**: downloads a conditioned profile and deecompress it
  36 - **run-condprofile**: runs on or all conditioned profiles scenarii locally
  37
  38 How to download a conditioned profile
  39 =====================================
  40
  41 From your mozilla-central root, run:
  42
  43 ::
  44
  45     $ ./mach fetch-condprofile
  46
  47 This will grab the latest conditioned profile for your platform. But
  48 you can also grab a specific profile built from any scenario or platform.
  49
  50 You can look at all the options with --help
  51
  52 How to run a conditioned profile
  53 ================================
  54
  55 If you want to play a scenario locally to modify it, run for example:
  56
  57 ::
  58
  59     $ ./mach run-condprofile --scenario settled --visible /path/to/generated/profile
  60
  61 The project will run a webdriver session against Firefox and generate the profile.
  62 You can look at all the options with --help
  63
  64 Architecture
  65 ============
  66
  67 The conditioned profile project is organized into webdriver **scenarii** and
  68 **customization** files.
  69
  70 Scenarii
  71 --------
  72
  73 Scenarii are coroutines registered under a unique name in condprof/scenarii/__init__.py.
  74
  75 They get a **session** object and some **options**.
  76
  77 The scenario can do whatever it wants with the browser, through the webdriver session
  78 instance.
  79
  80 See Arsenic's `API documentation <https://arsenic.readthedocs.io/en/latest/reference/session.html>`_ for the session class.
  81
  82 Adding a new scenario is done by adding a module in condprof/scenarii/
  83 and register it in condprof/scenarii/__init__.py
  84
  85
  86 Customization
  87 -------------
  88
  89 A customization is a configuration file that can be used to set some
  90 prefs in the browser and install some webextensions.
  91
  92 Customizations are JSON files registered into condprof/customizations,
  93 and they provide four keys:
  94
  95 - **name**: the name of the customization
  96 - **addons**: a mapping of add-ons to install.
  97 - **prefs**: a mapping of prefs to set
  98 - **scenario**: a mapping of options to pass to a specific scenario
  99
 100 In the example below, we install uBlock, set a pref, and pass the
 101 **max_urls** option to the **heavy** scenario.
 102
 103   {
 104       "name": "intermediate",
 105       "addons":{
 106          "uBlock":"https://addons.mozilla.org/firefox/downloads/file/3361355/ublock_origin-1.21.2-an+fx.xpi"
 107       },
 108       "prefs":{
 109          "accessibility.tabfocus": 9
 110       },
 111       "scenario": {
 112          "heavy": {"max_urls": 10}
 113       }
 114    }