When a Browser Run Worker runs under wrangler dev, what does local mode simulate, and what can it not reproduce?
answer
- a real Chrome, on your machine
- downloaded on first use
- fixed limits, empty history
- Quick Actions need the real service
basics
~20 sUnder wrangler dev the browser binding launches a Chrome downloaded to your machine, so Puppeteer and Playwright code runs locally. It reports fixed limits, keeps no session history, rejects requests over 1 MB and does not implement quickAction().
solid answer
~40 sSince July 2025, `wrangler dev` serves the browser binding locally: Miniflare downloads a Chrome build on first use and launches it, so `puppeteer.launch(env.MYBROWSER)`, `sessions()` and `connect()` work against a browser on the developer's machine. `X_BROWSER_HEADFUL=true npx wrangler dev` opens a visible window for debugging. It does not reproduce the service around the browser: the local `limits()` reports fixed values and nothing throttles launches, so plan limits, 429s and idle-session cost appear only when deployed; `history()` returns an empty list; requests larger than 1 MB are not supported; and `env.BROWSER.quickAction()` fails with `The RPC receiver does not implement the method "quickAction"` unless the binding runs in remote mode, which uses the real service and the account's quota. Deployed, pages are also fetched from Cloudflare's network and always identified as a bot.
code
bash · 5 lines# Puppeteer or Playwright code against a local, visible Chrome
X_BROWSER_HEADFUL=true npx wrangler dev
# quickAction() calls reach the real Browser Run service and its quota
npx wrangler dev --remotego deeper
Recall that wrangler dev runs a real Chrome on your machine for the browser binding, and that X_BROWSER_HEADFUL=true shows its window.
Explain the gaps: fixed local limits, empty history(), the 1 MB request cap and quickAction() needing remote mode.
Show why leaks, 429s and font fallbacks only surface after deployment, and what evidence you check on the first deployed run.
Set the team's test split: page logic locally, Quick Actions, limits and rendering against the real service, and who may spend quota through remote mode.
## What local mode runs Until July 2025 a Browser Run Worker could only be tried against the real service. Now `wrangler dev` serves the `browser` binding locally through **Miniflare**, the local Workers simulator built into Wrangler: - on first use it downloads a Chrome build and caches it on the developer's machine; - each `launch()` starts a local Chrome process with its own temporary profile; - the binding answers the same session calls the Cloudflare forks of Puppeteer and Playwright make, so `puppeteer.launch(env.MYBROWSER)`, `puppeteer.sessions()`, `puppeteer.connect()` and `browser.close()` work unchanged. That makes the browser logic of the invoice-and-preview Worker testable offline: page navigation, selectors, `page.pdf()` and `page.screenshot()` all run against a real Chromium. For debugging, `X_BROWSER_HEADFUL=true npx wrangler dev` launches Chrome in a visible window so you can watch navigation and clicks. It is experimental and affects local development only; with the Playwright fork two windows may appear. ## What it does not reproduce | Concern | Local `wrangler dev` | Deployed Browser Run | |---|---|---| | Plan limits | `limits()` returns fixed values; launches are not throttled | concurrency, new-browser rate and Free daily time enforced, with 429s | | Session history | `history()` returns an empty list | recent sessions with close reasons such as `BrowserIdle` | | Request size | requests over 1 MB not supported | larger requests accepted (the `/pdf` Quick Action takes up to 50 MB bodies) | | Quick Actions | `quickAction()` not implemented | available, with compatibility date 2026-03-24 or later | | Billing | none | browser hours, plus concurrent browsers for sessions | | Network origin | your machine's network and IP | Cloudflare's network, always identified as a bot | Three consequences follow for a team: 1. **Leaks hide locally.** A code path that never calls `browser.close()` costs nothing on a laptop. Deployed, the same path bills idle time and holds concurrency until the timeout. Review close paths in code, and check `history()` close reasons after the first deployment. 2. **Rate behaviour hides locally.** A launch-per-request design never meets a 429 under `wrangler dev`. Load behaviour has to be judged against the published limits, or measured on a deployed preview. 3. **Rendering can differ.** Browser Run's managed Chromium has its own set of installed fonts and fetches pages from Cloudflare's network, while the local Chrome uses your machine's environment. An invoice whose fonts look right locally can fall back to another font when deployed; load the font explicitly, for example with `addStyleTag`. ## Quick Actions and remote mode The binding's `quickAction()` method is not implemented by the local binding. Under plain `wrangler dev` a call fails with: ```plaintext The RPC receiver does not implement the method "quickAction" ``` Cloudflare's documentation gives two ways to exercise it during development: run `wrangler dev --remote`, or set `"remote": true` on the `browser` binding. Both reach the real Browser Run service with the account's credentials, quota and bill, so they are a deliberate step rather than a default; the material on local development covers remote bindings in general. ## What the deployed browser adds Some behaviour exists only on Cloudflare's network, so no local run can show it: - requests from Browser Run carry automatic headers such as `cf-biso-request-id` and `cf-biso-devtools`, which let an origin recognise rendering traffic; - Browser Run traffic is always classified as a bot, whatever user agent the script sets, so a customer page protected by bot rules may challenge the deployed browser while the local one sails through; - sessions can be recycled when Browser Run rolls out a release, which shows up as a `Session evicted` close reason and needs reconnection logic; - the dashboard's Runs tab and `history()` record each session's close reason. A link-preview Worker that worked against every test page locally can therefore meet challenge pages in production. That is a property of the target site's configuration, not of the Worker's code. ## A practical split - Test page logic, selectors and PDF layout locally against the downloaded Chrome. - Test Quick Actions calls, limits, 429 handling and fonts against the real service, on a preview deployment or in remote mode. - Keep the request bodies under 1 MB in local tests, or test large inputs only when deployed.
- Why does the first wrangler dev run of a Browser Run Worker pause before the first launch succeeds?The local browser binding needs a Chrome build. On first use, Miniflare downloads it and caches it on the machine; later runs reuse the cached copy. If a download was interrupted, Wrangler may report that Chrome failed to launch and try to re-download it.
- What should a team verify after deployment that local runs could not show?That sessions end with `NormalClosure` rather than `BrowserIdle` in `history()` or the Runs tab, that 429s are handled with `Retry-After`, that `X-Browser-Ms-Used` on Quick Actions matches the cost estimate, and that rendered PDFs use the intended fonts.
- wrangler dev always uses the real Browser Run service and quota
- Local mode enforces the same concurrency limits as Workers Paid
- quickAction() works under plain wrangler dev like Puppeteer does
- A browser leak would already show up in local testing
- Headful mode also changes how deployed Workers render pages
Assumes Wrangler 4.149.0 and Browser Run as of 2026-10-10: local browser bindings arrived in July 2025, and quickAction() is still not implemented in local mode.