Selenium is in an odd spot for network mocking. Unlike Puppeteer or Playwright, its classic API has no request interception at all — a Selenium test drives a real browser making real requests to real URLs. For years the community answer was selenium-wire, which spliced a proxy into the driver; that project was archived in January 2024 (last release: October 2022) and no longer tracks current Selenium. The other classic answer is running your own mock server next to the test — which is exactly the chore a hosted mock URL removes.
The good news, in order of how much machinery you need:
driver.network in Python) finally does real interception — URL rewrites, header injection, even stubbed responses — with no proxy. It's recent and still stabilizing; we hit real sharp edges, all documented in §7.Every snippet below was run verbatim before publishing (Selenium 4.48.0 Python bindings, Chrome for Testing 152 — the parallel two-driver run in §6 twice).
curl -X POST https://mockbird.mockbird.workers.dev/api/projects \
-H 'content-type: application/json' -d '{"name":"selenium-demo","preset":"ecommerce"}'That returns a project id and admin key, with products, orders, customers and reviews already seeded with realistic data — full CRUD, filtering, pagination, CORS on. Or create it in one click. The snippets below use the public demo project so you can paste-and-run them with nothing created at all.
If your app reads its API base from config/env, you need nothing beyond vanilla Selenium — this also covers SSR and backend fetches that browser-side interception can never see:
from selenium import webdriver
from selenium.webdriver.support.ui import WebDriverWait
MOCK = "https://mockbird.mockbird.workers.dev/m/demo"
driver = webdriver.Chrome()
driver.get("http://localhost:8141/?api=" + MOCK)
WebDriverWait(driver, 15).until(
lambda d: d.find_element("id", "state").text.startswith(("loaded", "error")))
items = driver.find_elements("css selector", "#list li")
assert len(items) == 5
driver.quit()(The app under test here is a plain page that fetches {base}/products?limit=5 and renders an <li> per product — swap in your own app and selector.)
When you can't change the base URL, the BiDi network API swaps it below the page — the page still believes it called the production host, and the response comes from the mock (Mockbird sends Access-Control-Allow-Origin: *, so the cross-origin check passes):
from selenium.webdriver.chrome.options import Options
MOCK = "https://mockbird.mockbird.workers.dev/m/demo"
opts = Options()
opts.enable_bidi = True # BiDi on: driver.network appears
driver = webdriver.Chrome(options=opts)
def to_mock(request):
request.set_url(request.url.replace("https://api.example.com", MOCK))
driver.network.add_request_handler(callback=to_mock,
url_patterns=["https://api.example.com/*"])
driver.get("http://localhost:8141/") # app uses its normal "production" baseCall request.set_url() (or set_headers/set_method) inside the handler and Selenium continues the request with your mutations — don't call driver.network.continue_request() yourself with the wrapped request object; that's the lower-level command and it doesn't accept the handler's Request wrapper.
Every Mockbird endpoint honors simulation query params. A scoped request handler is a clean per-test injection point — the app code stays untouched:
# spinner/skeleton spec: every API call takes a real 2 seconds
def slow(request):
u = request.url
request.set_url(u + ("&" if "?" in u else "?") + "mock_delay=2000")
h = driver.network.add_request_handler(callback=slow,
url_patterns=["https://mockbird.mockbird.workers.dev/**"]) # ** — see §7!
driver.get(APP)
time.sleep(1)
assert driver.find_element("id", "state").text == "loading..." # skeleton still up at 1s
WebDriverWait(driver, 15).until(
lambda d: d.find_element("id", "state").text.startswith("loaded"))
driver.network.remove_request_handler(h)Swap the param for the error-matrix spec: mock_status=500 returns a real 500 with a JSON body (any 400–599 works), and your error UI renders exactly as it would in production — our verification run asserted both. On older Selenium without BiDi, point the base URL at the mock (§2) and put the flags on a per-scenario project instead. Full recipes: loading & error states guide.
mock_seq scripts an exact status sequence — deterministic, unlike random chaos. First call 500, every call after that 200:
key = f"run-{int(time.time()*1000)}" # fresh counter per test run
def flaky(request):
u = request.url
sep = "&" if "?" in u else "?"
request.set_url(f"{u}{sep}mock_seq=500,200&mock_seq_key={key}")
driver.network.add_request_handler(callback=flaky,
url_patterns=["https://mockbird.mockbird.workers.dev/**"])Our verification run's retry loop observed exactly [500, 200] and got the data on attempt two. The counter is server-side per key — a stale key from a previous run would replay from wherever it left off, hence the timestamp. For random flakiness use ?mock_chaos=0.4 (chaos-failed writes are not applied, so pointing retry logic at it is safe).
Selenium parallelism is one driver per worker (pytest-xdist, Grid nodes) — which maps perfectly onto snapshot pinning: save each state (empty list, edge cases, bug repro) as a named snapshot once, then each driver pins itself with one header. Live data is untouched; two drivers read different states of the same project at the same time. Setup (once):
ADMIN='x-admin-key: YOUR_ADMIN_KEY'
B=https://mockbird.mockbird.workers.dev/api/projects/YOUR_ID
curl -X POST $B/snapshots -H "$ADMIN" -H 'content-type: application/json' -d '{"name":"baseline"}'
curl -X POST $B/resources/products -H "$ADMIN" -H 'content-type: application/json' -d '{"seed":0}'
curl -X POST $B/snapshots -H "$ADMIN" -H 'content-type: application/json' -d '{"name":"empty"}'
curl -X POST $B/snapshots/baseline/restore -H "$ADMIN"Then each worker injects the header with a scoped handler:
def make_worker_driver(snapshot=None):
opts = Options(); opts.enable_bidi = True
d = webdriver.Chrome(options=opts)
if snapshot:
def pin(request):
request.set_headers({**request.headers,
"x-mockbird-snapshot": snapshot})
d.network.add_request_handler(callback=pin,
url_patterns=["https://mockbird.mockbird.workers.dev/**"])
return d
live_driver = make_worker_driver() # sees live data
empty_driver = make_worker_driver("empty") # pinned to the "empty" snapshot
# both run against the SAME project at the same moment:
# live renders 5 products; empty renders the empty-state UIThat exact parallel run (two drivers in threads) is part of our pre-publish verification. Writes while pinned return 405 with a restore hint, so a test can't corrupt a scenario by accident. If a query param is easier than a header in your setup, ?mock_snapshot=empty does the same thing.
* in URL patterns doesn't cross /. Selenium's URL globs are segment-scoped: host/* matches /products but silently never matches /m/demo/products — your handler just doesn't fire, with no error. Use ** for multi-segment paths. (Puppeteer and Playwright globs behave differently; this one cost us a debugging session.)driver.network.add_extra_header(), which internally pauses every request — also paused the page navigation itself and hung the session. A handler with url_patterns scoped to the mock host was reliable every time, which is why §6 injects the header that way.execute_async_script can deadlock against BiDi handlers. Our first retry test blocked on the classic (HTTP) command while the paused fetch waited on the BiDi handler — script timeout. Kick the async work off with execute_script, then poll for a result with WebDriverWait instead.--no-sandbox. On distros that restrict unprivileged user namespaces, Chrome dies at launch — opts.add_argument("--no-sandbox") is the standard CI workaround (understand the tradeoff before using it outside CI).| selenium-wire | BiDi provide_response stubs | Mockbird (hosted) | Both (this guide) | |
|---|---|---|---|---|
| Maintained | ✘ archived Jan 2024 | ✔ but new, still stabilizing | ✔ | ✔ |
| Works on old Selenium / all bindings | Python only, old versions | ✘ needs recent BiDi support | ✔ any version, any language | partial |
| Works offline / airgapped CI | ✔ | ✔ | ✘ needs network | ✘ |
| Seeded, realistic, stateful CRUD data | hand-written | hand-written, stateless | ✔ | ✔ |
| SSR / backend fetches | ✘ browser only | ✘ browser only | ✔ any process | ✔ via base URL |
| Same data for curl / teammates / QA links | ✘ | ✘ | ✔ it's a URL | ✔ |
| Parallel data scenarios | DIY | DIY state machine | ✔ snapshot pinning, one header | ✔ |
If your suite is browser-only, airgapped, and you need a handful of static stubs, BiDi's request.provide_response() can answer requests without any server — that's a fair choice, and it composes with everything above.
pip install selenium
curl -X POST https://mockbird.mockbird.workers.dev/api/projects \
-H 'content-type: application/json' -d '{"name":"selenium-demo","preset":"ecommerce"}'…or skip the terminal: create the same seeded project in one click. Free, no signup required — the project is anonymous and claimable later. Full docs.
Using Puppeteer or Playwright instead? The Puppeteer guide and Playwright guide cover the same patterns with their native interception. Running in CI? Ephemeral project per GitHub Actions run. Testing loading/error UI specifically? Loading & error states.
Environment used for verification: Selenium 4.48.0 (Python), Chrome for Testing 152, run against the live demo project and a scratch project on 2 Sep 2026 — including the §6 parallel two-driver run (twice) and all four §7 gotchas reproduced, not read about. If a snippet here doesn't work, that's a bug: tell us.