Files
VarshithandOskar Kwaśniewski a06b931b8d fix(web): launch Chromium with its sandbox on where it can start (#1621)
* fix(web): launch Chromium with its sandbox on by default

The web engine launched Chromium without chromiumSandbox, so Playwright added --no-sandbox to every browser process. The agent can follow the app to another origin, so a renderer exploit on a page it reaches ran unsandboxed as the user running e2e run, with the checkout, .env, and model keys in reach.

Chromium now launches with chromiumSandbox: true unless the config opts out with web({ chromiumSandbox: false }) or the run environment sets E2E_CHROMIUM_SANDBOX=0, for hosts where the sandbox cannot start (root, containers, Ubuntu 23.10+ with the AppArmor user-namespace restriction). Firefox and WebKit never receive the option. The flag resolves from the option, then the run's environment, then on; the process environment never decides a launch, per the EngineInitInfo.env contract. CI opts out explicitly because the ubuntu-2404 runners restrict unprivileged user namespaces.

Docs updated next to the no-origin-allowlist note (docs/reference/web.mdx, docs/security.mdx, SECURITY.md, skills/e2e/references/setup.md) with a .changeset entry. The smol VM's --no-sandbox is unchanged: the VM is the boundary there.

Verified: pnpm check green; web unit 354/354; web integration 379 passed with 3 known load flakes that pass in isolation; testbed CLI 6/6 fail with "Chromium sandboxing failed!" by default and 6/6 pass with the opt-out on this host.

Fixes #1613

Signed-off-by: Varshith Puli <pulivarshit@gmail.com>

* docs(web): qualify chromiumSandbox coverage as local-launch-only

Cubic review on the sandbox-default PR found three doc overstatements: SECURITY.md presented the sandbox as universal while connect() and browser providers bypass launch, the skill reference omitted that E2E_CHROMIUM_SANDBOX=0 only applies when the option is omitted, and the reference page implied any container cannot run the sandbox. All three are corrected in the SECURITY note, the reference page, the option JSDoc, and both skill copies.

Signed-off-by: Varshith Puli <pulivarshit@gmail.com>

* fix(web): friendly Chromium sandbox failure and unified sandbox resolution

A sandboxed launch on a host whose sandbox cannot start failed with Playwright's raw error and its full call log, which only hints at the option. acquireBrowser now catches that one failure on a local launch and throws an ENGINE_FAILURE naming both opt-outs, E2E_CHROMIUM_SANDBOX=0 and web({ chromiumSandbox: false }), with no call log and no cause chain to leak it back.

The sandbox flag resolves in one place now: resolveChromiumSandbox(configured, env) in browser-connection.ts replaces the split readChromiumSandboxFlag plus surface resolver, and the surface keeps a single field that init resolves. BrowserConnection.acquire takes an options object, so a relaunch retries with the same options. The option JSDoc shrinks to two lines pointing at the security docs.

Tests follow the restructure: the cdp-attach edits are gone (the flag never applied to attach), screenshot-caret and stalled-frame run sandboxed by default, resolved from the ambient environment so the CI opt-out still reaches a direct launch, and the workflow comments shrink to one line. New tests pin the trim and lowercase handling, the opt-out surviving a failed relaunch, and the friendly error text.

Verified: web unit 358/358 with the opt-out; a real launch on this host fails with the friendly error by default and passes with E2E_CHROMIUM_SANDBOX=0.

Signed-off-by: Varshith Puli <pulivarshit@gmail.com>

* docs(web): minor bump for the sandbox default, CI opt-out, one home for the why

The sandbox default breaks Docker and Linux CI hosts, and the changeset said nothing about it: it is now a minor bump, opened as a maintainer-called release, telling users to set E2E_CHROMIUM_SANDBOX=0.

The CI docs name the opt-out where CI users find it: the GitHub Actions web workflow and the visual-testing screenshots workflow both set E2E_CHROMIUM_SANDBOX=0 on ubuntu-latest, matching this repo's own CI, with a note pointing at the security docs. The other CI pages run mobile targets only, so there is nothing to add there.

The why now lives in docs/security.mdx alone: the reference page, SECURITY.md, the option JSDoc, and the skill reference link to it instead of repeating it.

Verified: changeset-bumps, the docs check chain (anchors, MDX, examples, package managers, logos), and the skill tests all pass.

Signed-off-by: Varshith Puli <pulivarshit@gmail.com>

* docs(web): qualify the Chromium sandbox opt-out as ubuntu-latest only

The visual-testing guide said Linux runners generally block the user
namespaces Chromium needs. The limitation is specific to the
ubuntu-latest runners used here, so name them and tell readers to leave
the sandbox on where it starts.

* fix(web): address review follow-ups on the Chromium sandbox default

Move the sandbox launch error out of the surface and into
BrowserConnection.launchLocal, where the browser name and the resolved
sandbox flag are already known, and drop the untested verb guard. The
error now names the environment opt-out only when the option did not set
the value, since an explicit option wins over the variable. The surface
keeps the option as a readonly field and resolves it into a private
field defaulting to true, the same pattern as headed, so startAttempt
without init no longer needs the fallback. The skill GitHub Actions
recipe runs ubuntu-latest with E2E_CHROMIUM_SANDBOX 0, the web reference
points at the new ENGINE_FAILURE instead of Playwright error text, and
the resolve helper loses its dead branches.

Web unit suite: 362/363 pass; the one failure is artifact-path, which
fails identically on the base head because a real Chromium cannot start
sandboxed in this container.

* fix(web): address re-review follow-ups on the Chromium sandbox default

Resolve the sandbox into one { enabled, fromOption } object and pass it through acquire into launchLocal, which now takes the options object instead of five positional args, so the launch and its error cannot disagree about which opt-out set the value. Add the waiter-joins-a-pending-relaunch case, where the re-acquire runs once and a flip cannot cancel out, and assert retryable is false on the friendly error. Document E2E_CHROMIUM_SANDBOX in the environment reference, point the dead [Security](/security) links at https://e2e.com/docs/security, and fix the changeset wording, since the error no longer always names both opt-outs. The acquire JSDoc now states the actual guarantee: a launch takes the value its own call passes.

Web unit suite: 364/364 pass with E2E_CHROMIUM_SANDBOX=0 (artifact-path fails without it, identically on the base head, because a real Chromium cannot start sandboxed in this container). Web typecheck clean, oxlint clean. The new waiter test fails against a flip mutant injected on the re-acquire and passes without it.

Signed-off-by: Varshith Puli <pulivarshit@gmail.com>

* docs(web): mark E2E_CHROMIUM_SANDBOX as a value in the env reference

The entry was marked flag, but on this page 0 and false mean unset for flags, while 0 opts out of sandboxing here. Mark it value so readers do not apply the wrong flag semantics.

Signed-off-by: Varshith Puli <pulivarshit@gmail.com>

* docs(ci): restore the timings-history section lost in the rebase

The rebase conflict resolution in docs/ci/github-actions.mdx kept only the tail of the new Cache the timings history section, dropping its heading, intro, and example, which broke the docs anchor check (docs/ci.mdx links to #cache-the-timings-history). Restored in full; the sandbox opt-out paragraph follows it unchanged.

Verified: the docs check chain passes locally (anchors, examples, package managers, logos, MDX).

Signed-off-by: Varshith Puli <pulivarshit@gmail.com>

* docs(security): soften sandbox containment wording

The security page stated a renderer exploit stays contained by the
sandbox, which reads as a guarantee. Say the sandbox helps contain it
and note it does not prevent sandbox escapes or Chromium
vulnerabilities, matching the review feedback on the Chromium sandbox
default.

Signed-off-by: Varshith Puli <pulivarshit@gmail.com>

* docs(security): wrap the sandbox containment sentence at 80 columns

Signed-off-by: Varshith Puli <pulivarshit@gmail.com>

* fix(web): import EngineError from @e2e-dev/core/engine

browser-connection imported EngineError from e2e/engine, so loading the
web engine without the e2e package failed with ERR_MODULE_NOT_FOUND.
That broke the core-only install smoke check, which loads each engine
main entry without e2e installed. Import from @e2e-dev/core/engine
instead, like every other file in the web engine.

Signed-off-by: Varshith Puli <pulivarshit@gmail.com>

* docs(security): re-wrap sandbox paragraph and soften changeset wording

Re-wrap the sandbox containment paragraph in docs/security.mdx at 80
columns so vulnerabilities; no longer sits on a line of its own, and
soften the changeset to match: the sandbox helps contain a renderer
exploit but does not prevent sandbox escapes. The changeset keeps only
the user-facing part: what changed and the two opt-outs.

Signed-off-by: Varshith Puli <pulivarshit@gmail.com>

* fix(web): default the Chromium sandbox by platform, drop the env opt-out

On for macOS and Windows, opt-in on Linux where root, most containers
and Ubuntu 23.10+ cannot start it. The option alone decides, so CI,
the test env forwarding and the docs recipes need no opt-out.

* test(web): drop the relaunch cases the waiter test already covers

---------

Signed-off-by: Varshith Puli <pulivarshit@gmail.com>
Co-authored-by: Oskar Kwaśniewski <oskar@okwasniewski.com>
2026-11-20 11:25:39 +00:00
..
2026-11-19 16:37:27 +02:00
2026-11-19 16:37:27 +02:00

@e2e-dev/web

The browser engine for e2e, built on Playwright.

e2e ships no engine of its own: every target names the engine that drives it, and this package is the one for browsers. It implements the public @e2e-dev/core/engine contract (e2e/engine to the runner), so a device or desktop engine plugs into the same seam with no privilege either way.

Install

npm install --save-dev e2e @e2e-dev/web

To drive a browser from a program without the test runner, install @e2e-dev/core instead of e2e, and import web from @e2e-dev/web/engine:

npm install @e2e-dev/core @e2e-dev/web

This package depends on playwright-core pinned to an exact version, so the engine always runs the Playwright it was tested against. An app that depends on Playwright itself keeps its own copy; the two share a browser cache only when their versions match.

import type { E2EConfig } from 'e2e';
import { web } from '@e2e-dev/web';

export default {
  targets: [{ name: 'web', engine: web(), app: { url: 'http://localhost:3000' } }],
} satisfies E2EConfig;

The target declares the app; the engine only drives it. The target's app takes url (the base URL app.open() opens; required on a web() target), command (a process the runner starts before the run and stops after it, with readyUrl to poll, default url), environment (test, staging, production; inferred from the host), and identity (a stable cache and session key when the origin is ephemeral). web({ url }) and the other old app options are INVALID_CONFIG. A target with app.url is a browser target, so a test can requires: ['browser']. Browser options: browser (chromium, firefox, webkit; default chromium; or a BrowserProvider that leases hosted browsers, see below), viewport ({ width, height }; default 1280x720), testIdAttribute (the attribute getByTestId and a node's testId read; default data-testid), userAgent (the User-Agent every attempt sends and navigator.userAgent reports), locale and timezoneId (the language and time zone every attempt runs in, such as de-DE and Europe/Berlin), colorScheme and reducedMotion (the prefers-color-scheme and prefers-reduced-motion every page reports, from first paint; browser.emulateMedia changes them in a test), initScripts (scripts every document runs before the page's own), and connect — attach to a remote browser over CDP instead of launching a local one.

Attaching to a remote browser (connect)

Set connect.cdpEndpoint to attach over the Chrome DevTools Protocol rather than launch. The resolver is async and called at worker init, and again at the start of any attempt that finds the session dropped, so a hosted browser whose endpoint is provisioned per run — a cloud session URL that is not known at config load — resolves each time it is needed. The resolver receives an AbortSignal that fires when the init or attempt is cancelled or exceeds its budget; a browser that connects after that is detached, never used. CDP attach is chromium-only, and disposing the engine detaches the session without killing the remote process the host owns.

engine: web({
  connect: { cdpEndpoint: async () => acquireCloudBrowserSession() },
});

For transport recovery, add connect.reconnectEndpoint(signal). This opts into the remote browser's persistent default context. cdpEndpoint then provisions a fresh, dedicated browser for every attempt, including retries; reconnectEndpoint must return that same browser after a disconnect. The engine verifies the default context ID and active page target ID, clears stale references, and never repeats a dispatched operation. A missing target fails the attempt. The host owns deleting the remote browser after cleanup.

This mode does not support headers, basicAuth, userAgent, locale, timezoneId, context reset, or session state capture and restore. Recording resumes after reconnect, but a segment lost during the disconnect remains unavailable. See the Playwright reference for the lifecycle and ownership contract.

Leasing hosted browsers (browser)

connect has no lifecycle: nothing tells the host when to delete the browser it provisioned. Pass a BrowserProvider as browser instead and the engine asks for a browser when one is needed and gives it back when its scope ends, on every exit path. scope: 'worker' (the default) leases one browser per worker slot in prepare and releases them in finish; a worker whose browser drops leases a replacement itself. scope: 'attempt' leases a fresh browser in every startAttempt and releases it in endAttempt, reattaching through the lease's reconnectEndpoint after a transport drop, with the limits of connect.reconnectEndpoint. A provider implies chromium and excludes connect; no vendor ships in the package. See Hosted browsers for the contract and an example against a generic session API.

engine: web({
  browser: {
    name: 'hosted-browsers',
    acquire: async (request) => ({ id: session.id, cdpEndpoint: session.cdpUrl }),
    release: async (lease) => stopSession(lease.id),
  },
});

The browser fixture

The engine contributes browser: navigation, routes, cookies, dialogs, frames, downloads, keyboard and mouse, plus expect(browser).toHaveURL() and toHaveTitle() and toHaveClass(). Import test from this package to have it typed; it is the same runtime test as e2e's.

import { test } from '@e2e-dev/web';
import { expect } from 'e2e';

test('signs in', async ({ app, screen, browser }) => {
  await app.open('/login');
  await screen.getByLabel('Email').fill('user@example.test');
  await expect(browser).toHaveURL('/dashboard');
});

Browsers

A missing browser is downloaded once per run, in the runner process, after the tests are collected and before the app starts: the progress prints in the run log, the run's clock starts only once the download is done, and no launch or test timeout ever includes it. Workers launch the browser the runner installed.

In CI, install browsers as their own step instead, so the cost is visible and cacheable:

npx @e2e-dev/web install chromium --with-deps

It downloads the browsers for the Playwright version this package pins, the ones the engine launches. Under pnpm, run the bin by name: pnpm exec e2e-web install chromium --with-deps.

--with-deps also installs the system libraries a slim container image lacks.

Documentation

Full documentation lives at e2e.com/docs.