SeleniumBase: CDP Mode, Stealth Chromium and pytest in One Python Package

What SeleniumBase Is Actually For

The README calls SeleniumBase an "All-in-one Browser Automation Framework: Web Crawling / Testing / Scraping / Stealth". That is four jobs in one package, and the packaging reflects it: pyproject.toml lists packages including seleniumbase.core, seleniumbase.drivers (with separate driver folders for cft, chs, opera, brave, comet and chromium), seleniumbase.undetected, seleniumbase.translate and mcp_servers. Nothing here is a thin wrapper.

The audience is Python developers who already think in pytest. The dependency list pins pytest==8.4.2 on Python below 3.11 and pytest==9.1.1 above it, along with pytest-html, pytest-metadata, pytest-ordering, pytest-rerunfailures and pytest-xdist. If your test suite is pytest, SeleniumBase slots into the runner you already use. If your suite is JUnit, Jest or Go test, the framework offers you nothing you cannot get from raw Selenium.

The second audience is scrapers who keep getting blocked. CDP Mode, documented under examples/cdp_mode/, drives a Chromium instance over the Chrome DevTools Protocol rather than through the WebDriver wire protocol, and the README states plainly that it "bypasses bot-detection with Chromium-based browsers." That claim is about Chromium-based browsers only. Firefox and Safari users are outside the scope of the stealth path.

How CDP Mode Differs From the Standard WebDriver Path

Most Selenium code goes through WebDriver: the client sends HTTP commands to a driver binary, which drives the browser. CDP Mode skips that. The README example imports sb_cdp and calls Chrome(), then goto() and sleep(). There is no webdriver.Chrome() call, no Service object and no driver path to configure. The connection is the DevTools Protocol, which is the same channel Chrome's own DevTools panel uses.

That architectural choice explains the stealth behaviour. WebDriver-driven sessions expose properties that detection scripts probe. A CDP session does not go through the same automation handshake, so those probes come back differently. The README points at browserscan.net/bot-detection as the demonstration target, which is a site built to report what a browser leaks. Whether it passes on any given day is not something the README guarantees.

The repository keeps a separate undetected package (seleniumbase.undetected, with a cdp_driver subpackage), and there is also a UC Mode documented in help_docs/uc_mode.md. So there are at least three distinct stealth-related paths in one codebase. That is a maintenance surface, and it is worth knowing which one your code is on before you file a bug.

Stealthy Playwright Mode, documented under examples/cdp_mode/playwright/, extends the same CDP approach to Playwright. It requires a separate install, which the README lists as pip install playwright.

Installing SeleniumBase and Running a First Script

The README gives two install lines. The first installs the framework; the second is only needed if you want the Playwright integration.

pip install seleniumbase

pip install playwright

The README also notes that uv add works for either. After installation, the shortest working program is the Pure CDP Mode example from the README, which needs no pytest and no test file.

from seleniumbase import sb_cdp

sb = sb_cdp.Chrome()
sb.goto("https://browserscan.net/bot-detection")
sb.sleep(3)
sb.quit()

Run it with python. What you should see is a Chromium window open, navigate to the detection page, wait three seconds and close. The README uses this exact script to demonstrate that the session reaches the page without being flagged. If the browser closes immediately or the page reports automation, the stealth path is not working on your machine, and the README does not document a fallback for that case.

For a test-shaped project rather than a script, the repository ships examples/ with basic_test.py and a pytest.ini at the top level, so pytest discovery is configured out of the box. The README also links a Dockerfile at the repository root if you would rather not install Chromium dependencies locally.

The MCP Server and What It Changes

The repository contains a top-level mcp_servers/ directory and a .mcp.json file, and the README links a dedicated MCP ReadMe. The package name given in the README is seleniumbase-mcp. The most recent releases are almost entirely MCP work: v4.54.10 is labelled "MCP Server: Patch 18", v4.54.9 is "MCP Server: Patch 17", and v4.54.8 is "Fix command injection and more".

