playwright录制脚本原理：从注入脚本到locator生成的完整链路

1. 录制按钮点下去之后浏览器里到底发生了什么Playwright 的codegen或者 VS Code 插件里的录制按钮表面上看只是打开了一个新浏览器窗口鼠标划过元素会高亮点一下就在右侧生成一行page.getByRole(...)或者page.locator(...)。很多人第一次用会觉得这是「魔法」但只要你想排查「为什么我点了一个按钮它生成的 locator 却指向了旁边的 div」或者「为什么录制时高亮框不跟着鼠标走」就必须把这条链路拆开看。这条链路的核心其实只有三件事第一Playwright 在页面里注入了一段脚本第二这段脚本监听 DOM 事件并把事件目标转成 locator第三宿主进程VS Code 插件或 CLI把 locator 序列化成代码写进文件。理解这三步之后录制失效基本都能定位到具体环节。这篇文章面向两类人一类是想搞明白录制底层机制、不想只当「录制按钮操作员」的开发者另一类是录制时遇到高亮错位、locator 生成不合理、注入脚本没生效需要按链路排查的人。我会从注入脚本的挂载点讲起给出可复制的配置片段再走一遍验证录制链路的操作步骤最后把常见的坑列出来。需要说明的是下面涉及的源码路径以 playwright-core 的src/server/injected目录为参照不同版本文件名可能微调但结构一致。你不需要改 Playwright 源码但需要知道它在哪里才能在出问题时知道去看什么。2. 前置准备用 TaoToken 拿到可调用的模型与 Key在动手验证录制链路之前如果你打算把录制生成的脚本接到一个能自动补全、能解释 locator 的编码助手流程里建议先把调用凭证准备好。我平时用的是 TaoToken 这个平台它的接口兼容主流 SDK 的调用方式配置成本低。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台可以创建 API Key。API 基址是 https://taotoken.net/api 注意这个地址不带 UTM 参数直接填到 SDK 的base_url里即可。如果你只是想让模型帮你解释一段录制出来的 locator 为什么这么生成用模型对话页就够了https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你是要长期跑编码任务、让 Agent 反复读写测试文件那更适合用 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Key 的管理在控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 具体的 Key 创建页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。拿到 Key 之后先做一次最小验证确认凭证可用再往下走录制链路的排查。这一步不要跳过因为后面如果录制脚本生成正常但你的辅助工具调不通很容易误判成录制本身的问题。curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 用一句话解释 Playwright locator 的作用}] }返回里能看到正常的choices结构就说明 Key 和基址都没问题。这一步和录制链路本身是解耦的但它是后面「让模型帮你分析 locator 生成结果」的前提。3. 注入脚本的挂载点与事件捕获配置Playwright 录制能力的起点是在目标页面里注入一段脚本。这段脚本的源码位于playwright-core/src/server/injected/目录下其中recorder/recorder.ts是录制逻辑的主体。它做的事情可以概括为在document上挂载一系列事件监听器把用户操作翻译成 Playwright 的语义。在recorder.ts里有一个RecordTool接口定义了onClick、onInput、onMouseMove等方法。以onInput为例它拿到事件目标target后会依次判断这个元素是textarea、select还是checkbox再根据类型返回不同的录制结果。这就是为什么你在输入框里打字录制出来的是fill()而在下拉框里选择录制出来的是selectOption()。事件监听器的挂载方式本质上是在document上做事件委托。下面这段是简化后的结构帮助你理解注入脚本的挂载点// 简化示意非源码原文 document.addEventListener(click, event { const target deepEventTarget(event); if (!target.isConnected) return; recorder.onClick(event, target); }, true); document.addEventListener(input, event { const target deepEventTarget(event); recorder.onInput(event, target); }, true); document.addEventListener(mousemove, event { const target deepEventTarget(event); recorder.onMouseMove(event, target); }, true);注意deepEventTarget这个方法它负责穿透 Shadow DOM 拿到真实的事件目标。如果你的页面大量使用 Web Components录制时高亮框错位往往就是这一层没处理好或者目标元素在 shadow root 里而选择器生成时没有带上穿透语法。onMouseMove是理解 locator 生成的最佳入口。它的逻辑是拿到 hover 的元素调用injectedScript.generateSelector()生成选择器然后更新高亮模型。源码里可以看到它先判断this._hoveredElement target如果没变就直接返回避免重复计算。这个细节解释了为什么鼠标在同一个元素上移动时高亮不会闪烁。如果你要在自己的调试环境里观察注入脚本是否生效可以在启动录制时打开 DevTools在 Console 里检查window.__playwright__相关的挂载对象不同版本命名可能不同。更稳妥的方式是直接在document上打断点看事件监听器是否被触发。4. locator 生成链路从 generateSelector 到唯一性去重录制链路里最值得细看的是 locator 的生成。核心函数是generateSelector它定义在injectedScript中被recorder.ts调用。这个函数的目标是给定一个 HTML 元素生成一个或多个唯一的选择器并返回匹配的元素列表。它的执行流程大致如下。首先调用injectedScript._evaluator.begin()开始评估并启用 ARIA 缓存。如果选项里带了forTextExpect会尝试生成一个带文本的选择器否则会先在目标元素的父级或 shadow host 里找符合特定角色的元素比如button、select、input、[rolebutton]、[rolecheckbox]、[roleradio]、a、[rolelink]。这一步是 Playwright 偏好语义化 locator 的原因——它优先往 role 上靠而不是直接甩一个 CSS 路径。接下来根据options.multiple决定生成一个还是多个选择器。当multiple为真时它会同时生成带文本和不带文本的版本如果带 CSS ID 还会再生成去掉 ID 的版本最后用Set去重。源码里这段逻辑很关键// 简化示意 if (options.multiple) { const withText generateSelectorFor(injectedScript, targetElement, options); const withoutText generateSelectorFor(injectedScript, targetElement, { ...options, noText: true }); let tokens [withText, withoutText]; cacheAllowText.clear(); cacheDisallowText.clear(); if (withText hasCSSIdToken(withText)) { tokens.push(generateSelectorFor(injectedScript, targetElement, { ...options, noCSSId: true })); } tokens tokens.filter(Boolean); selectors [...new Set(tokens.map(t joinTokens(t!)))]; }去重这一步是为了保证生成的选择器列表里没有重复项同时保留多个候选方便你在录制结果里右键切换。这也是为什么录制出来的 locator 有时候会给你「多个选项」——它不是随便生成的而是按优先级排好序的候选集。onMouseMove里调用generateSelector时传的是multiple: false所以高亮时只取第一个选择器。而真正点击录制时可能会拿到多个候选。理解这个差异能解释「为什么高亮显示的 locator 和最终写入文件的 locator 不完全一样」。如果你想让生成的 locator 更稳定可以在录制前配置testIdAttributeName让 Playwright 优先使用你指定的data-testid属性。这个配置在playwright.config.ts里设置import { defineConfig } from playwright/test; export default defineConfig({ use: { testIdAttribute: data-testid, }, });配置之后generateSelector在生成选择器时会优先考虑这个属性生成的 locator 会变成page.getByTestId(submit-btn)这种形式比 CSS 路径稳定得多。5. 验证录制链路从启动浏览器到写入文件理解了原理之后走一遍验证流程确认整条链路是通的。这里用 CLI 的codegen来演示因为它不依赖 VS Code 插件更容易观察。第一步启动录制npx playwright codegen https://example.com --targetjavascript执行后会自动打开一个浏览器窗口同时弹出一个 Playwright Inspector 窗口。Inspector 里显示的就是实时生成的代码。第二步在页面上做一次点击操作。比如点击一个链接Inspector 里应该立刻出现类似page.getByRole(link, { name: More information }).click();的代码。如果没出现说明注入脚本没生效或者事件监听被页面自身的逻辑拦截了。第三步验证 locator 的唯一性。把生成的 locator 复制到 Inspector 的「Explore」输入框里它会实时显示匹配到的元素数量。如果匹配到多个说明这个 locator 不够唯一需要手动调整或者换用nth()。第四步检查写入结果。在 Inspector 里点击「Record」停止录制生成的代码会输出到终端或者你指定的文件。如果你用的是 VS Code 插件代码会直接写入当前打开的测试文件。这里有一个容易忽略的点codegen启动的浏览器是 Playwright 自己管理的它和playwright-core/server/chromium目录下的生命周期管理代码有关。Playwright 没有直接用 Puppeteer而是自己实现了浏览器管理这也是它比简单封装更复杂的原因。如果你在排查启动阶段的报错比如浏览器起不来、版本不匹配问题往往出在这一层而不是注入脚本。验证注入脚本是否生效还有一个更直接的办法在录制过程中打开 DevTools切到 Elements 面板看目标元素上有没有被加上高亮相关的属性或覆盖层。Playwright 的高亮是通过在页面上插入一个覆盖元素实现的如果你能看到这个覆盖层跟着鼠标走说明onMouseMove链路是通的。6. 录制失效的常见排查清单录制失效的表现有很多种但按链路拆开之后排查会快很多。下面是我实际遇到过的几类问题以及对应的定位方法。第一类高亮框不出现或者错位。优先检查页面是否大量使用 Shadow DOM。deepEventTarget负责穿透 shadow root如果目标元素在多层 shadow 里选择器生成可能拿不到正确的宿主。解决办法是在录制时手动确认目标元素或者改用page.locator(host-element).locator(inner)这种链式写法。第二类点击后生成的 locator 指向了错误的元素。这通常是事件冒泡导致的。注入脚本用的是捕获阶段监听addEventListener(..., true)但页面自身的逻辑可能在冒泡阶段改变了 DOM 结构。排查方法是看onClick里拿到的target是不是你真正点击的元素如果不是说明中间有元素拦截了事件。第三类输入框录制成了click而不是fill。这要看onInput的类型判断逻辑。如果输入框是自定义组件比如用div模拟的contenteditablePlaywright 可能识别不出它是输入元素就会退化成点击。这种情况需要手动改成fill()或者type()。第四类录制出来的 locator 带了一长串 CSS 路径。这说明generateSelector没有找到合适的 role 或 testId退化到了cssFallback。解决办法是给关键元素加上data-testid并在配置里指定testIdAttribute让生成器优先使用它。第五类浏览器启动失败或者录制窗口打不开。这类问题基本和注入脚本无关要去看 Playwright 的浏览器管理模块。常见原因是浏览器版本和 Playwright 版本不匹配执行npx playwright install重新安装对应版本即可。第六类录制正常但写入文件失败。这是宿主进程的问题不是浏览器端的问题。VS Code 插件通过textedit对象把生成的内容写入当前测试文件如果文件被占用或者权限不足就会写入失败。检查文件是否只读或者换一个路径重试。排查的时候有一个原则先确认注入脚本是否生效看高亮再确认 locator 生成是否合理看 Inspector最后确认写入是否成功看文件。按这个顺序走基本不会绕弯路。7. 把录制链路接进你的编码工作流录制只是起点真正省时间的是把录制结果接进一个能持续帮你改测试、补断言的流程。我自己的做法是用codegen录出基础操作然后把生成的脚本丢给编码助手让它补上断言和异常处理。这时候一个稳定的模型调用入口就很重要。如果你要长期跑这类编码任务建议用 Coding Plan它的额度模型更适合反复读写文件的场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果只是偶尔让模型解释一段 locator用模型对话页就够了https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各语言 SDK 的配置示例。回到录制本身最后给你一个实用技巧录制之前先想清楚你要的 locator 风格。如果你偏好getByRole就确保页面元素有正确的 ARIA 角色如果你偏好getByTestId就提前把data-testid加上并在配置里声明。录制器会按你给的线索去生成线索越清晰生成的 locator 越稳定。这比录完之后手动改一堆选择器要省事得多。