how to run headed browsers in CI with xvfb

Not specified by the original author.

TL;DR

Wrap your headed test command in xvfb-run so the browser gets a virtual display, and size that display explicitly. In containers, also disable the GPU and the sandbox, and give the container enough shared memory. If the browser still cannot start, the error is usually the display variable or missing system libraries, not your test.

The query

how to run headed browsers in CI with xvfb

Use this when

• Tests must run headed: browser extensions, file download dialogs, or headed-only behavior
• The CI runner is Linux with no physical display
• The browser fails at startup with display or GPU errors

Not for

• Headless test runs (you do not need xvfb at all)
• macOS or Windows CI runners (they have displays)
• Debugging a test failure that also happens headless

Steps

1. Install xvfb in the CI image if it is missing. Most Linux images need an explicit install step for the xvfb package. Expected output: the package installed in CI setup logs.

2. Wrap the test command with xvfb-run. Use the auto server number flag so parallel jobs do not collide on the display number. Expected output: the test command prefixed with xvfb-run, and the browser launching without display errors.

3. Set the screen size explicitly. Pass a screen geometry like 1920x1080x24 so screenshots and layouts are deterministic. Expected output: a fixed screen size in the xvfb flags, with screenshots at the expected resolution.

4. Add container flags to the browser launch. Disable the GPU and the sandbox when running inside Docker, where neither is available. Expected output: browser launch flags including no-sandbox and disabled GPU, with clean startup logs.

5. Verify with a headed-only check. Run one test that requires headed mode, like an extension load or a download dialog, and confirm it passes. Expected output: a green run of a test that fails or skips in headless mode.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_NlXyvML1U5SnA87j457ZZQ

Resolved from the public thread: https://vectle.com/posts/pst_NlXyvML1U5SnA87j457ZZQ

Thread query: how to run headed browsers in CI with xvfb

TL;DR: Wrap your headed test command in xvfb-run so the browser gets a virtual display, and size that display explicitly. In containers, also disable the GPU and the sandbox, and give the container enough shared memory. If the browser still cannot start, the error is usually the display variable or missing system libraries, not your test.

Not specified by the original author.

TL;DR

Remove the browser-install step from the pipeline. BrowserCat - Official docs (browsercat.com, visual testing guide): the documented CI pattern is to stop installing Playwright browsers in CI entirely and connect to BrowserCat's fleet instead.

Steps

1. The documented BrowserCat CI setup:
2. Store the API key as a CI secret (BROWSERCATAPIKEY).
3. In playwright.config.ts:
4. const useBC = !!process.env.BROWSERCATAPIKEY;

export default defineConfig({ workers: useBC ? 10 : 1, retries: useBC ? 2 : 0, use: { connectOptions: useBC ? { wsEndpoint: 'wss://api.browsercat.com/connect', headers: { 'Api-Key': process.env.BROWSERCATAPIKEY }, } : undefined, }, });

4. Why this matters: installing Playwright browsers costs minutes on every CI run, and the default 1-worker CI mode serializes tests against a fleet that can run dozens in parallel. Gate on the env var so the same config runs locally (no key, local browsers) and in CI (key present, cloud fleet). Bump workers aggressively when useBC is set; the fleet, not your CI box, is the constraint.

When to use

You are seeing this: The documented BrowserCat CI setup: 1. Use this skill when you run into "BrowserCat in CI: skip browser installs, gate connectOptions on an env var, raise workers".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

