SeleniumBase on GitHub (seleniumbase/SeleniumBase)

Q: What is this?

SeleniumBase is an all-in-one Python framework for browser automation — web crawling, testing, scraping, and stealth. Its CDP Mode bypasses bot-detection in Chromium-based browsers, and a Stealthy Playwright Mode extends that to Playwright.

Q: Is it a testing framework or a scraping library?

Both, in one framework: it wraps the Selenium/WebDriver APIs and plugs into test runners like pytest, pynose, and behave, so the same calls power organized E2E test suites as well as crawling and scraping scripts.

Q: How do I get it running?

'pip install seleniumbase' is all it takes ('uv add seleniumbase' works too). For the optional Stealthy Playwright Mode, also run 'pip install playwright'.

Q: Which browsers can it drive — and do I have to babysit chromedriver versions?

Chromium-based browsers; Google Chrome is the default, and unbranded Chromium or Chrome-for-Testing are downloaded automatically if missing. Driver versions are handled for you too — SeleniumBase matches your browser unless you pin one with --driver-version=VER.

Q: Will the bot-detection bypass work on any site?

Not on every site — the README demos passing all BrowserScan checks and a Cloudflare Turnstile challenge, but whatever isn't bypassed automatically falls through to sb.solvecaptcha(), which steps in only when a CAPTCHA is actually on the page.

Q: Is this mainly for QA engineers, or also for scraping?

Both audiences: pytest-based E2E testing is the core, but the same API drives crawling and scraping — and CDP Mode's bot-detection bypass is aimed at protected sites a plain Selenium script can't touch.

Q: Does it matter if I'm on Windows, Mac, or Linux?

Nightly CI exercises the suite on macOS and Ubuntu, and being a pip package it runs wherever Python and a Chromium browser are available. Which Chromium variant you drive is your call — method args include browser='edge' and browser='brave'.

Q: How is it different from just using raw Selenium?

Raw Selenium is bare WebDriver calls. SeleniumBase layers on test-runner integration (pytest, pynose, behave), command-line options, automatic driver downloads, auto-detection of CSS vs XPath selectors, and multi-step methods — self.type() waits for the element to be visible and interactive, clears the field, types the text, and presses Enter if it ends in a newline.

Q: What does CDP Mode get used for in practice?

Stealthy scraping and automation on protected sites: the README demos passing every BrowserScan bot-detection check, bypassing a Cloudflare Turnstile challenge page, and saving Google Search results as PDF, HTML, and PNG files into ./latestlogs/. Playwright can hook into the same stealthy session via Stealthy Playwright Mode.

Q: Is there an MCP server so coding agents can drive it?

Yes — the README points to a seleniumbase-mcp MCP server, a separate package from the main 'pip install seleniumbase' framework.

SeleniumBase README

All-in-one Browser Automation Framework:
Web Crawling / Testing / Scraping / Stealth

🐙 CDP Mode bypasses bot-detection with Chromium-based browsers.
🎭 Stealthy Playwright Mode extends CDP Mode's stealth to Playwright.

pip install seleniumbase for the main framework. (Or use uv add)
pip install playwright for the optional integration. (Or use uv add)

🤖 For the seleniumbase-mcp MCP server, see the MCP ReadMe.

📝 Here's a Python example that uses Pure CDP Mode (sb_cdp):
(It navigates to Browserscan where it bypasses bot-detection.)

from seleniumbase import sb_cdp

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

BrowserScan Test Results: Normal
(All BrowserScan bot-detection tests passed successfully.)

🎭 Here's an example script that uses Stealthy Playwright Mode:
(Playwright connects to a stealthy SeleniumBase browser session.)

from playwright.sync_api import sync_playwright
from seleniumbase import sb_cdp

sb = sb_cdp.Chrome(guest=True)
endpoint_url = sb.get_endpoint_url()

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(endpoint_url)
    page = browser.contexts[0].pages[0]
    page.goto("https://bot.sannysoft.com/")
    page.wait_for_timeout(500)

All Sannysoft tests passed successfully
(All Sannysoft bot-detection tests passed successfully.)

📝 This example shows off multiple methods:

from seleniumbase import sb_cdp

sb = sb_cdp.Chrome()
sb.goto("https://seleniumbase.io/demo_page")
sb.type("input", "Quickly type text!")
sb.press_keys("textarea", "Slowly type text!")
sb.click("#myButton")
sb.set_value("input#mySlider", "100")
sb.click_visible_elements("input.checkBoxClassB")
sb.select_option_by_text("#mySelect", "Set to 75%")
sb.hover_and_click("#myDropdown", "#dropOption2")
sb.click("#checkBox1")
sb.drag_and_drop("img#logo", "div#drop2")
sb.nested_click("iframe#myFrame3", ".fBox")
sb.highlight("#myButton")
sb.quit()

📝 This example expands the Browserscan script into a test demo:
(Assertions added and elements highlighted with JavaScript.)

from seleniumbase import sb_cdp

sb = sb_cdp.Chrome(locale="en", ad_block=True)
sb.goto("https://browserscan.net/bot-detection")
sb.flash("Test Results", duration=1.5, pause=0.5)
sb.assert_element('strong:contains("Normal")')
print("Bot Not Detected")
sb.flash('strong:contains("Normal")', pause=1)
sb.quit()

