Playwright codegen与AI补全：UI自动化脚本的工程化实践

运行了近一年的 UI 自动化项目后，我愈发觉得“录制脚本”这件事被很多人低估了。尤其当 AI 编程助手越来越普及的时候，一说到生成自动化脚本，大家下意识就想让 AI“从零写一段”。但我在自己的多个项目里，几乎都是反着来的：先用 Playwright codegen 快速把人为操作录成原始脚本，人工只做轻量整理，再把脚本交给 AI 去补全、重构、抽取方法。这样的配合方式省下的成本非常直观，尤其在按 token 计费的工作流里，省下来的可都是真金白银。

先说结论：UI 自动化的最大瓶颈从来不是“会不会写代码”，而是“有多大把握让脚本稳定复现真实操作”。Playwright codegen 的意义就在于它先把“人怎么点”这件模糊的事变成了精确的、可回放的代码，AI 再在这些真实代码上工作，就能避开最常见的幻觉和错误假设。这篇内容我会完整拆解我的实操路径、每个决策背后的理由，以及踩坑之后沉淀下来的一套可复用流程，希望对正在纠结“要不要从纯 AI 生成脚本”的你有点帮助。

1. 为什么没让 AI 从零生成整段脚本

很多人一开始就打开 AI 编程助手，输入“帮我写一个登录并下单的 Playwright 脚本”，看起来高效，实际上一旦页面结构稍微复杂一点，AI 生成的选择器就可能全是臆想出来的，运行起来处处报错。问题不在 AI 的编程能力，而是它看不到你那个真实页面的 DOM。

1.1 一个肉眼可见的成本对比

我之前接过一个模拟项目 X 的 Web 控制台自动化需求，脚本需要覆盖登录、切换组织、新建工单、上传附件、校验列表结果这五个核心场景。如果直接让 AI 从零生成，每条命令都要反复调试，给 AI 的上下文得把页面结构、接口返回、测试数据全都塞进去，一次对话消耗的 token 量非常夸张。更要命的是，AI 经常生成一个看起来很完整的脚本，但里面每个选择器它都得“猜一遍”，猜错一轮，来回折腾七八轮，时间和成本全烧在那了。

同样的需求，我先用 codegen 录一遍，五分钟录完，生成的基础脚本大约 200 行。再把这个 200 行的真实代码扔给 AI，告诉它“基于这段代码把公共逻辑抽出来，补上断言和等待策略”，AI 一来不需要去猜 DOM，二来它只做增量改造，上下文本体就是真实代码，token 消耗大幅减少，生成的代码还基本能跑。

后来我算过一笔账：纯 AI 生成并调通的成本，大概是“codegen 录制 + AI 重构”这个方案的 5 到 10 倍。如果脚本量再翻一倍，这个差距还会继续拉大。

1.2 codegen 录制是“语义对齐”的天然入口

UI 自动化的难点从来不是语法，而是“人和机器对界面的理解不一致”。人眼看到的是一个写着“提交”的按钮，而代码里它可能是<button>playwright codegen http://localhost:8080/demo

启动之后，Playwright 会同时打开一个浏览器窗口和一个代码生成面板。浏览器窗口里你做的每一次点击、输入、跳转，都会被实时翻译成代码，显示在右侧面板上。如果操作过程中切换了标签页，面板顶部会自动生成page.expect_popup()之类的等待逻辑，非常贴心。

有一点值得注意：codegen 生成的代码默认带有page.pause()调用，这个调用会在脚本运行到对应位置时暂停，方便你在真实环境里继续手动操作。我的习惯是生成之后先把所有pause()批量删掉，否则脚本在 CI 环境里跑到一半就会一直停顿在暂停状态。

2.2 配置 AI Skills：把团队约定塞进上下文

这里提到的 Skills，简单说就是把一段“关于怎么帮你做 UI 自动化”的方法论固化成可复用的指令。你可以把它理解成 AI 助手的角色说明书：每次调用 AI 时，它都会自动加载这份说明，按你预先定义的规则来思考和输出。

