TestEngineering/Performance/Raptor

Raptor is a performance-testing framework for running browser pageload and browser benchmark tests. The core of Raptor was designed as a browser extension, therefore Raptor is cross-browser compatible and is currently running in production on Firefox Desktop, Firefox Android GeckoView, Fennec, Fenix, Reference Browser, Chromium, and Chrome.

• Contact: Dave Hunt [:davehunt]
• Source code: https://searchfox.org/mozilla-central/source/testing/raptor
• Good first bugs: https://codetribute.mozilla.org/projects/automation?project%3DRaptor

Raptor currently supports three test types: 1) page-load performance tests, 2) standard benchmark-performance tests, and 3) "scenario"-based tests, such as power, CPU, and memory-usage measurements on Android (and desktop?).

Locally, raptor can be invoked with either of the following commands - raptor-test may be deprecated in the future:

    ./mach raptor
    ./mach raptor-test

Page-Load Tests

Page-load tests involve loading a specific web page and measuring the load performance (i.e. time-to-first-non-blank-paint, first-contentful-paint , dom-content-flushed, ttfi).

For page-load tests by default, instead of using live web pages for performance testing, Raptor uses a tool called [Mitmproxy]. Mitmproxy allows us to record and playback test pages via a local Firefox proxy. The Mitmproxy recordings are stored on tooltool and are automatically downloaded by Raptor when they are required for a test. Raptor uses mitmproxy via the mozbase mozproxy package.

There are two different types of Raptor page-load tests: warm page-load and cold page-load.

Warm Page-Load

For warm page-load tests, the desktop browser (or android browser app) is just started up once; so the browser is warm on each page-load.

Raptor warm page-load test process when running on Firefox/Chrome/Chromium desktop:

• A new browser profile is created
• The desktop browser is started up
• Post-startup browser settle pause of 30 seconds
• A new tab is opened
• The test URL is loaded; measurements taken
• The tab is reloaded 24 more times; measurements taken each time
• The measurements from the first page-load are not included in overall results metrics b/c of first load noise; however they are listed in the perfherder-data.json/raptor.json artifacts

Raptor warm page-load test process when running on Firefox android browser apps:

• The android app data is cleared (via `adb shell pm clear firefox.app.binary.name`)
• The new browser profile is copied onto the android device sdcard
• The Firefox android app is started up
• Post-startup browser settle pause of 30 seconds
• On Fennec only, a new browser tab is created (other Firefox apps use the single/existing tab)
• The test URL is loaded; measurements taken
• The tab is reloaded 14 more times; measurements taken each time
• The measurements from the first page-load are not included in overall results metrics b/c of first load noise; however they are listed in the perfherder-data.json/raptor.json artifacts

Cold Page-Load

For cold page-load tests, the desktop browser (or android browser app) is shut down and restarted between page load cycles; so the browser is cold on each page-load. This is what happens for Raptor cold page-load tests:

Raptor cold page-load test process when running on Firefox/Chrome/Chromium desktop:

• A new browser profile is created
• The desktop browser is started up
• Post-startup browser settle pause of 30 seconds
• A new tab is opened
• The test URL is loaded; measurements taken
• The tab is closed
• The desktop browser is shut down
• Entire process is repeated for the remaining browser cycles (25 cycles total)
• The measurements from all browser cycles are used to calculate overall results

Raptor cold page-load test process when running on Firefox Android browser apps:

• The Android app data is cleared (via `adb shell pm clear firefox.app.binary.name`)
• A new browser profile is created
• The new browser profile is copied onto the Android device sdcard
• The Firefox Android app is started up
• Post-startup browser settle pause of 30 seconds
• On Fennec only, a new browser tab is created (other Firefox apps use the single/existing tab)
• The test URL is loaded; measurements taken
• The Android app is shut down
• Entire process is repeated for the remaining browser cycles (15 cycles total)
• Note that the SSL cert DB is only created once (browser cycle 1) and copied into the profile for each additional browser cycle; thus not having to use the 'certutil' tool and re-created the db on each cycle
• The measurements from all browser cycles are used to calculate overall results

Using Live Sites

It is possible to use live web pages for the page-load tests instead of using the mitproxy recordings. This option is available when running on Try only; as we don't want to submit data from live pages to Perfherder (since live page content will always be changing).

To run a particular Raptor tp6 page-load test with live sites, open the raptor-tp6*.ini file (Raptor tests folder), and for the test default (or under a single page/subtest) just add this attribute:

 use_live_sites = true

And push that change to Try (./mach try fuzzy --full) and run the Raptor page-load test.

Disabling Alerts

It is possible to disable alerting for all our performance tests. Open the target test manifest such as the raptor-tp6*.ini file (Raptor tests folder), and make sure there are no alert_on specifications.

When it's removed there will no longer be a shouldAlert field in the output perferhder data (you can find the schema here). As long as shouldAlert is not in the data, no alerts will be generated. If you need to also disable code sheriffing for the test, then you need to change the tier of the task to 3.

