feat(browser-run): add Cloudflare hosted browsers

Merged
IR
4d ago
+1242-44

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_ID and CLOUDFLARE_API_TOKEN with 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. connect also 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; set BROWSER_RUN_SCOPE=attempt for the second run.
  • Unfiltered runs: worker 21 passed, 1 failed; attempt 14 passed, 1 failed. Both failures are browser.back() waiting for load, 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.
RegressionBefore review fixesThis branch
Errored 429 response bodyStream cancellation masks the retryRegression passes; the rejected request retries
Journal write and DELETE both failCleanup error replaces the journal errorBoth errors and session ID retained
Attempt-scope reconnectNo regression covered reconnect credentialsReconnect tests require headers for explicit and fallback endpoints

Maintainer verification on 2026-11-12 after rebasing onto main:

  • pnpm check passed, including the build, public type checks, and docs checks.
  • Built CLI: pnpm --filter @e2e-dev/testbed test passed 588 tests, 1 skipped; pnpm --filter @e2e-dev/web-benchmark test passed 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/browser path.
  • Fork workflows have been approved for the rebased head. Human re-review is requested.