SeleniumBase 快速上手：5 分钟搭建浏览器自动化与反检测测试的完整指南

SeleniumBase 快速上手：5 分钟搭建浏览器自动化与反检测测试的完整指南

【免费下载链接】SeleniumBaseAPIs for browser automation, testing, and bypassing bot-detection. Includes CDP Mode: A stealthy configuration for chromium that passes every bot detection test.项目地址: https://gitcode.com/GitHub_Trending/se/SeleniumBase

SeleniumBase 是一个 Python 浏览器自动化框架：网页端到端测试、爬虫抓取、绕过反机器人检测（bot-detection）一套搞定。装好之后，你只需几行代码，就能驱动真实浏览器完成打开、点击、输入和断言。

一句话定位：它是什么

SeleniumBase 把 Selenium、pytest 和隐身浏览器封装进同一个包，给你三类现成的能力：

• 你要写端到端测试 →BaseCase自带等待、断言和截图，测试代码只剩"做什么"。
• 你要爬数据或做自动化脚本 →SB上下文管理器几行代码就能跑，不用写任何配置。
• 你的脚本总被网站识别成机器人 → CDP Mode 用隐身配置启动 Chromium，可通过主流反检测检测站。

五分钟上手：安装与最小配置

🚀 你只需执行一条命令完成安装：

pip install seleniumbase

不需要WebDriver 手动管理——首次运行时它会按浏览器版本自动下载匹配的驱动。零配置即可开跑，下面这个文件就是你全部需要的"最小配置"：

from seleniumbase import BaseCase BaseCase.main(__name__, __file__) # 允许直接用 python 运行 class LoginTest(BaseCase): def test_login(self): self.goto("https://www.saucedemo.com") self.type("#user-name", "standard_user") self.type("#password", "secret_sauce\n") # \n 自动提交 self.assert_element("div.inventory_list")

运行pytest test_login.py -v（或直接python test_login.py），看到 PASSED 就算跑通了。注意type()会自动等待元素可见、清空旧内容再输入，你不用手写time.sleep。

实战：从零搭一个电商登录自动化测试

以开源演示商城 saucedemo 为例，一步步把"登录 → 进商品页 → 退出"这条流程搭出来。

第 1 步：打开登录页并填表单。就是上面最小文件里的goto+ 两次type。跑完后浏览器停在商品列表页，assert_element("div.inventory_list")确认你已经登录成功。

第 2 步：验证页面内容并退出。加几行断言，让测试真正"有意义"：

self.assert_exact_text("Products", "span.title") self.click('button[name*="backpack"]') self.assert_exact_text("Your Cart", "span.title") self.js_click("a#logout_sidebar_link") self.assert_element("div#login_button_container")

做完之后，这条测试覆盖了"登录、加购、看购物车、登出"四个状态。仓库里有一份完整成品可以参考：examples/test_login.py，它就是这个流程的完整版。

第 3 步：加个演示模式。运行pytest test_login.py --demo_mode，每一步操作会在浏览器里高亮并放慢，方便给别人演示测试在干什么。

第 4 步：切换到隐身模式跑登录。如果目标网站有反检测，把驱动换成 CDP Mode（一种用 Chromium 开发者协议直接启动隐身浏览器的模式），其余 API 基本不变：

from seleniumbase import sb_cdp sb = sb_cdp.Chrome() sb.goto("https://seleniumbase.io/simple/login") sb.type("#username", "demo_user") sb.type("#password", "secret_pass") sb.click('a:contains("Sign in")') sb.assert_exact_text("Welcome!", "h1") sb.quit()

直接python运行即可，登录、断言、关浏览器一气呵成，且能顺利通过主流 bot 检测站。更多 CDP 写法见 examples/cdp_mode/。

个性化：主题与样式

框架的行为细节（等待时长、窗口大小、无头模式分辨率）都集中在一个设置文件里，你复制一份再改，运行时用--settings指过去即可：

# custom_settings.py MINI_TIMEOUT = 2 # 短等待（秒） SMALL_TIMEOUT = 7 # 常规等待 LARGE_TIMEOUT = 10 # 长等待 HEADLESS_START_WIDTH = 1440 # 无头窗口宽度 SCREENSHOT_WITH_BACKGROUND = True

pytest test_login.py --settings=custom_settings.py

命令行还能临时改"外观"：--user-agent换 UA、--mobile模拟手机、--ad_block屏蔽广告、--start-maximized全屏打开。完整开关清单在 help_docs/customizing_test_runs.md，默认值的出处是 examples/custom_settings.py。

常见坑与 FAQ

⚠️ 新手最容易在这四处卡住：

1. 驱动下载失败 / 版本对不上。SeleniumBase 会自动匹配驱动，网络不通时会报错。解法：换网络后手动执行python -m sbase get chromedriver预下载，或pip install -U seleniumbase升级到最新版（驱动匹配规则会持续更新）。
2. 提示"测试必须在 pytest 下运行"。BaseCase的测试文件加一行BaseCase.main(__name__, __file__)，就能用python 文件名.py直接跑。
3. 元素找不到、测试时过时不过。SeleniumBase 的方法默认会自动等待，多数"时好时坏"是选择器写错了。解法：按 F12 在开发者工具里核对 CSS 选择器；页面确实慢就加timeout参数或在 custom_settings.py 里调大等待值。
4. 网站把你的脚本识别为机器人。普通模式下换 UA 不一定够。解法：给 pytest 加--uc开启 UC Mode，或直接用上面的sb_cdp.Chrome()，两者文档见 help_docs/uc_mode.md 和 help_docs/cdp_mode_methods.md。

深入指南与下一步

文档入口都放在 help_docs/，建议按下面三个方向挑一个继续：

• 反检测进阶：读 help_docs/cdp_mode_methods.md，跑通 examples/cdp_mode/ 里的检测站示例，让你的爬虫和测试在严格站点上也能稳定运行。
• 更快写测试：用 Recorder 模式（help_docs/recorder_mode.md）边点网页边生成代码，再用 GUI Commander（help_docs/commander.md）批量管理用例。
• 可视化回归：参考 examples/visual_testing/，给关键页面截图比对，页面一改版测试就变红。

控制台命令入口在 sbase/，常用方法速查在 help_docs/method_summary.md。把上面 5 分钟的最小测试改成你自己网站的登录页，就是下一步。🔍

【免费下载链接】SeleniumBaseAPIs for browser automation, testing, and bypassing bot-detection. Includes CDP Mode: A stealthy configuration for chromium that passes every bot detection test.项目地址: https://gitcode.com/GitHub_Trending/se/SeleniumBase