Benchmark Tests

Standard benchmarks are third-party tests (i.e. Speedometer) that we have integrated into Raptor to run per-commit in our production CI.

Scenario Tests

Currently, there are three subtypes of Raptor-run "scenario" tests, all on (and only on) Android:

1. power-usage tests
2. memory-usage tests
3. CPU-usage tests

For a combined-measurement run with distinct Perfherder output for each measurement type, you can do:

 ./mach raptor-test --test raptor-scn-power-idle-bg-fenix  --app fenix --binary org.mozilla.fenix.performancetest --host 10.0.0.16 --power-test --memory-test --cpu-test

Each measurement subtype (power-, memory-, and cpu-usage) will have a corresponding PERFHERDER_DATA blob:

22:31:05     INFO -  raptor-output Info: PERFHERDER_DATA: {"framework": {"name": "raptor"}, "suites": [{"name": "raptor-scn-power-idle-bg-fenix-cpu", "lowerIsBetter": true, "alertThreshold": 2.0, "value": 0, "subtests": [{"lowerIsBetter": true, "unit": "%", "name": "cpu-browser_cpu_usage", "value": 0, "alertThreshold": 2.0}], "type": "cpu", "unit": "%"}]}
22:31:05     INFO -  raptor-output Info: cpu results can also be found locally at: /Users/sdonner/moz_src/mozilla-unified/testing/mozharness/build/raptor-cpu.json

(repeat for power, memory snippets)

Power-Use Tests (Android)

Prerequisites

