SeleniumBase

Open source alternative to BrowserStack, LambdaTest, Sauce Labs and Cypress

13.3K stars
MIT
Active this week
Last commit 6 days ago

Last verified Nov 13, 2026

Automate browsers and run end-to-end tests in Python with built-in stealth modes, pytest integration, and automatic driver management.

Visit website GitHub13.3K

Read the full breakdownWho it is for, how it works, trade-offs, the quick start and the FAQ

who it's for

Who SeleniumBase is for#

QA teams migrating from raw Selenium

Teams with existing Selenium tests can migrate incrementally. SeleniumBase supports raw `self.driver` access alongside its higher-level methods, so you can modernize test files one at a time without rewriting everything.

Skip if:

Your team uses Playwright or Cypress and has no Python constraint.

Scraping behind bot-detection

CDP Mode and UC Mode handle Cloudflare Turnstile and similar bot-detection protections that block standard WebDriver. Use SeleniumBase when your scraping target actively blocks automated browsers.

Skip if:

Your target sites have no bot-protection and static HTTP fetching is sufficient.

CI-based E2E testing in Python projects

If your project already uses Python and pytest, SeleniumBase slots directly into your CI pipeline without a separate testing toolchain. It runs in any environment where Chrome and Python are available.

Skip if:

Your project uses a JavaScript frontend framework with an established JS testing stack.

the problem

The problem it solves#

Raw Selenium requires significant boilerplate to work reliably. Setting up a CLI options parser, adding explicit WebDriverWait calls for every element interaction, and parsing error output on failures all add overhead before you can write reliable tests. Teams end up maintaining test infrastructure as much as writing tests themselves. Bot-detection is a separate pain point: standard WebDriver signatures get blocked by Cloudflare Turnstile challenges and similar protections on many real-world sites. Cloud testing services like BrowserStack or Sauce Labs address cross-browser device coverage, but add per-minute pricing and route test traffic through third-party servers. Teams that need stealth, Python, and local or CI execution have historically had to stitch together multiple libraries with unreliable results.

how SeleniumBase solves it

How it solves it#

CDP Mode for stealth browsing

CDP Mode uses the Chrome DevTools Protocol to bypass bot-detection on Chromium-based browsers. It handles Cloudflare Turnstile challenges automatically, with `sb.solve_captcha()` as a manual fallback when challenges are not auto-resolved.

Auto-waiting methods

Methods like `self.type()`, `self.click()`, and `self.assert_element()` wait up to 7 seconds for elements to be visible and interactive before acting. This eliminates most explicit WebDriverWait calls that raw Selenium requires.

pytest, behave, and pynose integration

Tests run with pytest or behave using standard test discovery and reporting. Command-line options let you set browser, timeout, demo mode, and UC Mode without editing code. The framework also supports pynose for compatibility with older test suites.

Multiple syntax formats

Write tests using BaseCase class inheritance for pytest structure, the SB context manager for script-style code, or the Driver Manager for raw driver access. All three share the same underlying methods; choose the style that fits your codebase.

Recorder and test generator

The built-in Recorder captures browser actions and generates test code, reducing the manual work of writing selectors. The desktop SeleniumBase Commander GUI launches test runs without the command line.

Dashboard and failure screenshots

An HTML dashboard shows test pass/fail state across a run. Failing tests automatically save screenshots to `./latest_logs/`, making post-run debugging faster without custom logging code.

strengths · trade-offs

Strengths and trade-offs#

Strengths

MIT license with no seat feesSeleniumBase is MIT-licensed and installs from PyPI. There are no per-seat charges, no usage-based billing, and no account required. Teams of any size run as many tests as they need on their own infrastructure.
Active maintenance since 2014The repo has been in active development for over a decade, with its last push in November 2026. With 15 open issues and over 13,000 GitHub stars, it has a proven track record and a steady release cadence.
Automatic driver and selector handlingCSS and XPath selectors are detected automatically, so you pass a selector string without specifying its type. The driver manager downloads a matching browser driver based on the installed browser version without manual setup.

Trade-offs

-Python onlySeleniumBase is a Python framework. Teams whose test suites are in JavaScript, TypeScript, or Ruby need a different tool; Cypress or Playwright are the typical choices for non-Python shops.
-No cloud device matrixSeleniumBase runs against browsers installed on the host machine. It does not provide access to real devices, different OS versions, or cloud-hosted browser farms. Teams that need cross-device coverage still need a service like BrowserStack or Sauce Labs alongside it.
-Selenium WebDriver limitationsSeleniumBase sits on top of Selenium WebDriver, which uses the WebDriver protocol rather than native browser APIs for most operations. This can be slower than Playwright in some scenarios and subject to the same driver compatibility issues Selenium users know.