我自己维护了一个专门用于 Playwright 自动化的 Skill，核心内容包含这么几块：第一，定位器优先级规则，约定优先使用get_by_role和get_by_test_id，其次才考虑get_by_text和locator；第二，等待策略约定，默认使用expect断言式等待，而不是固定sleep；第三，公共方法抽取约定，凡是重复出现两次以上的操作必须抽成方法；第四，一个稳定的“页面对象”模板，让 AI 补全时直接套用我们团队已有的风格。

配置 Skills 的过程不需要写代码。大多数 AI 编程助手的配置入口里都有“自定义技能”或“指令”功能，把上述约定写成结构化文本保存即可。这样后续 AI 在补全脚本时，输出的代码风格会自动和我们现有仓库保持一致，省掉大量人工 review 后返工的麻烦。

3. 人工录制实操：从浏览器操作到可维护脚本

录制听起来简单，但很多人在最初几步就会踩坑。我总结了一套可以稳定复现的完整流程，每一步都有明确的意图。

3.1 第一次启动 codegen 我做了什么

以某学习平台的 Web 控制台为例，我需要录制一个完整的“创建线上课程”流程，大致步骤是登录后台、进入课程管理、点击新建、填写表单四要素、选择封面、上传 PDF、保存并确认。第一次启动 codegen 后，我不会上来就操作，而是先手工清理一下页面上的弹窗、公告这类干扰元素。录制路径里每多一个无意的操作，脚本就会多加三五行噪音代码，后期维护成本都是翻倍的。

正式开始后，我会有意识地放慢点击节奏，每次操作后停顿一两秒，等页面稳定再执行下一步。这可以让 codegen 更精准地区分“一次点击触发多步异步”和“连续两次独立操作”，从而生成更合理的等待逻辑。录制过程中我还会观察右侧面板的代码变化，一旦发现某个操作生成了特别复杂的选择器，就会在当前页停下来，先在浏览器里打开开发者工具确认那段 DOM，再回到 codegen 继续。

录完以后，保存的脚本不会拿来直接用，而是会先经过一轮“人工降噪”：把录制过程中生成的临时变量、不必要的中间步骤、重复导航全部精简。比如 codegen 经常会在登录成功跳转后额外生成一个page.goto()调用，这在录制流程里是冗余的，我会备注给 AI，让它后续重构时把这部分剔除。

3.2 录制过程中的结构优化技巧

录制不是机械地“点一遍完事”，我一般会把一个完整业务流拆成三段录制：前置准备、核心操作、结果校验。前置准备包括登录和数据初始化，通常只录一次，存成独立的login配置；核心操作对应业务主链路，录制成连贯的 action 序列；结果校验则单独录制，比如列表出现预期文案、表单状态变为已完成等。

这样的拆分带来的直接好处是：AI 补全时职责清晰，前置准备可以复用，核心操作方便定位失败节点，结果校验可以被抽成公共断言工具。多个业务流程出现交叉时，也可以把已经录好的片段当作“模板”拼接使用，而不是每次从头录一遍。

另外一个非常实用的技巧是：在录制前先把页面里不稳定的元素用代码临时隐藏或者填充默认值。比如某些下拉框的数据来自外部接口，每次运行数据顺序都可能变化，录制时选中第三项生成的索引，下次运行可能就选错。我遇到这种情况会在录制前用开发者工具给下拉框固定几个选项，或者手动在控制台把接口返回 mock 成固定顺序，录出来的操作才具备可重复性。

4. AI 补全脚本：让机器补全你不想写的那 70%

codegen 解决的是“把操作变成代码”，但录出来的脚本通常是线性的、机械的，离“可维护的工程代码”还有一段距离。AI 补全这一步，就是把这部分差距填上的关键环节。

4.1 给 AI 喂什么样的“现场材料”

我见过很多人在这一步犯同一个错误：直接丢给 AI 一句“帮我优化这段代码”，然后粘贴 200 行录制脚本，AI 给出的结果往往只是把代码压缩了一遍，实际价值不大。要让 AI 真正补全得漂亮，必须在上下文里提供“现场材料”。

现场材料包括四部分：录制的原始脚本、页面对象的设计规范、业务操作的关键约束，以及少量代表性的 DOM 结构。举例来说，我会在提交给 AI 的提示词里写清楚：“第一个文件是刚用 codegen 录制的创建课程脚本；第二个文件是我们项目的页面对象模板；这段逻辑里，上传附件必须走本地路径，不能用绝对路径；表单提交后页面跳转的 URL 会包含一个动态课程 ID，断言结果时不要写死完整 URL。”