📝 This example scrapes Hacker News listings:

from seleniumbase import sb_cdp

sb = sb_cdp.Chrome()
sb.goto("https://news.ycombinator.com/submitted?id=seleniumbase")
elements = sb.find_elements("span.titleline > a")
for element in elements:
    print("* " + element.text)

🐙 Stealthy CDP Mode examples are located in ./examples/cdp_mode/.

🎭 Stealthy Playwright examples are located in ./examples/cdp_mode/playwright/.

⚙️ Stealthy architecture flowchart:

Stealthy architecture flowchart
(For maximum stealth, use CDP Mode, which includes Stealthy Playwright Mode.)

🌐 CLI Options for Supported Chromium Browsers

💡 You can set the Chromium browser to use via command line parameters:

python SCRIPT.py --chromium  # Use the unbranded Chromium browser
python SCRIPT.py --cft  # Use Chrome-for-testing
python SCRIPT.py --edge  # Use Microsoft Edge
python SCRIPT.py --brave  # Use Brave browser

Google Chrome is the default browser. Only unbranded Chromium and Chrome-for-Testing get downloaded automatically if not already present on the system.

The Chromium browser can also be set via method args, eg: cft=True, use_chromium=True, browser="edge", browser="brave", etc. Eg:

sb = sb_cdp.Chrome(use_chromium=True)

📝 This example saves Google Search results with UC + CDP Mode:
(Results are saved as PDF, HTML, and PNG files to ./latest_logs/)

from seleniumbase import SB

with SB(uc=True, test=True) as sb:
    url = "https://google.com/ncr"
    sb.activate_cdp_mode(url)
    sb.click_if_visible('button:contains("Accept all")')
    sb.type('[name="q"]', "SeleniumBase GitHub page")
    sb.click('[value="Google Search"]')
    sb.sleep(4)  # The "AI Overview" sometimes loads
    print(sb.get_page_title())
    sb.save_as_pdf_to_logs()
    sb.save_page_source_to_logs()
    sb.save_screenshot_to_logs()
    print("Logs have been saved to: ./latest_logs/")

