Heuristic:Getgauge Taiko Browser Launch Flags
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Optimization |
| Last Updated | 2026-02-12 03:00 GMT |
Overview
Chrome launch flag recommendations for headless testing, Docker containers, CI pipelines, and parallel execution scenarios.
Description
Taiko launches Chrome with a carefully curated set of default flags that disable unnecessary features (sync, updates, crash reporting) and enable automation-friendly behavior. Additional flags are needed for Docker/CI environments where the sandbox is unavailable, shared memory is limited, or tests run in parallel. These flags are passed via the `TAIKO_BROWSER_ARGS` environment variable or the `args` option in `openBrowser()`.
Usage
Apply this heuristic when configuring Taiko for CI/CD pipelines, Docker containers, or parallel test execution. Also useful when debugging Chrome launch failures or optimizing browser startup time.
The Insight (Rule of Thumb)
- For Docker / CI:
- `--no-sandbox` — Required when running as root or in restricted environments
- `--disable-dev-shm-usage` — Prevents crashes from 64MB /dev/shm limit
- `--disable-gpu` — No GPU available in most CI environments
- For Parallel Execution (Cloud):
- All Docker flags plus:
- `--disable-setuid-sandbox` — Sandbox not available
- `--no-first-run` — Skip first-run experience
- `--no-zygote` — Disable zygote process forking
- For Headless Mode:
- Default window size is `--window-size=1440,900`
- Override with custom size via `TAIKO_BROWSER_ARGS`
- Trade-off: `--no-sandbox` reduces security isolation. Only use in trusted environments (CI, Docker). Never use with untrusted content.
Reasoning
Why disable site-per-process? The `--disable-features=site-per-process` flag is set because Taiko manages CDP connections at the page level, and site isolation creates separate renderer processes that complicate frame management.
Why force sRGB? The `--force-color-profile=srgb` flag ensures consistent screenshot colors across machines with different display profiles.
Why /dev/shm matters: Chrome uses `/dev/shm` for sharing rendering data between processes. Docker's default 64MB is insufficient for complex pages, causing tab crashes with "session deleted because of page crash" errors.
Why --bwsi and --browser-test? `--bwsi` (Browse Without Sign In) and `--browser-test` enable a clean, automation-friendly Chrome state without user profile interference.
Code Evidence
Default Chrome flags from `lib/browser/launcher.js:268-291`:
let args = [
`--remote-debugging-port=${options.port}`,
"--disable-features=site-per-process,TranslateUI",
"--enable-features=NetworkService,NetworkServiceInProcess",
"--disable-renderer-backgrounding",
"--disable-backgrounding-occluded-windows",
"--disable-background-timer-throttling",
"--disable-background-networking",
"--disable-breakpad",
"--disable-default-apps",
"--disable-hang-monitor",
"--disable-prompt-on-repost",
"--disable-sync",
"--force-color-profile=srgb",
"--safebrowsing-disable-auto-update",
"--password-store=basic",
"--use-mock-keychain",
"--enable-automation",
"--disable-notifications",
"--no-first-run",
"--bwsi",
"--browser-test",
"about:blank",
];
TAIKO_BROWSER_ARGS parsing from `lib/browser/launcher.js:21-26`:
const envArgs = process.env.TAIKO_BROWSER_ARGS
? process.env.TAIKO_BROWSER_ARGS.split(/\s*,?\s*--/)
.filter((arg) => arg !== "")
.map((arg) => `--${arg}`)
: [];
Headless window size from `lib/browser/launcher.js:29-35`:
function setHeadlessArgs(args, options) {
if (options.headless) {
args.push("--headless");
if (!args.some((arg) => arg.startsWith("--window-size"))) {
args.push("--window-size=1440,900");
}
}
}