这样做的好处是，让 AI 的每一次补全都有明确边界，它不用去猜你的业务要求，也不需要在代码风格上做无畏探索。它会像团队里的一个老手一样，根据你的约定来写，而不是照着它自己的九九八十一套模板来套。

AI 补全的典型任务一般是这么划分的：把线性脚本里的重复操作抽成页面对象方法；把散落的断言统一收敛为assert_result这类公共断言函数；把固定等待替换为条件等待；把硬编码测试数据提取为配置项；把登录逻辑单独抽离成可复用的 session fixture。

4.2 典型补全思路与代码形态

拿一个真实例子说。codegen 录制出的登录部分，通常是一大段连续的page.fill()和page.click()。如果不能接受让这些裸代码散落在用例里，就需要把它收进一个login_page对象。我给 AI 的提示词会是：

把下面这段录制脚本中的登录操作重构为 LoginPage 类的方法， 返回值为登录成功后的 DashboardPage 实例。 保持原有的定位器不变，但把用户名和密码替换为构造参数。

AI 给出的结果通常是这样的：

class LoginPage: def __init__(self, page: Page): self.page = page def goto(self): self.page.goto(LOGIN_URL) def login(self, username: str, password: str) -> "DashboardPage": self.page.get_by_label("用户名").fill(username) self.page.get_by_label("密码").fill(password) self.page.get_by_role("button", name="登录").click() self.page.wait_for_load_state("networkidle") return DashboardPage(self.page)

补全完成后，我一般会人工把关两个重点：一是定位器是否被 AI 擅自修改；二是方法命名是否符合团队规范。在 Skills 里把“禁止修改已有定位器”写死之后，这类问题基本就绝迹了。

再看一个补全断言的案例。录制脚本里，点击保存后可能只是什么都没有执行，操作员看到页面上出现感叹号提示就认为完成了。AI 补全阶段，我会要求它在保存后用expect轮询“课程列表第一行的课程状态”是否为“审核中”，同时捕获可能的 toast 提示文本。最终它会在录制代码之外，补上一段稳定、可重试的断言逻辑，这恰恰是纯录制脚本最缺乏的部分，也是 AI 补全的价值所在。

5. 常见问题与排查技巧实录

脚本跑久了，总会遇到各种不稳定的情况。下面这几个问题，是我这套流程中出现频率最高的，每一个我都实际排过，解决方案也验证过多次。

5.1 录制回放就挂的 5 个原因

录制过程中一切顺利，一执行回放就失败，原因通常集中在五处。第一，录制的操作里包含了鼠标轨迹和悬停动作，这类动作在无头模式下会被忽略，直接删掉即可。第二，录制时页面处于某个弹窗的遮挡下，回放时弹窗没有出现，导致点击目标被遮挡判断错误，我会在录制前先统一处理弹窗。第三，选了带时间依赖的定位器，比如“今天”这个动态文案，第二天回放自然失败。第四，把鼠标移动和点击混合进了录制，生成hover_click的复合交互，在某些浏览器内核上稳定性极差，我会手动把它拆成独立的 hover 和 click。第五，录制时使用了物理键盘输入特殊字符，比如@和#，在部分系统键盘布局下，回放环境按键被映射成其他字符，输入断言就会失败。这五个原因覆盖了我见过的绝大多数回放失败场景。

排查的时候我通常会在本地先用PWDEBUG=1环境变量启动有头调试模式，单步查看每一步操作落在哪个元素上。这比一遍遍跑全量脚本高效得多，因为你能直接看到选择器匹配到的元素是不是你想操作的那个。

5.2 选择器维护的坑

选择器维护是长期运行自动化最大的噩梦。这套方案里，我总结了一条经验：凡是 codegen 自动生成的复杂 XPath，都值得花时间替换成更稳定的语义定位器。

举一个典型例子，codegen 录制的表格行选择器可能长这样：

page.locator("div.ant-table-row").filter(has_text="课程A").get_by_role("button", name="编辑")

这个写法回放往往没问题，但一旦课程名变了、表格多了排序，或者某个按钮文案调整，脚本就会挂。我的做法是在录制完成后，直接对关键交互元素打上>