-
Notifications
You must be signed in to change notification settings - Fork 184
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(chrome-flags-for-tools): massive update and refactor (#226)
- Loading branch information
Showing
1 changed file
with
120 additions
and
137 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,147 +1,130 @@ | ||
| # Chrome Flags for Tooling | ||
|
|
||
| Many tools maintain a list of runtime flags for Chrome to configure the environment. This file | ||
| is an attempt to document all chrome flags that are relevant to tools, automation, benchmarking, etc. | ||
|
|
||
| All use cases are different, so you'll have to choose which flags are most appropriate. | ||
|
|
||
| ## Flags | ||
|
|
||
| ### `--disable-extensions` | ||
| Disable all chrome extensions. | ||
|
|
||
| ### `--disable-component-extensions-with-background-pages` | ||
| Disable some built-in extensions that aren't affected by `--disable-extensions` | ||
|
|
||
| ### `--disable-background-networking` | ||
| Disable various background network services, including extension updating, | ||
| safe browsing service, upgrade detector, translate, UMA | ||
|
|
||
| ### `--disable-sync` | ||
| Disable syncing to a Google account | ||
|
|
||
| ### `--metrics-recording-only` | ||
| Disable reporting to UMA, but allows for collection | ||
|
|
||
| ### `--disable-default-apps` | ||
| Disable installation of default apps on first run | ||
|
|
||
| ### `--mute-audio` | ||
| Mute any audio | ||
|
|
||
| ### `--no-default-browser-check` | ||
| Disable the default browser check, do not prompt to set it as such | ||
|
|
||
| ### `--no-first-run` | ||
| Skip first run wizards | ||
|
|
||
| ### `--disable-background-timer-throttling` | ||
| Disable timers being throttled in background pages/tabs | ||
|
|
||
| ### `--disable-client-side-phishing-detection` | ||
| Disables client-side phishing detection. | ||
|
|
||
| ### `--disable-popup-blocking` | ||
| Disable popup blocking. `--block-new-web-contents` is the strict version of this. | ||
|
|
||
| ### `--disable-prompt-on-repost` | ||
| Reloading a page that came from a POST normally prompts the user. | ||
|
|
||
| ### `--enable-automation` | ||
| Disable a few things considered not appropriate for automation. ([Original design doc](https://docs.google.com/a/google.com/document/d/1JYj9K61UyxIYavR8_HATYIglR9T_rDwAtLLsD3fbDQg/preview)) [codesearch](https://cs.chromium.org/search/?q=kEnableAutomation&type=cs) | ||
|
|
||
| * disables the password saving UI (which covers the usecase of the [removed](https://bugs.chromium.org/p/chromedriver/issues/detail?id=1015) `--disable-save-password-bubble` flag) | ||
| * disables infobar animations | ||
| * disables dev mode extension bubbles (?), and doesn't show some other info bars | ||
| * disables auto-reloading on network errors ([source](https://cs.chromium.org/chromium/src/chrome/renderer/net/net_error_helper_core.cc?l=917&rcl=6eaf0af71262eb876764c6237ee2fe021a3e7a18)) | ||
| * means the default browser check prompt isn't shown | ||
| * avoids showing these 3 infobars: ShowBadFlagsPrompt, GoogleApiKeysInfoBarDelegate, ObsoleteSystemInfoBarDelegate | ||
| * adds this infobar: | ||
|
|
||
|  | ||
|
|
||
| ### `--password-store=basic` | ||
| Avoid potential instability of using Gnome Keyring or KDE wallet. crbug.com/571003 | ||
|
|
||
| ### `--use-mock-keychain` | ||
| Use mock keychain on Mac to prevent blocking permissions dialogs | ||
|
|
||
| ### `--test-type` | ||
| Basically the 2014 version of `--enable-automation`. [codesearch](https://cs.chromium.org/search/?q=kTestType%5Cb&type=cs) | ||
|
|
||
| * It avoids creating application stubs in ~/Applications on mac. | ||
| * It makes exit codes slightly more correct | ||
| * windows navigation jumplists arent updated https://bugs.chromium.org/p/chromium/issues/detail?id=389375 | ||
| * doesn't start some chrome StartPageService | ||
| * disables initializing chromecast service | ||
| * "Component extensions with background pages are not enabled during tests because they generate a lot of background behavior that can interfere." | ||
| * when quitting the browser, it disables additional checks that may stop that quitting process. (like unsaved form modifications or unhandled profile notifications..) | ||
|
|
||
| ### `--disable-browser-side-navigation` | ||
| Disable PlzNavigate. | ||
|
|
||
| ## Flags to triage | ||
|
|
||
| These flags are being used in various tools. They also just need to be documented with their effects and confirmed as still present in Chrome. | ||
|
|
||
| ```sh | ||
| --process-per-tab | ||
| --new-window | ||
| --allow-running-insecure-content | ||
| --silent-debugger-extension-api | ||
|
|
||
| --disable-notifications | ||
| --disable-desktop-notifications | ||
| --disable-component-update | ||
| --disable-background-downloads | ||
| --disable-add-to-shelf | ||
| --disable-datasaver-prompt | ||
| --disable-domain-reliability | ||
| --disable-breakpad # Disable crashdump collection (reporting is already disabled in Chromium) | ||
| --disable-features=site-per-process # Disables OOPIF. https://www.chromium.org/Home/chromium-security/site-isolation | ||
| --disable-hang-monitor | ||
|
|
||
| --disable-backgrounding-occluded-windows | ||
| --disable-ipc-flooding-protection # https://crrev.com/604305 | ||
|
|
||
| --disable-renderer-backgrounding # This disables non-foreground tabs from getting a lower process priority | ||
| # This doesn't (on its own) affect timers or painting behavior. | ||
| # https://github.com/karma-runner/karma-chrome-launcher/issues/123 | ||
|
|
||
| --remote-debugging-pipe # more secure than using protocol over a websocket | ||
| --enable-logging=stderr # Logging behavior slightly more appropriate for a server-type process. | ||
| --log-level=0 # 0 means INFO and higher. | ||
| --block-new-web-contents # All pop-ups and calls to window.open will fail. | ||
| --js-flags=--random-seed=1157259157 --no-script-streaming | ||
| --autoplay-policy=user-gesture-required # Don't render video | ||
|
|
||
| --disable-dev-shm-usage # https://github.com/GoogleChrome/puppeteer/issues/1834 | ||
| --no-sandbox # often used with headless, though ideally you don't need to. | ||
|
|
||
| # Headless rendering stuff I definitely don't understand | ||
| --run-all-compositor-stages-before-draw | ||
| --disable-new-content-rendering-timeout | ||
| --enable-features=SurfaceSynchronization | ||
| --disable-threaded-animation | ||
| --disable-threaded-scrolling | ||
| --disable-checker-imaging | ||
| --disable-image-animation-resync | ||
| --use-gl="" # use angle/swiftshader? | ||
| ``` | ||
|
|
||
|
|
||
| ## Removed flags | ||
|
|
||
| ### ~`--disable-translate`~ | ||
| [Removed April 2017](https://codereview.chromium.org/2819813002/) Used to disable built-in Google Translate service. | ||
|
|
||
| ### ~`--ignore-autoplay-restrictions`~ | ||
| [Removed December 2017](https://chromium-review.googlesource.com/#/c/816855/) Can use `--autoplay-policy=no-user-gesture-required` instead. | ||
|
|
||
| ## Sources | ||
| ## Commonly unwanted browser features | ||
|
|
||
| * `--disable-client-side-phishing-detection`: Disables client-side phishing detection. | ||
| * `--disable-component-extensions-with-background-pages`: Disable some built-in extensions that aren't affected by `--disable-extensions` | ||
| * `--disable-default-apps`: Disable installation of default apps on first run | ||
| * `--disable-extensions`: Disable all chrome extensions. | ||
| * `--mute-audio`: Mute any audio | ||
| * `--no-default-browser-check`: Disable the default browser check, do not prompt to set it as such | ||
| * `--no-first-run`: Skip first run wizards | ||
|
|
||
| ## Performance & web platform behavior | ||
|
|
||
| * `--allow-running-insecure-content` | ||
| * `--autoplay-policy=user-gesture-required`: Don't render video | ||
| * `--disable-background-timer-throttling`: Disable timers being throttled in background pages/tabs | ||
| * `--disable-backgrounding-occluded-windows` | ||
| * `--disable-features=ScriptStreaming`: V8 script streaming | ||
| * `--disable-hang-monitor` | ||
| * `--disable-ipc-flooding-protection`: Some javascript functions can be used to flood the browser process with IPC. By default, protection is on to limit the number of IPC sent to 10 per second per frame. This flag disables it. https://crrev.com/604305 | ||
| * `--disable-notifications`: Disables the Web Notification and the Push APIs. | ||
| * `--disable-popup-blocking`: Disable popup blocking. `--block-new-web-contents` is the strict version of this. | ||
| * `--disable-prompt-on-repost`: Reloading a page that came from a POST normally prompts the user. | ||
| * `--disable-renderer-backgrounding`: This disables non-foreground tabs from getting a lower process priority This doesn't (on its own) affect timers or painting behavior. [karma-chrome-launcher#123](https://github.com/karma-runner/karma-chrome-launcher/issues/123) | ||
| * `--js-flags=--random-seed=1157259157`: Initialize V8's RNG with a fixed seed. | ||
|
|
||
| ## Test & debugging flags | ||
|
|
||
| * `--disable-device-discovery-notifications`: Avoid messages like "New printer on your network" | ||
| * `--enable-automation`: Disable a few things considered not appropriate for automation. ([Original design doc](https://docs.google.com/a/google.com/document/d/1JYj9K61UyxIYavR8_HATYIglR9T_rDwAtLLsD3fbDQg/preview), though renamed [here](https://codereview.chromium.org/2564973002#msg24)) [codesearch](https://cs.chromium.org/search/?q=kEnableAutomation&type=cs). Note that some projects have chosen to **avoid** using this flag: [web-platform-tests/wpt/#6348](https://github.com/web-platform-tests/wpt/pull/6348) | ||
| - disables bubble notification about running development/unpacked extensions | ||
| - disables the password saving UI (which [covers](https://source.chromium.org/chromium/chromium/src/+/master:chrome/browser/password_manager/chrome_password_manager_client.cc;l=295-298;drc=00053fb4d880a925c890193b74a8ff35e1cef2a0) the usecase of the [removed](https://bugs.chromium.org/p/chromedriver/issues/detail?id=1015) `--disable-save-password-bubble` flag) | ||
| - disables infobar animations | ||
| - disables auto-reloading on network errors ([source](https://cs.chromium.org/chromium/src/chrome/renderer/net/net_error_helper_core.cc?l=917&rcl=6eaf0af71262eb876764c6237ee2fe021a3e7a18)) | ||
| - means the default browser check prompt isn't shown | ||
| - avoids showing these 3 infobars: ShowBadFlagsPrompt, GoogleApiKeysInfoBarDelegate, ObsoleteSystemInfoBarDelegate | ||
| - adds this infobar:  | ||
| * `--enable-logging=stderr`: Logging behavior slightly more appropriate for a server-type process. | ||
| * `--log-level=0`: 0 means INFO and higher. | ||
| * `--password-store=basic`: Avoid potential instability of using Gnome Keyring or KDE wallet. crbug.com/571003 | ||
| * `--remote-debugging-pipe`: more secure than using protocol over a websocket | ||
| * `--silent-debugger-extension-api`: Does not show an infobar when a Chrome extension attaches to a page using `chrome.debugger` page. Required to attach to extension background pages. | ||
| * `--test-type`: Basically the 2014 version of `--enable-automation`. [codesearch](https://cs.chromium.org/search/?q=kTestType%5Cb&type=cs) | ||
| - It avoids creating application stubs in ~/Applications on mac. | ||
| - It makes exit codes slightly more correct | ||
| - windows navigation jumplists arent updated crbug.com/389375 | ||
| - doesn't start some chrome StartPageService | ||
| - disables initializing chromecast service | ||
| - "Component extensions with background pages are not enabled during tests because they generate a lot of background behavior that can interfere." | ||
| - when quitting the browser, it disables additional checks that may stop that quitting process. (like unsaved form modifications or unhandled profile notifications..) | ||
| * `--use-mock-keychain`: Use mock keychain on Mac to prevent blocking permissions dialogs | ||
|
|
||
| ## Background updates, networking, reporting | ||
|
|
||
| * `--disable-background-networking`: Disable various background network services, including extension updating,safe browsing service, upgrade detector, translate, UMA | ||
| * `--disable-breakpad`: Disable crashdump collection (reporting is already disabled in Chromium) | ||
| * `--disable-component-update`: Don't update the browser 'components' listed at chrome://components/ | ||
| * `--disable-domain-reliability`: Disables Domain Reliability Monitoring, which tracks whether the browser has difficulty contacting Google-owned sites and uploads reports to Google. | ||
| * `--disable-sync`: Disable syncing to a Google account | ||
| * `--enable-crash-reporter-for-testing`: Used for turning on Breakpad crash reporting in a debug environment where crash reporting is typically compiled but disabled. | ||
| * `--metrics-recording-only`: Disable reporting to UMA, but allows for collection | ||
|
|
||
| ## Rendering & GPU | ||
|
|
||
| * `--deterministic-mode`: An experimental meta flag. This sets the below indented flags which put the browser into a mode where rendering (border radius, etc) is deterministic and begin frames should be issued over DevTools Protocol. [codesearch](https://source.chromium.org/chromium/chromium/src/+/master:headless/app/headless_shell.cc;drc=df45d1abbc20abc7670643adda6d9625eea55b4d) | ||
| - `--run-all-compositor-stages-before-draw` | ||
| - `--disable-new-content-rendering-timeout` | ||
| - `--enable-begin-frame-control` | ||
| - `--disable-threaded-animation` | ||
| - `--disable-threaded-scrolling` | ||
| - `--disable-checker-imaging` | ||
| - `--disable-image-animation-resync` | ||
| * `--disable-features=PaintHolding`: Don't defer paint commits (normally used to avoid flash of unstyled content) | ||
| * `--disable-partial-raster`: crbug.com/919955 | ||
| * `--disable-skia-runtime-opts`: Do not use runtime-detected high-end CPU optimizations in Skia. | ||
| * `--in-process-gpu`: Saves some memory by moving GPU process into a browser process thread | ||
| * `--use-gl="swiftshader"`: Select which implementation of GL the GPU process should use. Options are: `desktop`: whatever desktop OpenGL the user has installed (Linux and Mac default). `egl`: whatever EGL / GLES2 the user has installed (Windows default - actually ANGLE). `swiftshader`: The SwiftShader software renderer. | ||
|
|
||
| ## Window & screen management | ||
|
|
||
| * `--block-new-web-contents`: All pop-ups and calls to window.open will fail. | ||
| * `--force-color-profile=srgb`: Force all monitors to be treated as though they have the specified color profile. | ||
| * `--force-device-scale-factor=1` | ||
| * `--new-window`: Launches URL in new browser window. | ||
| * `--window-position=0,0` | ||
| * `--window-size=1600,1024` | ||
|
|
||
| ## Process management | ||
|
|
||
| * `--disable-features=site-per-process`: Disables OOPIF. https://www.chromium.org/Home/chromium-security/site-isolation | ||
| * `--process-per-tab`: Doesn't do anything. Use --single-process instead. | ||
| * `--single-process`: Runs the renderer and plugins in the same process as the browser. | ||
|
|
||
| ## Headless | ||
|
|
||
| * `--disable-dev-shm-usage`: https://github.com/GoogleChrome/puppeteer/issues/1834 | ||
| * `--no-sandbox`: often used with headless, though ideally you don't need to. | ||
|
|
||
| # ~Removed~ flags | ||
|
|
||
| * `--disable-add-to-shelf`: [Removed June 2017](https://codereview.chromium.org/2944283002) | ||
| * `--disable-background-downloads`: [Removed Oct 2014](https://codereview.chromium.org/607843002). | ||
| * `--disable-browser-side-navigation` Disabled PlzNavigate. | ||
| * `--disable-datasaver-prompt` | ||
| * `--disable-desktop-notifications` | ||
| * `--disable-features=TranslateUI`: renamed `TranslateUI` to `Translate` in [Sept 2020](https://chromium-review.googlesource.com/c/chromium/src/+/2404484). | ||
| * `--disable-infobars`: [Removed April 2014](https://codereview.chromium.org/240193003) | ||
| * `--disable-save-password-bubble` | ||
| * `--disable-translate`: [Removed April 2017](https://codereview.chromium.org/2819813002/) Used to disable built-in Google Translate service. | ||
| * `--ignore-autoplay-restrictions`: [Removed December 2017](https://chromium-review.googlesource.com/#/c/816855/) Can use `--autoplay-policy=no-user-gesture-required` instead. | ||
| * `--safebrowsing-disable-auto-update`: [Removed Nov 2017](https://bugs.chromium.org/p/chromium/issues/detail?id=74848#c26) | ||
|
|
||
| # Sources | ||
|
|
||
| * [chrome-launcher's flags](https://github.com/GoogleChrome/chrome-launcher/blob/master/src/flags.ts) | ||
| * [Chromedriver's flags](https://cs.chromium.org/chromium/src/chrome/test/chromedriver/chrome_launcher.cc?type=cs&q=f:chrome_launcher++kDesktopSwitches&sq=package:chromium) | ||
| * [Puppeteer's flags](https://github.com/GoogleChrome/puppeteer/blob/master/lib/Launcher.js) | ||
| * [WebpageTest's flags](https://github.com/WPO-Foundation/webpagetest/blob/master/agent/wptdriver/web_browser.cc) | ||
| * [Puppeteer's flags](https://github.com/puppeteer/puppeteer/blob/main/src/node/Launcher.ts) | ||
| * [WebpageTest's flags](https://github.com/WPO-Foundation/wptagent/blob/master/internal/chrome_desktop.py) | ||
| * [Catapult's flags](https://source.chromium.org/search?q=f:catapult%20f:desktop%20symbol:GetBrowserStartupArgs&ss=chromium%2Fchromium%2Fsrc) | ||
| * [Karma's flags](https://github.com/karma-runner/karma-chrome-launcher/blob/master/index.js) | ||
|
|
||
| # All Chrome flags | ||
|
|
||
| ## All Chrome flags | ||
| * [Peter.sh's canonical list of Chrome command-line switches](http://peter.sh/experiments/chromium-command-line-switches/) |