README.rst (3702B)
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 .. code-block:: json 104 105 { 106 "name": "intermediate", 107 "addons":{ 108 "uBlock":"https://addons.mozilla.org/firefox/downloads/file/3361355/ublock_origin-1.21.2-an+fx.xpi" 109 }, 110 "prefs":{ 111 "accessibility.tabfocus": 9 112 }, 113 "scenario": { 114 "heavy": {"max_urls": 10} 115 } 116 }