seleniumbase/SeleniumBase

One framework for browser automation, web scraping, and testing.
Includes stealth options for bypassing bot-detection and CAPTCHAs.
🚀 Start |
🏰 Features |
🎛️ Options |
📚 Examples |
💻 Scripts |
🗾 Locale
📗 API |
📘 Stealth API |
🔠 DesignPatterns |
🔴 Recorder |
📊 Dashboard
🎖️ GUI |
📰 TestPage |
👤 UC Mode |
🐙 CDP Mode |
📶 Charts |
🖥️ Farm
👁️ How |
🚝 Migration |
🎭 Stealthy Playwright |
🛂 MasterQA |
🚎 Tours
🤖 MCP |
🟨 JS Mgr |
🌏 Translator |
🎞️ Presenter |
🖼️ Visual |
🗂️ CPlans
--------
🥷 CDP Mode makes browser automation undetectable to anti-bot services and adds stealth to stock Playwright . Also includes code for bypassing CAPTCHAs.
📚 Example scripts that start or end with " test " are specifically designed to be run with pytest . Other scripts run directly with raw python . (Those start with " raw " to avoid confusion.)
--------
📝 Here's an example with seleniumbase sb_cdp ( Pure CDP Mode ): (It bypasses both BrowserScan AND Sannysoft Bot-Detection)
(All BrowserScan bot-detection tests passed successfully)
(All Sannysoft bot-detection tests passed successfully)
--------
📝 Here's another example with seleniumbase sb_cdp ( Pure CDP Mode ): (It performs various browser actions and bypasses a Cloudflare Turnstile)
✅ sb.solve_captcha() handles CAPTCHAs that aren't bypassed automatically. (If called when there's no CAPTCHA on the page, then nothing happens / no-op.)
ℹ️ sb.assert_* methods wait up to 7 seconds for the expected condition to occur.
--------
📝 This script scrapes Hacker News listings:
--------
📝 This script bypasses Cloudflare's challenge page with UC + CDP Mode:
--------
🧪 End-to-End Testing examples are located in ./examples/.
🐙 Stealthy CDP Mode examples are located in ./examples/cdp_mode/.
🎭 Stealthy Playwright examples are located in ./examples/cdp_mode/playwright/.
--------
🌐 CLI Options for Supported Chromium Browsers
💡 You can set which Chromium browser to use via command-line parameters:
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:
--------
⚙️ Stealthy architecture flowchart:
--------
🧪 Comprehensive E2E Testing with pytest :
📝 This script tests an e-commerce site: (Runs with pytest ):
🥷 For stealth with pytest, add --uc as a command-line option.
--------
📝 This script tests a different e-commerce site with pytest :
> ( --demo mode slows down tests and highlights actions)
--------
📝 This script covers multiple actions with pytest :
> Easy to type, click, select, toggle, drag & drop, and more.
📚 For more scripts, 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.
💡 SeleniumBase uses default timeout values when not set:
✅ self.click("button")
With raw Selenium, methods would fail instantly ( by default ) if an element needed more time to load: