Heuristic:Puppeteer Puppeteer Chrome Default Launch Arguments
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Configuration |
| Last Updated | 2026-02-11 23:30 GMT |
Overview
Puppeteer launches Chrome with 30+ default command-line flags that disable non-essential features for reliable automation, including workarounds for known Chromium bugs.
Description
The `ChromeLauncher.defaultArgs()` method constructs a carefully curated list of Chrome command-line flags optimized for automation reliability. These flags disable features that interfere with automated testing (sync, default apps, crash reporting, phishing detection) and enable features needed for Puppeteer functionality (PDF out-of-process iframes, tagged PDF export). Several flags are explicit workarounds for known Chromium bugs, referenced by `crbug.com` issue numbers in the source code.
Usage
Apply this heuristic when launching Chrome for automation. The default arguments are designed to create a stable, predictable automation environment. When users encounter unexpected Chrome behavior during automation, the first check should be whether `ignoreDefaultArgs` was set (which removes these protections). Use `ignoreDefaultArgs` as an array to selectively remove specific flags rather than removing all defaults.
The Insight (Rule of Thumb)
- Action: Let Puppeteer use its default Chrome flags. Only override specific flags using `ignoreDefaultArgs: ['--flag-to-remove']` instead of `ignoreDefaultArgs: true`.
- Value: 30+ flags covering performance, stability, and workarounds for 6+ Chromium bugs.
- Trade-off: Default args disable features like sync, extensions, and component updates which may be needed for specific testing scenarios.
- Key Flags:
- `--disable-dev-shm-usage` — Prevents Chrome crashes in Docker/CI where `/dev/shm` is small
- `--disable-background-timer-throttling` — Prevents JS timers from being slowed in background tabs
- `--disable-renderer-backgrounding` — Keeps renderer processes active when not focused
- `--force-color-profile=srgb` — Ensures consistent color rendering across platforms
- `--headless=new` — Modern headless mode (or `--headless` for shell mode)
Reasoning
Chrome is designed for interactive use and includes many features (sync, phishing detection, crash reporting) that interfere with automation. Without these flags:
- Background tabs would throttle JavaScript timers, causing timeout flakes
- Chrome would attempt network requests for syncing, extension updates, and translation
- `/dev/shm` exhaustion in Docker would crash Chrome
- Color rendering differences across platforms would cause visual regression failures
Disabled Chrome Features and Their Bug References:
- `Translate` — Interferes with page content
- `AcceptCHFrame` — crbug.com/1348106
- `RenderDocument` — crbug.com/444150315
- `ProcessPerSiteUpToMainFrameThreshold` — crbug.com/1492053
- `IsolateSandboxedIframes` — puppeteer/puppeteer#10715
- `MediaRouter`, `OptimizationHints` — Unnecessary for automation
Enabled Chrome Feature:
- `PdfOopif` — Required for PDF generation in out-of-process iframes
// From ChromeLauncher.ts:208-239
const chromeArguments = [
'--allow-pre-commit-input',
'--disable-background-networking',
'--disable-background-timer-throttling',
'--disable-backgrounding-occluded-windows',
'--disable-breakpad',
'--disable-client-side-phishing-detection',
'--disable-component-extensions-with-background-pages',
'--disable-crash-reporter',
'--disable-default-apps',
'--disable-dev-shm-usage',
'--disable-hang-monitor',
'--disable-infobars',
'--disable-ipc-flooding-protection',
'--disable-popup-blocking',
'--disable-prompt-on-repost',
'--disable-renderer-backgrounding',
'--disable-search-engine-choice-screen',
'--disable-sync',
'--enable-automation',
'--export-tagged-pdf',
'--force-color-profile=srgb',
'--generate-pdf-document-outline',
'--metrics-recording-only',
'--no-first-run',
'--password-store=basic',
'--use-mock-keychain',
];