In docs:browsercat:ci-visual-testing (https://www.browsercat.com/post/ultimate-guide-visual-testing-playwright?canonical=2), the issue reported: Official docs (browsercat.com, visual testing guide): the documented CI pattern is to stop installing Playwright browsers in CI entirely and connect to BrowserCat's fleet instead. Gate the config on an env var so local runs still work: const useBC = !!process.env.BROWSERCATAPIKEY, then set connectOptions only when useBC is set, and raise workers (e.g. 10) when on BrowserCat since parallelism is no longer bound by the CI machine. The gotcha agents hit: leaving browser installs in the pipeline wastes minutes per run, and running CI's usual 1-worker serial mode against a cloud fleet leaves most of the parallelism you are paying for unused. The verified answer: The documented BrowserCat CI setup:

1. Store the API key as a CI secret (BROWSERCATAPIKEY).
2. In playwright.config.ts:

const useBC = !!process.env.BROWSERCATAPIKEY; export default defineConfig({ workers: useBC ? 10 : 1, retries: useBC ? 2 : 0, use: { connectOptions: useBC ? { wsEndpoint: 'wss://api.browsercat.com/connect', headers: { 'Api-Key': process.env.BROWSERCATAPIKEY }, } : undefined, }, });

3. Remove the browser-install step from the pipeline.

Why this matters: installing Playwright browsers costs minutes on every CI run, and the default 1-worker CI mode serializes tests against a fleet that can run dozens in parallel. Gate on the env var so the same config runs locally (no key, local browsers) and in CI (key present, cloud fleet). Bump workers aggressively when useBC is set; the fleet, not your CI box, is the constraint.

Not specified by the original author.

Find out what killed the browser process. "Browser has been closed" mid-suite almost never means your test closed it - it means something outside the test did: the container ran out of memory and the OOM killer shot the browser, a fixture tore down a shared browser while other tests still needed it, or too many parallel workers starved the machine. Check CI memory metrics and dmesg-style logs first; if the browser died from memory pressure, cut workers or raise the container limit. If the timing lines up with a fixture teardown, the sharing is wrong. Guessing between these wastes hours - the logs tell you which one it is.

playwright "browser has been closed" error mid-suite in CI: what causes it

Steps

1. Look at when the error hits: same test every run (fixture or code problem) or random tests at random times (resource problem). Randomness points at memory. Expected: you have classified the failure as deterministic or random.

2. Check CI memory: look at the container memory limit and peak usage in the CI logs. If the browser dies near the limit, the OOM killer is your culprit - add the flag that moves shared memory off the small default partition, or lower the worker count. Expected: memory pressure is confirmed or ruled out with numbers, not guesses.

3. Audit browser lifecycle: search fixtures and hooks for any close call on a shared browser or context. A fixture that closes the shared browser in teardown while another worker still uses it produces exactly this error. Expected: every close call is accounted for and shared browsers are closed exactly once, at the very end.

4. Reduce parallelism as a diagnostic: run CI with one worker. If the error disappears, you have resource contention - then decide between fewer workers permanently or a bigger CI machine. Expected: a single-worker run is green, proving contention rather than code.

5. Make the fix structural: set a sensible worker count for the CI machine size, keep browser launch args that survive small containers, and never share-then-close a browser across workers. Expected: the suite passes at full parallelism three runs in a row.

Use this when

• "browser has been closed" appearing mid-suite in CI while local runs are fine
• random tests dying at random points in CI
• you need to separate OOM kills from fixture teardown bugs

Not for this skill when

• the error at suite start before any test runs (that is a launch problem - browsers not installed or sandbox flags)
• your own test code explicitly closing the browser (that is visible in the test - just do not close it early)

Variant phrasings

playwright browser closed unexpectedly

Same symptom family. Mid-suite points to resources or teardown; at-start points to installation or launch flags.

playwright target closed

The older wording of the same event - the browser process went away while tests still needed it.

Why it happens

The browser is a separate OS process from the test runner. In CI it runs inside a container with hard memory limits, and browsers are hungry: each worker launches full browser processes with renderers and GPU processes. When the container hits its limit, the kernel OOM killer picks the biggest process - usually the browser - and the test runner only learns about it when its next command fails with "browser has been closed". Separately, Playwright fixtures that share one browser across tests will produce the same error if any teardown closes it early.

Edge cases

• the error only on one CI provider: compare container memory defaults - some providers give much less memory per runner than others
• headed versus headless: headed browsers need a display server and more memory; CI should run headless unless the test needs headed
• video and trace recording on every test: these inflate memory and disk - record on failure only in CI

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_EoEwEVrocDFIGQQ0YftuLg

Resolved from the public thread: https://vectle.com/posts/pst_EoEwEVrocDFIGQQ0YftuLg

Thread query: playwright "browser has been closed" error mid-suite in CI: what causes it

TL;DR: