0cad4a198e3e0716034c3e865dda41eba0980047
[WebKit-https.git] / 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
9 │   ├── __init__.py
10 │   ├── benchmark_builder_factory.py
11 │   ├── benchmark_builders.json
12 │   ├── generic_benchmark_builder.py
13 │   └── jetstream_benchmark_builder.py
14 ├── benchmark_runner.py
15 ├── browser_driver
16 │   ├── __init__.py
17 │   ├── browser_driver.py
18 │   ├── browser_driver_factory.py
19 │   ├── browser_drivers.json
20 │   ├── osx_chrome_driver.py
21 │   └── osx_safari_driver.py
22 ├── data
23 │   ├── patches
24 │   │   ├── JetStream.patch
25 │   │   └── Speedometer.patch
26 │   └── plans
27 │       ├── jetstream.plan
28 │       └── speedometer.plan
29 ├── generic_factory.py
30 ├── http_server_driver
31 │   ├── __init__.py
32 │   ├── http_server
33 │   │   └── twisted_http_server.py
34 │   ├── http_server_driver.py
35 │   ├── http_server_driver_factory.py
36 │   ├── http_server_drivers.json
37 │   └── simple_http_server_driver.py
38 └── utils.py
39 ```
40 ## Requirements
41 * python modules:
42     * PyObjc
43     * psutils (optional)
44
45 ## HOW TOs
46 ### How to run
47 ```shell
48     python path/to/run-benchmark --build-directory path/to/browser/directory --plan json_format_plan --platform target_platform --browser target_browser
49 ```
50 * **path/to/browser/directory**: should be the folder containing the executable binary(e.g. /Application/ on OSX which contains Safari.app)
51 * **json_format_plan**: the benchmark plan you want to execute  
52
53 ### How to create a plan
54 To create a plan, you may refer to Plans/jetstream.plan.
55 ```json 
56 {
57     "http_server_driver": "SimpleHTTPServerDriver", 
58     "timeout" : 600,
59     "count": 5,
60     "benchmark_builder": "JetStreamBenchmarkBuilder",
61     "original_benchmark": "../../../../PerformanceTests/JetStream",
62     "benchmark_patch": "data/patches/JetStream.patch",
63     "entry_point": "JetStream/JetStream-1.0.1/index.html",
64     "output_file": "jetstream.result"
65 }
66 ```
67 Plan is a json-formatted dictionary which contains following keys 
68 * **http_server_driver**: (**case-sensitive**) the http server module you want to host the resources. Current available option is "SimpleHTTPServerHandle" which is based on python twisted framework.
69 * **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.
70 * **count**: the number of times you want to run benchmark
71 * **benchmark_builder**:  builder of the benchmark which is responsible for arranging benchmark before the web server serving the directory. In most case, 'GenericBenchmarkHandler' is sufficient. It copies the benchmark to a temporary directory and applies patch to benchmark. If you have special requirement, you could design your own benchmark handle, just like the 'JetStreamBenchmarkHandle' in this example.
72 * **original_benchmark**: path of benchmark, a relative path to the root of this project ('benchmark_runner' directory)
73 * **benchmark_path**: (**OPTIONAL**) path of patch, a relative path to the root of this project ('benchmark_runner' directory)
74 * **entry_point**: the relative url you want browser to launch (a relative path to the webRoot)
75 * **output_file**: specify the output file, this can be overwritten by specifying '--output-file' while invoking run-benchmark script
76
77 ### How to import a benchmark
78 * Modify the benchmark html file, make sure the page has following functionalities:
79     * When you launch the page('entry_point' in benchmark), the test will start automatically
80     * Organizing the results
81     * 'POST' information to '/report', and 'GET' '/shutdown' when post succeeds. Example:
82     * ```js
83       var xhr = new XMLHttpRequest();
84       xhr.open("POST", "/report");
85       xhr.setRequestHeader("Content-type", "application/json");
86       xhr.setRequestHeader("Content-length", results.length);
87       xhr.setRequestHeader("Connection", "close");
88       xhr.onreadystatechange = function() {
89           if(xhr.readyState == 4 && xhr.status == 200) {
90               var closeRequest = new XMLHttpRequest();
91               closeRequest.open("GET", '/shutdown');
92               closeRequest.send()
93           }
94       }
95       xhr.send(results);
96 ``` 
97 * Create a patch file against original file
98     * Go to the directory contains the benchmark directory (e.g. for JetStream, you should go to PerformaceTest folder)
99     * Use ```git diff --relative HEAD > your.patch``` to create your patch
100     * (**Suggested**) move the patch to the 'Patches' directory under project directory
101 * Create a plan for the benchmark (refer to **"How to create a plan"** for more details)
102 * Do following instruction **ONLY IF NEEDED**. In most case, you do not have to.
103     * 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.
104     * 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.
105     * If you want to customize BenchmarkBuilder, you need to extend benchmark_builder/generic_benchmark_builder register you module in benchmark_builder/benchmark_builders.json