versus alternatives

SeleniumBase vs alternatives#

SeleniumBase vs BrowserStack and Sauce Labs

BrowserStack and Sauce Labs are commercial cloud platforms that provide access to real devices and browser versions you do not have on your own machine. They charge per minute of test execution and route your test traffic through their infrastructure. SeleniumBase runs entirely on the machine you control, with no usage-based billing. The tradeoff is device coverage: if your tests need to run against iOS Safari on a real iPhone or an obscure browser version, the cloud platforms provide that; SeleniumBase does not.

For teams whose tests run against a known set of desktop browsers, SeleniumBase cuts the per-minute cost to zero and keeps test data off third-party servers. Teams that need broad device matrix testing typically use a cloud service alongside a local framework rather than choosing one over the other.

SeleniumBase vs LambdaTest

LambdaTest is a cloud-based cross-browser testing service with a similar value proposition to BrowserStack: hosted real devices, parallelization, and integrations with CI services. SeleniumBase can send tests to LambdaTest via its remote WebDriver capabilities, so the two are not mutually exclusive. When used together, SeleniumBase handles test authoring and CDP Mode stealth while LambdaTest provides the cloud device grid. When used in isolation, the same cost-versus-coverage tradeoff applies as with BrowserStack.

SeleniumBase vs Cypress

Cypress is an end-to-end testing framework that runs tests inside the browser using its own test runner and dashboard service. The key differences are language and architecture: Cypress uses JavaScript and TypeScript, while SeleniumBase uses Python. Cypress runs test code in the same browser process as the application; SeleniumBase controls the browser from an external driver.

For Python teams, SeleniumBase is the natural fit. For JavaScript teams, Cypress is the more idiomatic choice. SeleniumBase's CDP Mode adds stealth and cross-browser capabilities that Cypress does not offer; Cypress has a tighter browser-side debugging story and time-travel inspection in its dashboard. Teams that need to scrape bot-protected sites or automate outside of a browser testing context will find SeleniumBase's CDP and UC modes have no direct equivalent in Cypress.

install · quick start

Quick start#

bash

Install SeleniumBase from PyPI using pip; add the optional Playwright package for the CDP stealth integration.
```bash
pip install seleniumbase
pip install playwright
```

tech stack · detected from GitHub

What it's built on#

Languages: Python
Frameworks: Express
Tooling: Playwright

frequently asked

FAQ#

Does SeleniumBase work with browsers other than Chrome?

Yes. SeleniumBase supports Microsoft Edge, Brave, unbranded Chromium, and Chrome-for-Testing. Select the browser with a command-line flag (--edge, --brave, --chromium, --cft) or by passing the browser argument to the driver. Chrome is the default. Firefox is supported through Selenium's WebDriver, but CDP and UC stealth modes require a Chromium-based browser.

What is the difference between UC Mode and CDP Mode?

UC Mode patches ChromeDriver to avoid bot-detection signatures that standard WebDriver exposes. CDP Mode uses the Chrome DevTools Protocol directly, bypassing WebDriver for the browser session. The two can be combined: SB(uc=True) followed by sb.activate_cdp_mode(). CDP Mode is the more capable stealth option; UC Mode is the simpler entry point.

How do I install SeleniumBase?

Install from PyPI with pip install seleniumbase. Add --upgrade or -U to update an existing install. After installation, run seleniumbase or sbase in your terminal to verify it installed correctly. For development, clone the repo and run pip install -e . from inside it.

Does SeleniumBase work with Playwright?

SeleniumBase's Stealthy Playwright Mode integrates Playwright under the CDP Mode stealth layer, so it can drive Playwright browsers with the same anti-detection approach. SeleniumBase is primarily a Selenium framework; teams that want Playwright as their primary driver should use it directly or pair it with the SeleniumBase CDP layer for stealth. Install the Playwright integration with pip install playwright.

Can SeleniumBase be used for web scraping, not just testing?

Yes. SeleniumBase includes both test-mode scripts (run with pytest) and raw Python scripts (run directly with python). The sb_cdp.Chrome() context is designed for scraping and automation without a test runner. CDP Mode's stealth and automatic CAPTCHA handling make it suitable for scraping sites that block standard HTTP clients.

also worth a look