Tools/Scripts/webkitpy/benchmark_runner/README.md

   1 # Benchmark Runner
   2 This is a script for automating the browser based benchmarks(e.g. Speedometer, JetStream)
   3 ## Project Structure
   4 ```
   5 benchmark_runner
   6 ├── README.md
   7 ├── __init__.py
   8 ├── benchmark_builder.py
   9 ├── benchmark_results.py
  10 ├── benchmark_results_unittest.py
  11 ├── benchmark_runner.py
  12 ├── browser_driver
  13 │   ├── __init__.py
  14 │   ├── browser_driver.py
  15 │   ├── browser_driver_factory.py
  16 │   ├── osx_browser_driver.py
  17 │   ├── osx_chrome_driver.py
  18 │   ├── osx_firefox_driver.py
  19 │   └── osx_safari_driver.py
  20 ├── data
  21 │   ├── patches
  22 │   │   ├── Dromaeo.patch
  23 │   │   ├── JSBench.patch
  24 │   │   ├── JetStream.patch
  25 │   │   ├── Kraken.patch
  26 │   │   ├── Octane.patch
  27 │   │   ├── Speedometer.patch
  28 │   │   └── SunSpider.patch
  29 │   └── plans
  30 │       ├── dromaeo-cssquery.plan
  31 │       ├── dromaeo-dom.plan
  32 │       ├── dromaeo-jslib.plan
  33 │       ├── jetstream.plan
  34 │       ├── jsbench.plan
  35 │       ├── kraken.plan
  36 │       ├── octane.plan
  37 │       ├── speedometer.plan
  38 │       └── sunspider.plan
  39 ├── generic_factory.py
  40 ├── http_server_driver
  41 │   ├── __init__.py
  42 │   ├── http_server
  43 │   │   └── twisted_http_server.py
  44 │   ├── http_server_driver.py
  45 │   ├── http_server_driver_factory.py
  46 │   └── simple_http_server_driver.py
  47 ├── run_benchmark.py
  48 └── utils.py
  49 ```
  50 ## Requirements
  51 * python modules:
  52     * PyObjc
  53     * psutils (optional)
  54
  55 ## HOW TOs
  56 ### How to run
  57 ```shell
  58     python path/to/run-benchmark --build-directory path/to/browser/directory --plan json_format_plan --platform target_platform --browser target_browser
  59 ```
  60 * **path/to/browser/directory**: should be the folder containing the executable binary(e.g. /Application/ on OSX which contains Safari.app)
  61 * **json_format_plan**: the benchmark plan you want to execute
  62
  63 ### How to create a plan
  64 To create a plan, you may refer to Plans/jetstream.plan.
  65 ```json
  66 {
  67     "timeout" : 600,
  68     "count": 5,
  69     "local_copy": "../../../../PerformanceTests/JetStream",
  70     "benchmark_patch": "data/patches/JetStream.patch",
  71     "entry_point": "JetStream/JetStream-1.0.1/index.html",
  72     "output_file": "jetstream.result"
  73 }
  74 ```
  75 Plan is a json-formatted dictionary which contains following keys
  76 * **timeout**: time limit for **EACH RUN** of the benchmark. This can avoid program getting stuck in the extreme circumstances. The time limit is suggested to be 1.5-2x the time spent in a normal run.
  77 * **count**: the number of times you want to run benchmark
  78 * **local_copy**: (**OPTIONAL**) Path of benchmark, a relative path to the root of this project ('benchmark_runner' directory)
  79 * **remote_archive**: (**OPTIONAL**) URL of the remote (http/https) ZIP file that contains the benchmark.
  80 * **benchmark_path**: (**OPTIONAL**) path of patch, a relative path to the root of this project ('benchmark_runner' directory)
  81 * **entry_point**: the relative url you want browser to launch (a relative path to the benchmark directory)
  82 * **output_file**: specify the output file, this can be overwritten by specifying '--output-file' while invoking run-benchmark script
  83
  84 ### How to import a benchmark
  85 * Modify the benchmark html file, make sure the page has following functionalities:
  86     * When you launch the page('entry_point' in benchmark), the test will start automatically
  87     * Organizing the results
  88     * 'POST' information to '/report', and 'GET' '/shutdown' when post succeeds. Example:
  89     * ```js
  90       var xhr = new XMLHttpRequest();
  91       xhr.open("POST", "/report");
  92       xhr.setRequestHeader("Content-type", "application/json");
  93       xhr.setRequestHeader("Content-length", results.length);
  94       xhr.setRequestHeader("Connection", "close");
  95       xhr.onreadystatechange = function() {
  96           if(xhr.readyState == 4 && xhr.status == 200) {
  97               var closeRequest = new XMLHttpRequest();
  98               closeRequest.open("GET", '/shutdown');
  99               closeRequest.send()
 100           }
 101       }
 102       xhr.send(results);
 103 ```
 104 * Create a patch file against original file
 105     * Go to the directory contains the benchmark directory (e.g. for JetStream, you should go to PerformaceTest folder)
 106     * Use ```git diff --relative HEAD > your.patch``` to create your patch
 107     * (**Suggested**) move the patch to the 'Patches' directory under project directory
 108 * Create a plan for the benchmark (refer to **"How to create a plan"** for more details)
 109 * Do following instruction **ONLY IF NEEDED**. In most case, you do not have to.
 110     * If you want to customize BrowserDriver for specific browser/platform, you need to extend browser_driver/browser_driver.py and register your module in browser_driver/browser_driversjson.
 111     * If you want to customize HTTPServerDriver, you need to extend http_server_drirver/http_server_driver and register your module in http_server_driver/http_server_drivers.json.