cli: update documented throttling flags (GoogleChrome#5000)

FreddyPeng · Apr 20, 2018 · 70f9ecc · 70f9ecc
1 parent 8ae7e48
commit 70f9ecc
Show file tree

Hide file tree

Showing 7 changed files with 27 additions and 18 deletions.
diff --git a/docs/readme.md b/docs/readme.md
@@ -76,7 +76,7 @@ instance with an open debugging port.
 
 Lighthouse can run against a real mobile device. You can follow the [Remote Debugging on Android (Legacy Workflow)](https://developer.chrome.com/devtools/docs/remote-debugging-legacy) up through step 3.3, but the TL;DR is install & run adb, enable USB debugging, then port forward 9222 from the device to the machine with Lighthouse.
 
-You'll likely want to use the CLI flags `--disable-device-emulation --disable-cpu-throttling` and potentially `--disable-network-throttling`.
+You'll likely want to use the CLI flags `--disable-device-emulation --throttling.cpuSlowdownMultiplier`.
 
 ```sh
 $ adb kill-server
@@ -88,7 +88,7 @@ $ adb devices -l
 
 $ adb forward tcp:9222 localabstract:chrome_devtools_remote
 
-$ lighthouse --port=9222 --disable-device-emulation --disable-cpu-throttling https://example.com
+$ lighthouse --port=9222 --disable-device-emulation --throttling.cpuSlowdownMultiplier=1 https://example.com
 ```
 
 ## Lighthouse as trace processor

diff --git a/docs/throttling.md b/docs/throttling.md
@@ -49,8 +49,8 @@ Currently, `comcast` will also throttle the websocket port that Lighthouse uses
 # Enable system traffic throttling
 comcast --latency=150 --target-bw=1600
 
-# Run Lighthouse with it's own throttling disabled
-lighthouse --disable-network-throttling # ...
+# Run Lighthouse with its own throttling disabled
+lighthouse --throttling.requestLatencyMs=0 --throttling.downloadThroughputKbps=0 --throttling.uploadThroughputKbps=0 # ...
 
 # Disable the traffic throttling once you see "Retrieving trace"
 comcast --stop

diff --git a/lighthouse-cli/cli-flags.js b/lighthouse-cli/cli-flags.js
@@ -33,8 +33,8 @@ function getFlags(manualArgv) {
           'lighthouse <url> --output=json --output-path=./report.json --save-assets',
           'Save trace, screenshots, and named JSON report.')
       .example(
-          'lighthouse <url> --disable-device-emulation --disable-network-throttling',
-          'Disable device emulation')
+          'lighthouse <url> --disable-device-emulation --throttling-method=provided',
+          'Disable device emulation and all throttling')
       .example(
           'lighthouse <url> --chrome-flags="--window-size=412,732"',
           'Launch Chrome with a specific window size')
@@ -70,8 +70,13 @@ function getFlags(manualArgv) {
         'disable-storage-reset':
             'Disable clearing the browser cache and other storage APIs before a run',
         'disable-device-emulation': 'Disable Nexus 5X emulation',
-        'disable-cpu-throttling': 'Disable CPU throttling',
-        'disable-network-throttling': 'Disable network throttling',
+        'throttling-method': 'Controls throttling method',
+        'throttling.rttMs': 'Controls simulated network RTT (TCP layer)',
+        'throttling.throughputKbps': 'Controls simulated network download throughput',
+        'throttling.requestLatencyMs': 'Controls emulated network RTT (HTTP layer)',
+        'throttling.downloadThroughputKbps': 'Controls emulated network download throughput',
+        'throttling.uploadThroughputKbps': 'Controls emulated network upload throughput',
+        'throttling.cpuSlowdownMultiplier': 'Controls simulated + emulated CPU throttling',
         'gather-mode':
             'Collect artifacts from a connected browser and save to disk. (Artifacts folder path may optionally be provided). If audit-mode is not also enabled, the run will quit early.',
         'audit-mode': 'Process saved artifacts from disk. (Artifacts folder path may be provided, otherwise defaults to ./latest-run/)',
@@ -111,12 +116,12 @@ function getFlags(manualArgv) {
 
       // boolean values
       .boolean([
-        'disable-storage-reset', 'disable-device-emulation', 'disable-cpu-throttling',
-        'disable-network-throttling', 'save-assets', 'list-all-audits',
+        'disable-storage-reset', 'disable-device-emulation', 'save-assets', 'list-all-audits',
         'list-trace-categories', 'perf', 'view', 'verbose', 'quiet', 'help',
         'mixed-content',
       ])
       .choices('output', printer.getValidOutputOptions())
+      .choices('throttling-method', ['devtools', 'provided', 'simulate'])
       // force as an array
       // note MUST use camelcase versions or only the kebab-case version will be forced
       .array('blockedUrlPatterns')

diff --git a/lighthouse-cli/test/smokehouse/smokehouse.js b/lighthouse-cli/test/smokehouse/smokehouse.js
@@ -66,7 +66,7 @@ function runLighthouse(url, configPath, isDebug) {
   if (process.env.APPVEYOR) {
     // Appveyor is hella slow already, disable CPU throttling so we're not 16x slowdown
     // see https://github.com/GoogleChrome/lighthouse/issues/4891
-    args.push('--disable-cpu-throttling');
+    args.push('--throttling.cpuSlowdownMultiplier=1');
   }
 
   // Lighthouse sometimes times out waiting to for a connection to Chrome in CI.

diff --git a/package.json b/package.json
@@ -51,7 +51,7 @@
     "devtools": "bash lighthouse-core/scripts/roll-to-devtools.sh",
     "compile-devtools": "bash lighthouse-core/scripts/compile-against-devtools.sh",
     "chrome": "node lighthouse-core/scripts/manual-chrome-launcher.js",
-    "fast": "yarn start --disable-device-emulation --disable-cpu-throttling --disable-network-throttling",
+    "fast": "yarn start --disable-device-emulation --throttlingMethod=provided",
     "smokehouse": "node lighthouse-cli/test/smokehouse/smokehouse.js",
     "deploy-viewer": "cd lighthouse-viewer && gulp deploy",
     "bundlesize": "bundlesize",

diff --git a/plots/README.md b/plots/README.md
@@ -43,8 +43,6 @@ node measure.js [options]
 
 Lighthouse settings:
   --disable-device-emulation    Disable Nexus 5X emulation                                                     [boolean]
-  --disable-cpu-throttling      Disable CPU throttling                                                         [boolean]
-  --disable-network-throttling  Disable network throttling                                                     [boolean]
 
 Options to specify sites:
   --sites-path  Include relative path of a json file with urls to run                              [default: "sites.js"]
@@ -62,4 +60,4 @@ Examples:
   node measure.js -n 3 --sites-path ./sample-sites.json
   node measure.js --site https://google.com/
   node measure.js --subset
-```
+```
diff --git a/readme.md b/readme.md
@@ -84,16 +84,22 @@ Options:
   --blocked-url-patterns        Block any network requests to the specified URL patterns                                                     [array]
   --disable-storage-reset       Disable clearing the browser cache and other storage APIs before a run                                     [boolean]
   --disable-device-emulation    Disable Nexus 5X emulation                                                                                 [boolean]
-  --disable-cpu-throttling      Disable CPU throttling                                                                    [boolean] [default: false]
-  --disable-network-throttling  Disable network throttling                                                                                 [boolean]
+  --throttling-method                  Controls throttling method         [choices: "devtools", "provided", "simulate"]
+  --throttling.rttMs                   Controls simulated network RTT (TCP layer)
+  --throttling.throughputKbps          Controls simulated network download throughput
+  --throttling.requestLatencyMs        Controls emulated network RTT (HTTP layer)
+  --throttling.downloadThroughputKbps  Controls emulated network download throughput
+  --throttling.uploadThroughputKbps    Controls emulated network upload throughput
+  --throttling.cpuSlowdownMultiplier   Controls simulated + emulated CPU throttling
   --extra-headers               Set extra HTTP Headers to pass with request                                                                 [string]
 
 Examples:
   lighthouse <url> --view                                                   Opens the HTML report in a browser after the run completes
   lighthouse <url> --config-path=./myconfig.js                              Runs Lighthouse with your own configuration: custom audits, report
                                                                             generation, etc.
   lighthouse <url> --output=json --output-path=./report.json --save-assets  Save trace, screenshots, and named JSON report.
-  lighthouse <url> --disable-device-emulation --disable-network-throttling  Disable device emulation
+  lighthouse <url> --disable-device-emulation                               Disable device emulation and all throttling.
+    --throttling-method=provided
   lighthouse <url> --chrome-flags="--window-size=412,732"                   Launch Chrome with a specific window size
   lighthouse <url> --quiet --chrome-flags="--headless"                      Launch Headless Chrome, turn off logging
   lighthouse <url> --extra-headers "{\"Cookie\":\"monster=blue\"}"          Stringify\'d JSON HTTP Header key/value pairs to send in requests