本文详解如何在 seleniumbase 中可靠地触发、等待并验证文件下载，重点解决 js 重载页面下无显式链接时的下载同步问题，并提供断言、路径获取与内容校验的完整实践方案。
本文详解如何在 seleniumbase 中可靠地触发、等待并验证文件下载，重点解决 js 重载页面下无显式链接时的下载同步问题，并提供断言、路径获取与内容校验的完整实践方案。
在使用 SeleniumBase 自动化下载文件（尤其是 JavaScript 渲染的动态导出操作）时，常见痛点是：点击“导出”按钮后浏览器已开始下载，但脚本无法感知下载是否完成，导致提前退出或文件不完整。原 Driver() 实例虽支持 CDP 下载行为配置，但缺乏内置的下载状态监听与文件校验能力；而 SB()（SeleniumBase Test Context）上下文提供了更完善的下载工具链——包括阻塞式下载、文件存在断言、路径解析及内容验证。
✅ 推荐方案：使用 SB() 上下文替代 Driver()
SB() 不仅自动管理 WebDriver 生命周期（无需手动 quit()），还封装了 download_file()、assert_downloaded_file()、get_path_of_downloaded_file() 等专用于下载场景的方法，显著提升可靠性：
新增功能: 1.增加文件下载系统; 2.美化后台登陆界面; 3.完善前后台登陆系统安全性; 4.后台登陆加了验证码; 5.修正组织结构的后台管理; 6.修正所有发现的小错误; 7.美化页面; 后台主要功能如下： 一、系统管理：管理员管理，可以新增管理员及修改管理员密码；数据库备份，为保证您的数据安全本系统采用了数据库备份功能；上传文件管理，管理你增加产品时上传的图片及其他文件。 二、企业信息：可
from seleniumbase import SB
downloads_folder = "./downloads" # 推荐使用相对路径，避免 Windows 反斜杠转义问题
with SB(test=True, headless=False, uc=False) as sb:
# 1. 登录流程（复用原逻辑，语法更简洁）
sb.open("https://new.stamdata.com/app/statistics")
sb.click('button:contains("Account")')
sb.click("div#app div div:nth-of-type(2) span p")
sb.type('input[name="username"]', "xxxxx")
sb.type('input[name="password"]', "xxxxx")
sb.click('button:contains("sign in")')
# 2. 触发导出 & 等待下载完成（关键步骤）
sb.assert_element('button:contains("Excel export (max 50 000 rows)")')
sb.click('button:contains("Excel export (max 50 000 rows)")')
# ✅ 自动等待下载完成，并断言文件存在（默认超时 60s）
expected_filename = "statistics_export.xlsx" # 根据实际导出规则填写（可先手动下载确认名称）
sb.assert_downloaded_file(expected_filename)
# 3. （可选）进一步验证文件内容或完整性
file_path = sb.get_path_of_downloaded_file(expected_filename)
try:
with open(file_path, "rb") as f:
# 检查文件非空（Excel 文件通常 > 1KB）
assert len(f.read()) > 1024, "Downloaded Excel file is empty or corrupted"
print(f"✅ Successfully downloaded and validated: {expected_filename}")
except Exception as e:
raise AssertionError(f"File validation failed: {e}")
# 4. 后续操作（登出等）
sb.click('button:contains("menu")')
sb.click("div#app div div:nth-of-type(3) span p")
sb.click('button:contains("log out")')⚠️ 关键注意事项
-
文件名必须准确：assert_downloaded_file(filename) 依赖精确匹配。若导出文件名含时间戳（如 stats_20240520.xlsx），建议：
- 使用通配符（SeleniumBase ≥ 4.18.0）：sb.assert_downloaded_file("stats_*.xlsx", timeout=90)
- 或先调用 sb.get_downloaded_files() 获取列表后正则匹配。
- 下载目录需明确：SB() 默认使用临时目录，如需指定路径，请初始化时传入 download_folder="./downloads"（注意：test=True 模式下该参数生效）。
- 避免 Driver() + CDP 手动配置：Driver() 的 execute_cdp_cmd("Page.setDownloadBehavior") 易受 Chrome 版本、安全策略影响，且无下载完成回调；SB() 内部已封装健壮的轮询机制。
- Headless 模式兼容性：Chrome 无头模式下部分下载可能被禁用。若遇问题，添加 headless=False 或启用 uc=True（Undetected Chrome）绕过检测。
? 总结
使用 SB() 上下文是 SeleniumBase 中处理文件下载的最佳实践：它将“触发下载 → 等待完成 → 断言存在 → 验证内容”整合为声明式 API，彻底规避手动轮询 os.path.exists() 或 time.sleep() 的不可靠性。对于统计报表、日志导出等高频自动化场景，此方案兼具稳定性、可读性与可维护性。