1. rooted (i.e. superuser-capable), bootloader-unlocked Moto G5 or Google Pixel 2: internal (for now) test-device setup doc.
2. set up to run Raptor from a Firefox source tree (see Running Locally
3. GeckoView-bootstrapped environment

Raptor power-use measurement test process when running on Firefox Android browser apps:

• The Android app data is cleared, via:

 * adb shell pm clear firefox.app.binary.name

• The new browser profile is copied onto the Android device's sdcard
• We set `scenario_time` to 20 minutes (1200000 milliseconds), and `page_timeout` to '22 minutes' (1320000 milliseconds)
  • It's crucial that `page_timeout` exceed `scenario_time`; if not, measurement tests will fail/bail early
• We launch the {Fenix, Fennec, GeckoView, Reference Browser} on-Android app
• Post-startup browser settle pause of 30 seconds
• On Fennec only, a new browser tab is created (other Firefox apps use the single/existing tab)
• Power-use/battery-level measurements (app-specific measurements) are taken, via:

 * adb shell dumpsys batterystats

• Raw power-use measurement data is listed in the perfherder-data.json/raptor.json artifacts

In the Perfherder (or Firefox Health) dashboards for these power usage tests, all data points have milli-Ampere-hour units, with a lower value being better. Proportional power usage is the total power usage of hidden battery sippers that is proportionally "smeared"/distributed across all open applications.

Running Locally

To run on a tethered phone via USB from a macOS host, on:

Fennec

 ./mach raptor --test raptor-scn-power-idle-fennec --app fennec --binary org.mozilla.firefox --power-test --host 10.252.27.96

Fenix

 ./mach raptor --test raptor-scn-power-idle-fenix --app fenix --binary org.mozilla.fenix.performancetest --power-test --host 10.252.27.96

GeckoView

 ./mach raptor --test raptor-scn-power-idle-geckoview --app geckoview --binary org.mozilla.geckoview_example --power-test --host 10.252.27.96

Reference Browser

 ./mach raptor --test raptor-scn-power-idle-refbrow --app refbrow --binary org.mozilla.reference.browser.raptor --power-test --host 10.252.27.96

NOTE:

• it is important that you include `--power-test`, when running power-usage measurement tests, as that will help ensure that local test-measurement data doesn't accidentally get submitted to Perfherder

Pushing to Try server

As an example, a relatively good cross-sampling of builds can be seen in https://hg.mozilla.org/try/rev/6c07631a0c2bf56b51bb82fd5543d1b34d7f6c69.

• Include both G5 Android 7 (hw-g5-7-0-arm7-api-16/*) *and* Pixel 2 Android 8 (p2-8-0-android-aarch64/) target platforms
• pgo builds tend to be -- from my limited empirical evidence -- about 10 - 15 minutes longer to complete than their opt counterparts

Perf Dashboards

• Perfherder example (GeckoView): https://treeherder.mozilla.org/perf.html#/graphs?timerange=2592000&series=mozilla-central,2027286,1,10&series=mozilla-central,2027291,1,10&series=mozilla-central,2027296,1,10
• Coming soon to https://health.graphics/android

Running Locally

Prerequisites

In order to run Raptor on a local machine, you need:

• A local mozilla repository clone with a successful Firefox build completed
• Git needs to be in the path in the terminal/window in which you build Firefox / run Raptor, as Raptor uses Git to check-out a local copy for some of the performance benchmarks' sources.
• If you plan on running Raptor tests on Google Chrome, you need a local install of Google Chrome and know the path to the chrome binary
• If you plan on running Raptor on Android, your Android device must already be set up (see more below in the Android section)

Getting a List of Raptor Tests

To see which Raptor performance tests are currently available on all platforms, use the 'print-tests' option, e.g.:

    $ ./mach raptor --print-tests

That will output all available tests on each supported app, as well as each subtest available in each suite (i.e. all the pages in a specific page-load tp6* suite).

Running on Firefox

To run Raptor locally, just build Firefox and then run:

    $ ./mach raptor --test <raptor-test-name>

For example, to run the raptor-tp6 pageload test locally, just use:

    $ ./mach raptor --test raptor-tp6-1

You can run individual subtests too (i.e. a single page in one of the tp6* suites). For example, to run the amazon page-load test on Firefox:

    $ ./mach raptor --test raptor-tp6-amazon-firefox

Raptor test results will be found locally in <your-repo>/testing/mozharness/build/raptor.json.

Running on the Android GeckoView Example App

When running Raptor tests on a local Android device, Raptor is expecting the device to already be set up and ready to go.

First, ensure your local host machine has the Android SDK/Tools (i.e. ADB) installed. Check if it is already installed by attaching your Android device to USB and running:

    $ adb devices

If your device serial number is listed, then you're all set. If ADB is not found, you can install it by running (in your local mozilla-development repo):

    $ ./mach bootstrap

Then, in bootstrap, select the option for "Firefox for Android Artifact Mode," which will install the required tools (no need to do an actual build).

Next, make sure your Android device is ready to go. Local Android-device prerequisites are:

• Device is rooted

Note: If you are using Magisk to root your device, use version 17.3

• Device is in 'superuser' mode
  • [stephend] - I want to explain this a bit more, so leaving this comment as a reminder

• The geckoview example app is already installed on the device (from ./mach bootstrap, above). Download the geckoview_example.apk from the appropriate android build on treeherder, then install it on your device, i.e.:

    $ adb install -g ../Downloads/geckoview_example.apk

The '-g' flag will automatically set all application permissions ON, which is required.

Note, when the Gecko profiler should be run, or a build with build symbols is needed, then use a Nightly build of geckoview_example.apk.

When updating the geckoview example app, you MUST uninstall the existing one first, i.e.:

    $ adb uninstall org.mozilla.geckoview_example

Once your Android device is ready, and attached to local USB, from within your local mozilla repo use the following command line to run speedometer:

    $ ./mach raptor --test raptor-speedometer --app=geckoview --binary="org.mozilla.geckoview_example"

Note: Speedometer on Android GeckoView is currently running on two devices in production - the Google Pixel 2 and the Moto G5 - therefore it is not guaranteed that it will run successfully on all/other untested android devices. There is an intermittent failure on the Moto G5 where speedometer just stalls (Bug 1492222).

To run a Raptor page-load test (i.e. tp6m-1) on the GeckoView Example app, use this command line:

    $ ./mach raptor --test raptor-tp6m-1 --app=geckoview --binary="org.mozilla.geckoview_example"

A couple notes about debugging:

• Raptor browser-extension console messages *do* appear in adb logcat via the GeckoConsole - so this is handy:

    $ adb logcat | grep GeckoConsole

• You can also debug Raptor on Android using the Firefox WebIDE; click on the Android device listed under "USB Devices" and then "Main Process" or the 'localhost: Speedometer.." tab process

Raptor test results will be found locally in <your-repo>/testing/mozharness/build/raptor.json.

Running on Google Chrome

To run Raptor locally on Google Chrome, make sure you already have a local version of Google Chrome installed, and then from within your mozilla-repo run:

    $ ./mach raptor --test <raptor-test-name> --app=chrome --binary="<path to google chrome binary>"

For example, to run the raptor-speedometer benchmark on Google Chrome use:

    $ ./mach raptor --test raptor-speedometer --app=chrome --binary="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome

Raptor test results will be found locally in <your-repo>/testing/mozharness/build/raptor.json.

Page-Timeouts

On different machines the Raptor tests will run at different speeds. The default page-timeout is defined in each Raptor test INI file. On some machines you may see a test failure with a 'raptor page-timeout' which means the page-load timed out, or the benchmark test iteration didn't complete, within the page-timeout limit.

You can override the default page-timeout by using the --page-timeout command-line arg. In this example, each test page in tp6-1 will be given two minutes to load during each page-cycle:

 ./mach raptor --test raptor-tp6-1 --page-timeout 120000

If an iteration of a benchmark test is not finishing within the allocated time, increase it by:

 ./mach raptor --test raptor-speedometer --page-timeout 600000

Page-Cycles

Page-cycles is the number of times a test page is loaded (for page-load tests); for benchmark tests, this is the total number of iterations that the entire benchmark test will be run. The default page-cycles is defined in each Raptor test INI file.

You can override the default page-cycles by using the --page-cycles command-line arg. In this example, the test page will only be loaded twice:

 ./mach raptor --test raptor-tp6-google-firefox --page-cycles 2

Running Page-Load Tests on Live Sites

By default, Raptor page-load performance tests load the test pages from a recording (see Raptor and Mitmproxy). However it is possible to tell Raptor to load the test pages from the live internet instead of using the recorded page playback.

To use live pages instead of page recordings, just edit the Raptor tp6* test INI file and add the following attribute either at the top (for all pages in the suite) or under an individual page/subtest heading:

 use_live_pages = true

With that setting, Raptor will not start the playback tool (i.e. Mitmproxy) and will not turn on the corresponding browser proxy, therefore forcing the test page to load live.

When `use_live_pages = true` and a page-load test is measuring hero element (set in the test INI 'measure' option) then the hero element measurement will automatically be dropped - because the hero elements only exist in our Mitmproxy recordings and not in live pages.

The word 'live' will be appended to the test name in the PERFHERDER_DATA so live sites can be specifically seen in perfherder for try runs.

Important: This is fine for running on try, but we don't want to enable live sites in the production repos - because we don't want live site data being ingested by perfherder and used for regression alerting etc. Therefore as a safety catch, if using live sites the test won't even run unless running locally or on try.

Running Raptor on Try

Raptor tests can be run on try on both Firefox and Google Chrome. (Raptor pageload-type tests are not supported on Google Chrome yet, as mentioned above).

Note: Raptor is currently 'tier 2' on Treeherder, which means to see the Raptor test jobs you need to ensure 'tier 2' is selected / turned on in the Treeherder 'Tiers' menu.

The easiest way to run Raptor tests on try is to use mach try fuzzy:

    $ ./mach try fuzzy --full

Then type 'raptor' and select which Raptor tests (and on what platforms) you wish to run.

To see the Raptor test results on your try run:

1. In treeherder select one of the Raptor test jobs (i.e. 'sp' in 'Rap-e10s', or 'Rap-C-e10s')
2. Below the jobs, click on the "Performance" tab; you'll see the aggregated results listed
3. If you wish to see the raw replicates, click on the "Job Details" tab, and select the "perfherder-data.json" artifact

Raptor Hardware in Production

The Raptor performance tests run on dedicated hardware (the same hardware that the Talos performance tests use). See the [hardware used in automation wiki page] for more details.

Running Fennec ESR 68 tests

Fennec 68 tests are setup to run on latest fennec esr 68 build.

To start a try run on Fennec ESR 68 run:

    $ ./mach try fuzzy -q="fennec68" --full

Profiling Raptor Jobs

Raptor tests are able to create Gecko profiles which can be viewed in profiler.firefox.com. This is currently only supported when running Raptor on Firefox desktop.

Nightly Profiling Jobs in Production

We have Firefox desktop Raptor jobs with Gecko-profiling enabled running Nightly in production on Mozilla Central (on Linux64, Win10, and OSX). This provides a steady cache of Gecko profiles for the Raptor tests. Search for the "Rap-Prof" treeherder group on Mozilla Central.

Profiling Locally

To tell Raptor to create Gecko profiles during a performance test, just add the '--gecko-profile' flag to the command line, i.e.:

    $ ./mach raptor --test raptor-sunspider --gecko-profile

When the Raptor test is finished, you will be able to find the resulting gecko profiles (ZIP) located locally in:

    mozilla-central/testing/mozharness/build/blobber_upload_dir/

Note: While profiling is turned on, Raptor will automatically reduce the number of pagecycles to 3. If you wish to override this, add the --page-cycles argument to the raptor command line.

Raptor will automatically launch Firefox and load the latest Gecko profile in profiler.firefox.com. To turn this feature off, just set the DISABLE_PROFILE_LAUNCH=1 env var.

If auto-launch doesn't work for some reason, just start Firefox manually and browse to profiler.firefox.com, click on "Browse" and select the Raptor profile ZIP file noted above.

If you're on Windows and want to profile a Firefox build that you compiled yourself, make sure it contains profiling information and you have a symbols zip for it, by following the directions on MDN.

Profiling on Try Server

To turn on Gecko profiling for Raptor test jobs on try pushes, just add the '--gecko-profile' flag to your try push i.e.:

   $ ./mach try fuzzy --gecko-profile

Then select the Raptor test jobs that you wish to run. The Raptor jobs will be run on try with profiling included. While profiling is turned on, Raptor will automatically reduce the number of pagecycles to 2.

See below for how to view the gecko profiles from within treeherder.

Customizing the profiler

If the default profiling options are not enough, and further information is needed the gecko profiler can be customized.

Enable profiling of additional threads

In some cases it will be helpful to also measure threads which are not part of the default set. Like the MediaPlayback thread. This can be accomplished by using:

1. the gecko_profile_threads manifest entry, and specifying the thread names as comma separated list
2. the --gecko-profile-thread' argument for mach for each extra thread to profile

Add Profiling to Previously Completed Jobs

Note: You might need treeherder 'admin' access for the following.

Gecko profiles can now be created for Raptor performance test jobs that have already completed in production (i.e. mozilla-central) and on try. To repeat a completed Raptor performance test job on production or try, but add gecko profiling, do the following:

1. In treeherder, select the symbol for the completed Raptor test job (i.e. 'ss' in 'Rap-e10s')
2. Below, and to the left of the 'Job Details' tab, select the '...' to show the menu
3. On the pop-up menu, select 'Create Gecko Profile'

The same Raptor test job will be repeated but this time with gecko profiling turned on. A new Raptor test job symbol will be added beside the completed one, with a '-p' added to the symbol name. Wait for that new Raptor profiling job to finish. See below for how to view the gecko profiles from within treeherder.

Viewing Profiles on Treeherder

When the Raptor jobs are finished, to view the gecko profiles:

1. In treeherder, select the symbol for the completed Raptor test job (i.e. 'ss' in 'Rap-e10s')
2. Click on the 'Job Details' tab below
3. The Raptor profile ZIP files will be listed as job artifacts;
4. Select a Raptor profile ZIP artifact, and click the 'view in Firefox Profiler' link to the right

Recording Pages for Raptor Pageload Tests

Raptor pageload tests ('tp6' and 'tp6m' suites) use the Mitmproxy tool to record and play back page archives. For more information on creating new page playback archives, please see Raptor and Mitmproxy.

Performance Tuning for Android devices

When the test is run against Android, Raptor executes a series of performance tuning commands over the ADB connection.

Device agnostic:

• memory bus
• device remain on when on USB power
• virtual memory (swappiness)
• services (thermal throttling, cpu throttling)
• i/o scheduler

Device specific:

• cpu governor
• cpu minimum frequency
• gpu governor
• gpu minimum frequency

For a detailed list of current tweaks, please refer to this Searchfox page.

Raptor Test List

Currently the following Raptor tests are available. Note: Check the test details below to see which browser (i.e. Firefox, Google Chrome, Android) each test is supported on.

Page-Load Tests

For all Raptor page-load tests, the pages are played back from [Mitmproxy] recordings. If you need the HTML page source (outside of the Mitmproxy recording) for debugging, the raw HTML can be found in our perf-automation github repo.

All the pages in a test suite an be run by calling the top-level test name, i.e.:

 ./mach raptor --test raptor-tp6-1

Individual test pages can be ran by calling the subtest, i.e.:

 ./mach raptor --test raptor-tp6-google-firefox

Some of the page recordings contain [hero elements]. When hero elements are measured, the value is the time until the hero element appears on the page (in MS).

All pageload tests can be found at raptor-tp6 tests

Below are the details for page-load suites:

raptor-tp6-1 to 10

• contact: :rwood, :davehunt, :bebe
• type: page-load
• browsers: Firefox desktop, Chromium, Google Chrome desktop (Windows and OSX only at the moment)
• measuring on Firefox: time-to-first-non-blank-paint, first-contentful-paint, dom-content-flushed, loadtime
• measuring on Chrome: first-contentful-paint, loadtime
• page-cycles: 25
• reporting: Each pagecycle measures all the values (in MS). The first page-cycle is dropped due to the initial extra loading time/noise. The overall result reported for each test page is the median of the values reported for each pagecycle (in MS).
• test INI's: raptor-tp6-1 to 10 .

raptor-tp6-cold-1 to 4

• contact: :rwood, :davehunt, :bebe
• type: page-load, cold
• browsers: Firefox desktop, Chromium, Google Chrome desktop (Windows and OSX only at the moment)
• measuring on Firefox: time-to-first-non-blank-paint, first-contentful-paint, dom-content-flushed, loadtime
• measuring on Chrome: first-contentful-paint, loadtime
• page-cycles: 25
• reporting: Each pagecycle measures all the values (in MS). The first page-cycle is dropped due to the initial extra loading time/noise. The overall result reported for each test page is the median of the values reported for each pagecycle (in MS).
• test INI's: raptor-tp6-cold-1 to 4 .

raptor-tp6m-1 to 10

• contact: :rwood, :davehunt, :bebe
• type: page-load
• browsers: Firefox Android Geckoview Example App
• measuring: time-to-first-non-blank-paint, first-contentful-paint, dom-content-flushed, time-to-first-interactive, loadtime
• page-cycles: 15
• reporting: Each pagecycle measures all the values (in MS). The first page-cycle is dropped due to the initial extra loading time/noise. The overall result reported for each test page is the median of the values reported for each pagecycle (in MS).
• test INI: raptor-tp6m-1 to 10.

raptor-tp6m-cold-1 to 27

• contact: :rwood, :davehunt, :bebe
• type: page-load, cold
• browsers: Firefox Android Geckoview Example App
• measuring: time-to-first-non-blank-paint, first-contentful-paint, dom-content-flushed, time-to-first-interactive, loadtime
• page-cycles: 15
• reporting: Each pagecycle measures all the values (in MS). The first page-cycle is dropped due to the initial extra loading time/noise. The overall result reported for each test page is the median of the values reported for each pagecycle (in MS).
• test INI: raptor-tp6m-cold-1 to 27.

raptor-tp6m-cold-1 to 9-fennec68

• contact: :rwood, :davehunt, :bebe
• type: page-load
• browsers: Firefox Android Fennec ESR 68 App
• measuring: time-to-first-non-blank-paint, first-contentful-paint, dom-content-flushed, time-to-first-interactive, loadtime
• page-cycles: 15
• reporting: Each pagecycle measures all the values (in MS). The first page-cycle is dropped due to the initial extra loading time/noise. The overall result reported for each test page is the median of the values reported for each pagecycle (in MS).
• test INI: raptor-tp6m-1 to 9-fennec68.

raptor-tp6m-cold-1 to 27-fennec68

• contact: :rwood, :davehunt, :bebe
• type: page-load, cold
• browsers: Firefox Android Fennec ESR 68 App
• measuring: time-to-first-non-blank-paint, first-contentful-paint, dom-content-flushed, time-to-first-interactive, loadtime
• page-cycles: 15
• reporting: Each pagecycle measures all the values (in MS). The first page-cycle is dropped due to the initial extra loading time/noise. The overall result reported for each test page is the median of the values reported for each pagecycle (in MS).
• test INI: raptor-tp6m-cold-1 to 14-fennec68.

Benchmark Tests

raptor-assorted-dom

• contact: ?
• type: benchmark
• browsers: Firefox desktop, Chrome desktop
• TODO

raptor-motionmark-animometer, raptor-motionmark-htmlsuite

• contact: ?
• type: benchmark
• browsers: Firefox desktop, Chrome desktop
• measuring: benchmark measuring the time to animate complex scenes
• summarization:
  • subtest: FPS from the subtest, each subtest is run for 15 seconds, repeat this 5 times and report the median value
  • suite: we take a geometric mean of all the subtests (9 for animometer, 11 for html suite)

raptor-speedometer v1.0

• contact: :selena
• type: benchmark
• browsers: Firefox desktop, Chrome desktop, Firefox Android Geckoview
• measuring: responsiveness of web applications
• reporting: runs/minute score
• data: there are 16 subtests in Speedometer; each of these are made up of 9 internal benchmarks.
• summarization:
  • subtest: For all of the 16 subtests, we collect a summed of all their internal benchmark results for each of them. To obtain a single score per subtest, we take a median of the replicates.
  • score: geometric mean of the 16 subtest metrics (along with some special corrections).

This is the Speedometer v1.0 JavaScript benchmark taken verbatim and slightly modified to work with the Raptor harness.

raptor-stylebench

• contact: :emilio
• type: benchmark
• browsers: Firefox desktop, Chrome desktop
• measuring: speed of dynamic style recalculation
• reporting: runs/minute score

raptor-sunspider

• contact: ?
• type: benchmark
• browsers: Firefox desktop, Chrome desktop
• TODO

raptor-unity-webgl

• contact: ?
• type: benchmark
• browsers: Firefox desktop, Chrome desktop, Firefox Android Geckoview
• TODO

raptor-youtube-playback

• contact: ?
• type: benchmark
• details: YouTube playback performance
• browsers: Firefox desktop, Firefox Android Geckoview
• measuring: media streaming playback performance (dropped video frames)
• reporting: For each video the number of dropped and decoded frames, as well as its percentage value is getting recorded. The overall reported result is the mean value of dropped video frames across all tested video files.
• data: Given the size of the used media files those tests are currently run as live site tests, and are kept up-to-date via the perf-youtube-playback repository on Github.
• test INI: raptor-youtube-playback.ini

This are the Playback Performance Tests benchmark taken verbatim and slightly modified to work with the Raptor harness.

raptor-wasm-misc, raptor-wasm-misc-baseline, raptor-wasm-misc-ion

• contact: ?
• type: benchmark
• browsers: Firefox desktop, Chrome desktop
• TODO

raptor-wasm-godot, raptor-wasm-godot-baseline, raptor-wasm-godot-ion

• contact: ?
• type: benchmark
• browsers: Firefox desktop only
• TODO

raptor-webaudio

• contact: ?
• type: benchmark
• browsers: Firefox desktop, Chrome desktop
• TODO

Scenario Tests

This test type runs browser tests that use idle pages for a specified amount of time to gather resource usage information such as power usage. The pages used for testing do not need to be recorded with mitmproxy.

When creating a new scenario test, ensure that the `page-timeout` is greater than the `scenario-time` to make sure raptor doesn't exit the test before the scenario timer ends.

This test type can also be used for specialized tests that require communication with the control-server to do things like sending the browser to the background for X minutes.

Power-Usage Measurement Tests

These Android power measurement tests output 3 different PERFHERDER_DATA entries. The first contains the power usage of the test itself, the second contains the power usage of the android OS (named os-baseline) over the course of 1 minute, and the third (the name is the test name with '%change-power' appended to it) is a combination of these two measures which shows the percentage increase in power consumption when the test is run, in comparison to when it is not running. In these perfherder data blobs, we provide power consumption attributed to the cpu, wifi, and screen in Milli-ampere-hours (mAh).

raptor-scn-power-idle

• contact: stephend, sparky
• type: scenario
• browsers: Android: Fennec 64.0.2, GeckoView Example, Fenix, and Reference Browser
• measuring: Power consumption for idle Android browsers, with about:blank loaded and app foregrounded, over a 20-minute duration

raptor-scn-power-idle-bg

• contact: stephend, sparky
• type: scenario
• browsers: Android: Fennec 64.0.2, GeckoView Example, Fenix, and Reference Browser
• measuring: Power consumption for idle Android browsers, with about:blank loaded and app backgrounded, over a 10-minute duration

Debugging Desktop Product Failures

As of now, there is no easy way to do this. Raptor was not built for debugging functional failures. Hitting these in Raptor is indicative that we lack functional test coverage so regression tests should be added for those failures after they are fixed.

To debug a functional failure in Raptor you can follow these steps:

1. If bug 1653617 has not landed yet, apply the patch.
2. Add the --verbose flag to the extra-options list here.
3. If the --setenv doesn't exist yet (bug 1494669), then add your MOZ_LOG environment variables to give you additional logging here.
4. If the flag does exist, then you can add the MOZ_LOG variables to the raptor.yml configuration file.
5. Push to try if you can't reproduce the failure locally.

You can follow bug 1655554 as we work on improving this workflow.

In some cases, you might not be able to get logging for what you are debugging (browser console logging for instance). In this case, you should make your own debug prints with printf or something along those lines (see :agi's debugging work for an example).

Debugging the Raptor Web Extension

When developing on Raptor and debugging, there's often a need to look at the output coming from the Raptor Web Extension. Here are some pointers to help.

Raptor Debug Mode

The easiest way to debug the Raptor web extension is to run the Raptor test locally and invoke debug mode, i.e. for Firefox:

 ./mach raptor --test raptor-tp6-amazon-firefox --debug-mode

Or on Chrome, for example:

 ./mach raptor --test raptor-tp6-amazon-chrome --app=chrome --binary="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --debug-mode

Running Raptor with debug mode will:

• Automatically set the number of test page-cycles to 2 maximum
• Reduce the 30 second post-browser startup delay from 30 seconds to 3 seconds
• On Firefox, the devtools browser console will automatically open, where you can view all of the console log messages generated by the Raptor web extension
• On Chrome, the devtools console will automatically open
• The browser will remain open after the Raptor test has finished; you will be prompted in the terminal to manually shutdown the browser when you're finished debugging.

Manual Debugging on Firefox Desktop

The main Raptor runner is 'runner.js' which is inside the web extension. The code that actually captures the performance measures is in the web extension content code 'measure.js'.

In order to retrieve the console.log() output from the Raptor runner, do the following:

1. Invoke Raptor locally via ./mach raptor
2. During the 30 second Raptor pause which happens right after Firefox has started up, in the ALREADY OPEN current tab, type "about:debugging" for the URL.
3. On the debugging page that appears, make sure "Add-ons" is selected on the left (default).
4. Turn ON the "Enable add-on debugging" check-box
5. Then scroll down the page until you see the Raptor web extension in the list of currently-loaded add-ons. Under "Raptor" click the blue "Debug" link.
6. A new window will open in a minute, and click the "console" tab

To retrieve the console.log() output from the Raptor content 'measure.js' code:

1. As soon as Raptor opens the new test tab (and the test starts running / or the page starts loading), in Firefox just choose "Tools => Web Developer => Web Console", and select the "console' tab.

Raptor automatically closes the test tab and the entire browser after test completion; which will close any open debug consoles. In order to have more time to review the console logs, Raptor can be temporarily hacked locally in order to prevent the test tab and browser from being closed. Currently this must be done manually, as follows:

1. In the Raptor web extension runner, comment out the line that closes the test tab in the test clean-up. That line of code is here.
2. Add a return statement at the top of the Raptor control server method that shuts-down the browser, the browser shut-down method is here.

For benchmark type tests (i.e. speedometer, motionmark, etc.) Raptor doesn't inject 'measure.js' into the test page content; instead it injects 'benchmark-relay.js' into the benchmark test content. Benchmark-relay is as it sounds; it basically relays the test results coming from the benchmark test, to the Raptor web extension runner. Viewing the console.log() output from benchmark-relay is done the same was as noted for the 'measure.js' content above.

Note, Bug 1470450 is on file to add a debug mode to Raptor that will automatically grab the web extension console output and dump it to the terminal (if possible) that will make debugging much easier.

Debugging TP6 and Killing the Mitmproxy Server

Regarding debugging Raptor pageload tests that use Mitmproxy (i.e. tp6, gdocs). If Raptor doesn't finish naturally and doesn't stop the Mitmproxy tool, the next time you attempt to run Raptor it might fail out with this error:

    INFO -  Error starting proxy server: OSError(48, 'Address already in use')
    INFO -  raptor-mitmproxy Aborting: mitmproxy playback process failed to start, poll returned: 1

That just means the Mitmproxy server was already running before so it couldn't startup. In this case, you need to kill the Mitmproxy server processes, i.e:

    mozilla-unified rwood$ ps -ax | grep mitm
    5439 ttys000    0:00.09 /Users/rwood/mozilla-unified/obj-x86_64-apple-darwin17.7.0/testing/raptor/mitmdump -k -q -s /Users/rwood/mozilla-unified/testing/raptor/raptor/playback/alternate-server-replay.py /Users/rwood/mozilla-unified/obj-x86_64-apple-darwin17.7.0/testing/raptor/amazon.mp
    5440 ttys000    0:01.64 /Users/rwood/mozilla-unified/obj-x86_64-apple-darwin17.7.0/testing/raptor/mitmdump -k -q -s /Users/rwood/mozilla-unified/testing/raptor/raptor/playback/alternate-server-replay.py /Users/rwood/mozilla-unified/obj-x86_64-apple-darwin17.7.0/testing/raptor/amazon.mp
    5509 ttys000    0:00.01 grep mitm

Then just kill the first mitm process in the list and that's sufficient:

    mozilla-unified rwood$ kill 5439

Now when you run Raptor again, the Mitmproxy server will be able to start.

Manual Debugging on Firefox Android

Be sure to read the above section first on how to debug the Raptor web extension when running on Firefox Desktop.

When running Raptor tests on Firefox on Android (i.e. geckoview), to see the console.log() output from the Raptor web extension, do the following:

1. With your android device (i.e. Google Pixel 2) all set up and connected to USB, invoke the Raptor test normally via ./mach raptor
2. Start up a local copy of the Firefox Nightly Desktop browser
3. In Firefox Desktop choose "Tools => Web Developer => WebIDE"
4. In the Firefox WebIDE dialog that appears, look under "USB Devices" listed on the top right. If your device is not there, there may be a link to install remote device tools - if that link appears click it and let that install.
5. Under "USB Devices" on the top right your android device should be listed (i.e. "Firefox Custom on Android Pixel 2" - click on your device.
6. The debugger opens. On the left side click on "Main Process", and click the "console" tab below - and the Raptor runner output will be included there.
7. On the left side under "Tabs" you'll also see an option for the active tab/page; select that and the Raptor content console.log() output should be included there.

Also note: When debugging Raptor on Android, the 'adb logcat' is very useful. More specifically for 'geckoview', the output (including for Raptor) is prefixed with "GeckoConsole" - so this command is very handy:

    adb logcat | grep GeckoConsole

Manual Debugging on Google Chrome

Same as on Firefox desktop above, but use the Google Chrome console: View ==> Developer ==> Developer Tools.

Raptor on Mobile projects (Fenix, Reference-Browser)

Add new tests

For mobile projects, Raptor tests are on the following repositories:

Project	Repository	Tests results	Schedule
Fenix (aka Firefox Preview)	Github	Treeherder view	Every 24 hours Taskcluster force hook
Reference-Browser	Github	Treeherder view	On each push

Tests are now defined in a similar fashion compared to what exists in mozilla-central. Task definitions are expressed in Yaml:

• https://github.com/mozilla-mobile/fenix/blob/1c9c5317eb33d92dde3293dfe6a857c279a7ab12/taskcluster/ci/raptor/kind.yml
• https://github.com/mozilla-mobile/reference-browser/blob/4560a83cb559d3d4d06383205a8bb76a44336704/taskcluster/ci/raptor/kind.yml

If you want to test your changes on a PR, before they land, you need to apply a patch like this one: https://github.com/mozilla-mobile/fenix/pull/5565/files. Don't forget to revert it before merging the patch.

On Fenix and Reference-Browser, the raptor revision is tied to the latest nightly of mozilla-central

For more information, please reach out to :jlorenzo or :mhentges in #cia

Code formatting on Raptor

As Raptor is a Mozilla project we fallow the general Python coding style:

• https://firefox-source-docs.mozilla.org/tools/lint/coding-style/coding_style_python.html

blackis the tool used to reformat the Python code.