feat(browser-run): add Cloudflare hosted browsers
Merged
IR
4d ago+1242+1242+0123456789012345678901234567890123456789-44-44-01234567890123456789
Cloudflare Browser Run runs headless Chromium on Cloudflare's network. @e2e-dev/browser-run connects existing web tests to it.
import { web } from '@e2e-dev/web';
import { browserRun } from '@e2e-dev/browser-run';
web({ browser: browserRun() });
web({ browser: browserRun({ scope: 'attempt' }) });
- Set
CLOUDFLARE_ACCOUNT_IDandCLOUDFLARE_API_TOKENwith Browser Rendering - Edit permission. The app URL must be reachable from Cloudflare. - Worker scope reuses a browser with an isolated context per attempt. Attempt scope leases a fresh browser per attempt and retry. The default inactivity timeout is ten minutes.
- CDP endpoints and handshake headers resolve together. Providers derive headers inside workers; credentials stay outside lease handoffs and page requests.
connectalso accepts{ endpoint, headers }. - Screenshots, traces, and WebM screencasts work when enabled. Remote downloads and Cloudflare-native recording attachments are unsupported. History navigation can fail waiting for
load; the separate navigation fix remains outside this PR.
flowchart LR
R[e2e runner] --> P[browserRun provider]
P -->|create and delete sessions| C[Cloudflare Browser Run]
R <-->|authenticated CDP| C
C --> A[Public HTTPS app]
Verified
Ran it locally: yes
- Built CLI against an HTTPS deployment of the actual testbed pages, with real Browser Run sessions, two workers, traces, and video. Ran both provider scopes with
node ../../packages/e2e/dist/cli/bin.js run --config e2e.browser-run.config.ts; setBROWSER_RUN_SCOPE=attemptfor the second run. - Unfiltered runs: worker 21 passed, 1 failed; attempt 14 passed, 1 failed. Both failures are
browser.back()waiting forload, followed by video cleanup on the closed page. This limitation is documented. Rerunning with--grep-invert 'navigation verbs'passed every selected test:
worker: Test Files 4 passed (4) Tests 21 passed (21)
attempt: Test Files 3 passed (3) Tests 14 passed (14)
- Observed forms, cookies/storage isolation, network routes, dialogs, frames, viewport/media settings, reload/init scripts, and worker-scope session persistence. The Cloudflare session list was empty after teardown. Scanned generated artifacts for the actual API token: no matches. Remote WebM videos were generated in both scopes; GitHub attachment upload requires repository write access and was denied for this account.
- Built CLI local testbed: 588 passed, 1 skipped. Web benchmark: 91 passed. The main/branch A/B run matched every step outcome and counter across two pairs; timing was unresolved on the busy host, so no performance claim.
| Regression | Before review fixes | This branch |
|---|---|---|
| Errored 429 response body | Stream cancellation masks the retry | Regression passes; the rejected request retries |
| Journal write and DELETE both fail | Cleanup error replaces the journal error | Both errors and session ID retained |
| Attempt-scope reconnect | No regression covered reconnect credentials | Reconnect tests require headers for explicit and fallback endpoints |
Maintainer verification on 2026-11-12 after rebasing onto main:
pnpm checkpassed, including the build, public type checks, and docs checks.- Built CLI:
pnpm --filter @e2e-dev/testbed testpassed 588 tests, 1 skipped;pnpm --filter @e2e-dev/web-benchmark testpassed 93 tests. - Browser Run provider: 35 tests passed. Full web suite: 825 tests passed, 1 skipped. Fresh-context review found no critical or important findings.
- Cloudflare credentials were unavailable on the maintainer's machine. The live hosted results above are the contributor's earlier verification, before the endpoint changed to the documented
/browser-run/devtools/browserpath. - Fork workflows have been approved for the rebased head. Human re-review is requested.