That sequence is informative. Eighteen consecutive patches to one subsystem, followed by a security fix, tells you the MCP server is the newest and least settled part of the project. If you are evaluating SeleniumBase for an agent that drives a browser, you are adopting the component with the shortest track record. If you only need test automation, the MCP server is dead weight in the dependency tree but not a reason to avoid the package.

The command injection fix in v4.54.8 is also worth reading in the release notes before you expose an MCP server to anything untrusted. The README does not describe the server's trust model, so the release notes are the better source.

Where SeleniumBase Gets in the Way

The dependency list is the first real cost. requirements.txt pins selenium==4.49.0 exactly, plus behave, beautifulsoup4, pyotp, rich, Jinja2, MarkupSafe, trio, wsproto and a stack of pytest plugins. If your project already pins a different Selenium version, you have a conflict to resolve before you write a line of code. The same file pins pytest to two different major versions depending on the Python version, so an upgrade of the interpreter can move your test runner underneath you.

The stealth claim is also narrower than it sounds. The README scopes CDP Mode to Chromium-based browsers. It does not claim to defeat every detection system, and the demonstration target is a single public detection page. Sites that fingerprint at the network layer, require residential IPs, or rate-limit by account are not addressed by anything in the repository. The related search term seleniumbase proxy exists because stealth and proxy rotation are usually discussed together, but the README does not document a proxy feature here.

Finally, the release cadence is fast. Three releases in the three days before the last push on 2026-09-18, all MCP patches. Fast patch churn on a stealth layer means the behaviour you depend on can change between minor versions. Pin your version if you have a scraper in production.

SeleniumBase Compared With Raw Selenium and Playwright

Raw Selenium gives you the WebDriver API and nothing else. You choose the driver manager, the test runner, the reporting and the waits. SeleniumBase makes those choices for you: pytest is the runner, pytest-html and pytest-metadata are the reporting, and the waits are built into the framework's methods. The trade is control for convention. If your team has strong opinions about test structure, the framework's conventions will fight you.

Playwright is the closer comparison, and the interesting part is that SeleniumBase does not treat it as a rival. The repository contains Stealthy Playwright Mode, which the README describes as extending "CDP Mode's stealth to Playwright." So the two can be combined rather than chosen between. Playwright brings its own browser binaries and its own API surface; SeleniumBase brings the stealth layer and the pytest integration. Using both means maintaining two browser stacks.

The related search term seleniumbase vs undetected chromedriver points at the more direct comparison. undetected-chromedriver patches the Chrome driver to hide automation signals. SeleniumBase's CDP Mode takes a different route by not using the WebDriver protocol for the stealth path at all. Which approach survives a given detection update is an empirical question, and the README does not offer a comparison.

Licence, Upgrades and Maintenance Signals

SeleniumBase is MIT licensed, per the LICENSE file and the badge in the README. MIT is permissive: you can use it commercially, modify it and redistribute it, provided the copyright notice and permission notice travel with it. The repository also carries a SECURITY.md and a CODE_OF_CONDUCT.md, so there is a stated process for reporting problems. None of this is legal advice; if you are redistributing the package inside a product, read the LICENSE text yourself.

The maintenance signal is strong but the pattern matters. The last push was on 2026-09-18, three days before this writing, so the project is not dormant. But the three most recent releases are all MCP patches, and v4.54.8 is a security fix. Upgrading therefore carries a real cost: read the release notes for each version between yours and the target, because the changelog is where the behaviour changes are recorded, not the README.

There is no documented deprecation policy in the repository. If you depend on a specific CDP Mode method, help_docs/cdp_mode_methods.md is the API reference to check against each upgrade.

Editorial conclusion

Adopt SeleniumBase if you already write Python tests or scrapers and want stealth, a pytest runner and reporting in one dependency tree. Do not adopt it if you need a small browser client, a non-Python stack, or a stable script API: the release history shows rapid patch churn around CDP Mode and the MCP server. Before committing, run one target page through both sb_cdp.Chrome() and the standard SB() context and compare what each returns, because the README does not document rollback or fallback behaviour when the stealth layer fails.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. seleniumbase/SeleniumBase on GitHub