你可能刚被安排写自动化测试，搜索一圈发现全是零散代码片段：装完库不知道该建几个文件，用例写出来跑一次就挂，报错也看不懂是定位问题还是等待问题。这篇按一个新手能照着做的顺序，把 Playwright Python 的起步动作拆成环境准备、第一条用例、目录组织、调试排错四段，重点讲顺序和判断标准，具体版本与依赖数字到站内页面核对。
刚被安排写自动化测试的人，最常见的卡点不是不会写代码，而是不知道先做什么、后做什么。搜索出来的东西大多是零散片段：一个启动浏览器的例子、一段断言的写法、一条报错截图，看着都懂，合在一起就跑不起来。这篇按一个新手能照着做的顺序往下推：先把环境和依赖备齐，再跑通第一条用例，然后处理等待与定位这两类高频失败，最后讲目录怎么分、挂了怎么查。
写作时不给具体版本号和数字，因为这些东西变动快，写死了反而误导。用哪个解释器版本、装哪个依赖、浏览器内核多大，去站内的模型与工具资料库核对当时的说明；本文只讲顺序、判断标准和不适用的情况。
第一步：环境与依赖怎么备齐
第一步的核心判断标准只有一句话：能起浏览器、能打开一个空白页、能正常关闭，三件事都过才算环境就绪。很多人装完 Python 包就以为完事了，其实浏览器内核是单独安装的，两个步骤都成功才行。装失败的原因大多是网络或镜像，先换源再重试，别急着怀疑代码。
- 建虚拟环境在项目目录下创建并激活虚拟环境，把依赖和系统里的 Python 包隔开。验证方式：激活后执行 python -c 打印解释器路径，确认指向项目目录而不是系统目录。
- 确认解释器满足要求去站内资料库核对当前 Playwright Python 对解释器版本的要求，低于要求的版本直接升级，不要靠改代码绕过。
- 装 Playwright 包用包管理器在虚拟环境里安装，确认命令行工具可用。验证方式：执行 playwright 的版本命令，能打印信息就说明包本身没问题。
- 单独装浏览器内核再执行一次浏览器安装命令。失败先换镜像源重试；不要用系统自带浏览器顶替，内核版本和库不匹配会出现难以定位的启动报错。
- 跑通官方示例用一个最小示例启动、打开空白页、关闭，逐个确认三件事都成功，再往下写业务用例。
第二条：第一条用例从哪下手
第一个目标页面要选静态、无需登录、元素稳定的，比如一个公开的介绍页。别一上来就挑登录后带异步加载的后台系统，那种页面失败原因会混在一起，你分不清是定位错了、等待不够还是数据没准备好。第一条用例的目的不是覆盖业务，是把整条链路走通。
from playwright.sync_api import sync_playwright；with sync_playwright() as p:； browser = p.chromium.launch()； page = browser.new_page()； page.goto("https://example.com")； assert page.title() != ""； browser.close()这条链路固定下来以后，再考虑抽成 fixture 或页面对象。顺序别反：先能跑，再谈复用。定位优先用语义化方式和角色属性，别直接抄浏览器开发者工具生成的超长 CSS 链，那种写法页面小改一次就失效。另一个新手常忽略的点是断言写法——要断言页面上应该出现什么，而不是打印内容靠人眼看，否则用例不算真正的自动化。
第三条：等待与定位，八成失败都出在这
新手写用例挂掉，绝大多数不是逻辑写错，而是等待和定位的问题。优先用框架内置的自动等待能力，别到处写固定睡眠。固定睡眠既拖慢速度又不稳定，开发机快的时候够用，机器一慢照样挂，而且掩盖了真正的时序问题。
| 报错现象 | 优先怀疑 | 处理方向 |
|---|---|---|
| 元素找不到 | 选择器写错或页面没加载完 | 先确认页面状态，再核对选择器是否唯一 |
| 找到但不可点击 | 被弹窗遮挡或未滚动到可视区 | 处理遮挡、滚动与元素状态 |
| 时好时坏 | 用了固定睡眠或异步未结束 | 换成显式等待条件 |
| 定位到多个元素 | 选择器范围太宽 | 缩小范围或改用角色属性定位 |
- 页面是否真的加载完，还是只是请求发出去了
- 目标元素是否在 iframe 或多窗口里，需要先切换上下文
- 是否被弹窗、公告条或悬浮层遮挡
- 选择器是否匹配到多个元素，取到的是不是想要的那个
- 元素当前是否处于可交互状态，而不是仅存在
把定位器集中管理，页面一改只改一处。散落在各个用例里的硬编码选择器，是后期维护成本的主要来源。这套判断标准不适用于页面本身就是流式渲染、元素永远在变的场景，那种情况要先和开发确认有没有稳定的测试标识可用。
第四条：目录组织与调试排错顺序
小团队起步按四类分目录就够了：用例、页面对象、公共工具、测试数据。先别急着上复杂分层，跑通之后再按真实痛点重构。用例命名要能一眼看出测的哪个场景，失败列表本身就是一份缺陷清单，比事后整理报告更有用。
失败时的排查顺序是：先看框架生成的执行报告、截图和录像，再决定是改代码还是提缺陷。直接重跑容易把偶发问题当成环境问题忽略掉。调试周期长时用调试模式逐步执行，比反复加打印快得多。稳定但慢的用例再考虑并发执行，顺序别搞反——先稳再快，反过来只会得到一堆随机失败。
什么情况下不该选它：如果你的目标只是登录后抓一批数据做一次性分析，用请求库更省事；如果系统大量依赖老式桌面控件或原生客户端，浏览器自动化帮不上忙；如果团队没有人愿意长期维护用例，那自动化写出来只会慢慢腐烂，不如先把手工用例整理清楚。
下一步把环境清单和定位器管理规范先落到项目里，再去站内资料库核对依赖要求与浏览器内核说明，顺手看看工具目录里还有哪些能省掉重复劳动的小工具。→常见问题
完全没有编程基础，能直接学 Playwright Python 吗？
不建议。它需要你至少能读懂变量、函数和异常，还要会用命令行装包。零基础先补 Python 基础与基本断言概念，再上手会顺很多。如果你只是想验证接口通不通，用现成的接口测试工具更省事，不必先啃代码。
Playwright 和别的浏览器自动化方案怎么选？
看两点：一是团队已有技术栈，Python 团队选它学习成本最低；二是是否需要跨浏览器与移动端模拟、是否在意自动等待带来的稳定性。如果只是偶尔录一段操作，录屏式工具更快。各家差异可以到 /ai-nav/category/ai-coding 对照现有工具分类。
用例本地能跑，放进流水线就失败，先查什么？
按这个顺序：运行环境的浏览器内核是否装好、屏幕尺寸与语言设置是否一致、被测环境地址是否指到正确环境、是否有并发跑同一个账号导致互相踢下线。把这四项对齐后仍失败，再去看报告里的截图定位具体步骤。