📝 This example bypasses Cloudflare's challenge page with UC + CDP Mode:
(If the Turnstile isn't bypassed automatically, sb.solve_captcha() handles it.)

from seleniumbase import SB

with SB(uc=True, test=True, locale="en") as sb:
    url = "https://gitlab.com/users/sign_in"
    sb.activate_cdp_mode(url)
    sb.sleep(2)
    sb.solve_captcha()
    # (The rest is for testing and demo purposes)
    sb.assert_text("Username", '[for="user_login"]', timeout=3)
    sb.assert_element('label[for="user_login"]')
    sb.highlight('button:contains("Sign in")')
    sb.highlight('h1:contains("GitLab")')
    sb.post_message("SeleniumBase wasn't detected", duration=4)

SeleniumBase
(Successfully bypassed bot-detection on a Cloudflare challenge page.)

💡 sb.solve_captcha() handles CAPTCHAs that aren't bypassed automatically.
(If no CAPTCHA is present on the current page, then nothing happens.)

📝 This example handles a CAPTCHA page with Pure CDP Mode:

from seleniumbase import sb_cdp

sb = sb_cdp.Chrome(incognito=True)
sb.goto("https://gitlab.com/users/sign_in")
sb.sleep(2)
sb.solve_captcha()
sb.highlight('h1:contains("GitLab")')
sb.highlight('button:contains("Sign in")')
sb.quit()

🧪 Comprehensive E2E Testing with `pytest`:

📚 The SeleniumBase/examples/ folder includes over 150 ready-to-run examples of E2E testing. Examples that start with test_ or end with _test.py/_tests.py run with pytest. Other examples run directly with raw python (those generally start with raw_ to avoid confusion).

📝 This example tests an e-commerce site with pytest:

from seleniumbase import BaseCase
BaseCase.main(__name__, __file__)  # Call pytest

class MyTestClass(BaseCase):
    def test_swag_labs(self):
        self.goto("https://www.saucedemo.com")
        self.type("#user-name", "standard_user")
        self.type("#password", "secret_sauce\n")
        self.assert_element("div.inventory_list")
        self.click('button[name*="backpack"]')
        self.click("#shopping_cart_container a")
        self.assert_text("Backpack", "div.cart_item")
        self.click("button#checkout")
        self.type("input#first-name", "SeleniumBase")
        self.type("input#last-name", "Automation")
        self.type("input#postal-code", "77123")
        self.click("input#continue")
        self.click("button#finish")
        self.assert_text("Thank you for your order!")

pytest test_get_swag.py

📝 This example tests another e-commerce site with pytest:

pytest test_coffee_cart.py --demo

(--demo mode slows down tests and highlights actions)

📝 This example covers multiple actions with pytest:

pytest test_demo_site.py

Easy to type, click, select, toggle, drag & drop, and more.

(For more examples, see the SeleniumBase/examples/ folder.)

Explore the README:

Get Started / Installation

Basic Example / Usage

Common Test Methods

Fun Facts / Learn More

Demo Mode / Debugging

Command-line Options

Directory Configuration

SeleniumBase Dashboard

Generating Test Reports

▶️ How is SeleniumBase different from raw Selenium? (click to expand)

💡 SeleniumBase is a Python framework for browser automation and testing. SeleniumBase uses Selenium/WebDriver APIs and incorporates test-runners such as pytest, pynose, and behave to provide organized structure, test discovery, test execution, test state (eg. passed, failed, or skipped), and command-line options for changing default settings (eg. browser selection). With raw Selenium, you would need to set up your own options-parser for configuring tests from the command-line.

💡 SeleniumBase's driver manager gives you more control over automatic driver downloads. (Use --driver-version=VER with your pytest run command to specify the version.) By default, SeleniumBase will download a driver version that matches your major browser version if not set.

💡 SeleniumBase automatically detects between CSS Selectors and XPath, which means you don't need to specify the type of selector in your commands (but optionally you could).

💡 SeleniumBase methods often perform multiple actions in a single method call. For example, self.type(selector, text) does the following:
1. Waits for the element to be visible.
2. Waits for the element to be interactive.
3. Clears the text field.
4. Types in the new text.
5. Presses Enter/Submit if the text ends in "\n".
With raw Selenium, those actions require multiple method calls.<

13.1K ·GitHub

SeleniumBase

What is this?

SeleniumBase is an all-in-one Python framework for browser automation — web crawling, testing, scraping, and stealth. Its CDP Mode bypasses bot-detection in Chromium-based browsers, and a Stealthy Playwright Mode extends that to Playwright.

Is it a testing framework or a scraping library?

Both, in one framework: it wraps the Selenium/WebDriver APIs and plugs into test runners like pytest, pynose, and behave, so the same calls power organized E2E test suites as well as crawling and scraping scripts.

How do I get it running?

'pip install seleniumbase' is all it takes ('uv add seleniumbase' works too). For the optional Stealthy Playwright Mode, also run 'pip install playwright'.

Which browsers can it drive — and do I have to babysit chromedriver versions?

Chromium-based browsers; Google Chrome is the default, and unbranded Chromium or Chrome-for-Testing are downloaded automatically if missing. Driver versions are handled for you too — SeleniumBase matches your browser unless you pin one with --driver-version=VER.

Will the bot-detection bypass work on any site?

Not on every site — the README demos passing all BrowserScan checks and a Cloudflare Turnstile challenge, but whatever isn't bypassed automatically falls through to sb.solvecaptcha(), which steps in only when a CAPTCHA is actually on the page.

Is this mainly for QA engineers, or also for scraping?

Both audiences: pytest-based E2E testing is the core, but the same API drives crawling and scraping — and CDP Mode's bot-detection bypass is aimed at protected sites a plain Selenium script can't touch.

Does it matter if I'm on Windows, Mac, or Linux?

Nightly CI exercises the suite on macOS and Ubuntu, and being a pip package it runs wherever Python and a Chromium browser are available. Which Chromium variant you drive is your call — method args include browser='edge' and browser='brave'.

How is it different from just using raw Selenium?

Raw Selenium is bare WebDriver calls. SeleniumBase layers on test-runner integration (pytest, pynose, behave), command-line options, automatic driver downloads, auto-detection of CSS vs XPath selectors, and multi-step methods — self.type() waits for the element to be visible and interactive, clears the field, types the text, and presses Enter if it ends in a newline.

What does CDP Mode get used for in practice?

Stealthy scraping and automation on protected sites: the README demos passing every BrowserScan bot-detection check, bypassing a Cloudflare Turnstile challenge page, and saving Google Search results as PDF, HTML, and PNG files into ./latestlogs/. Playwright can hook into the same stealthy session via Stealthy Playwright Mode.

Is there an MCP server so coding agents can drive it?

Yes — the README points to a seleniumbase-mcp MCP server, a separate package from the main 'pip install seleniumbase' framework.

Where can I find working stealth examples to copy from?

Stealthy CDP Mode examples live in ./examples/cdpmode/, and Stealthy Playwright ones in ./examples/cdpmode/playwright/ — including runs that pass Sannysoft and BrowserScan bot-detection checks.

What are similar projects?

undetected-chromedriver, botasaurus, playwright, ovobrowser, CloakBrowser, turnstile-bypass, invisible_selenium, nopecha-extension

Which topics is it in?

end-to-end-testing, captcha-solving, cloudflare-bypass, web-automation, anti-detection, bot-detection, selenium, e2e-testing, chromium, test-automation, scraping, crawler

Creator: seleniumbase
Size: 15.1 MB
Stars: 13.1K
Updated: CommitOct 16 Releasev4.56.2Oct 16
Age: 12y
Commits · 90 Days

SeleniumBase README

⚙️ Stealthy architecture flowchart:

🌐 CLI Options for Supported Chromium Browsers

🧪 Comprehensive E2E Testing with pytest:

SeleniumBase (seleniumbase/SeleniumBase)

🧪 Comprehensive E2E Testing with `pytest`: