必须先运行playwright install chromium（或firefox/webkit），UI模式依赖Playwright自带浏览器二进制，不支持系统浏览器直连，否则报ECONNREFUSED或“找不到浏览器”。
Playwright UI模式启动失败：playwright codegen 找不到浏览器或报错 BrowserType.connect_over_cdp: connect ECONNREFUSED
Playwright 的 UI 模式（即录制/调试界面）核心是 playwright codegen 命令，它依赖本地已安装的 Playwright 浏览器二进制文件，不是系统全局浏览器。常见失败原因是没先执行安装步骤，或误用系统 Chrome 路径。
实操建议：
- 必须先运行
playwright install chromium（或firefox/webkit），不能跳过——这会下载 Playwright 自带的、与 API 完全兼容的浏览器版本 - 避免加
--browser-channel system或手动指定/usr/bin/google-chrome，UI 模式不支持系统浏览器直连（CDP 连接会被拒绝） - 若用 VS Code，确保终端在项目根目录下执行命令，且
playwrightCLI 已被正确识别（可通过npx playwright codegen绕过全局安装问题） - Windows 用户注意路径空格：如果项目在
C:\Users\John Doe\project，建议改用短路径或移至无空格目录，否则codegen可能静默崩溃
在 Python 脚本里启用 UI 调试：不是调用 playwright.sync_api.sync_playwright() 就能弹窗
Playwright 的 UI 模式本质是独立进程（基于 Chromium DevTools 协议），Python 脚本本身无法“内嵌”或“触发”该界面。所谓“Python 中使用 UI 模式”，实际是指用 codegen 录制行为生成 Python 代码，再在脚本中复现 + 调试。
实操建议：
- 录制时加
--target python：例如playwright codegen --target python https://example.com，生成的是可直接运行的.py文件 - 生成的代码默认用
sync_playwright()，但调试阶段建议改用async_playwright()+async with，避免阻塞导致 UI 响应卡顿 - 想边跑脚本边看浏览器动作？得显式传参
headless=False和slow_mo=500（单位毫秒），例如：browser = playwright.chromium.launch(headless=False, slow_mo=500)
- 别依赖 IDE 的“Run”按钮直接启 UI 模式——它不会自动拉起录制界面；UI 模式只存在于
codegen命令生命周期内
录制生成的代码跑不通：元素定位失效、TimeoutError 频发
codegen 默认用 get_by_role() 或 get_by_text() 等“面向用户”的定位器，比 query_selector() 更健壮，但前提是页面 DOM 加载完成、无障碍属性（aria-*）存在且准确。很多老系统或未适配的前端会缺失这些属性，导致生成代码一运行就超时。
实操建议：
- 录制前先手动打开 DevTools → Elements 面板，检查目标按钮/输入框是否有
role、name、aria-label；没有的话，codegen会退化为nth()或 CSS 选择器，稳定性差 - 生成后立即替换脆弱定位器：把
page.get_by_role("button", name="Submit").click()改成page.locator('button[type="submit"]').click()，并加显式等待：page.locator('button[type="submit"]').wait_for(state="visible", timeout=10000) - 遇到单页应用（SPA）路由跳转，
codegen不会自动插入page.wait_for_url()，需手动补上，否则后续操作在错误页面执行 - 禁用缓存和广告拦截插件：录制时浏览器扩展可能干扰网络请求或注入 DOM，导致定位器匹配失败
为什么 playwright show-trace 比 UI 模式更适合深度调试？
UI 模式只解决“录制→生成→粗略验证”环节，真正排查超时、状态不一致、JS 执行异常等问题时，trace 是更可靠的可视化手段——它记录了完整时间线、网络请求、截图、控制台日志和 JS 堆栈。
实操建议：
- 运行脚本时加
--tracing on参数（CLI）或 Python 中启用 tracing：context = browser.new_context(tracing=True)
，结束后调用context.tracing.stop(path="trace.zip") - 用
playwright show-trace trace.zip打开交互式面板，可逐帧查看 DOM 快照、筛选 network 请求、定位 JS 错误源码行 - Trace 文件体积大，别在 CI 环境默认开启；本地调试时也建议只对单个 test case 启用
- 注意：trace 不捕获 console.log，但会记录 uncaught exception 和 fetch/XHR 错误，这对诊断 401/500 类问题很关键
UI 模式只是起点，真正要稳住自动化用例，得靠 trace + 显式等待 + 定位器降级策略。很多人卡在“录完就能跑”，却忽略了页面加载节奏和 DOM 动态性——那才是超时和 flaky 的根源。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
