Playwright 跨已发布版本回归排查:双版本并排复现与 node_modules 编译产物级定位

当用户报告"某个 Playwright 版本正常、下个版本坏了"这类跨版本回归时,排查的正确姿势不是去 monorepo 源码里翻 git log,而是从 npm 把两个版本并排装出来、直接对比 node_modules 里已发布的编译产物。本文基于 Playwright 仓库内部开发者技能文档 bisect-published-versions.md(收录于 .claude/skills/playwright-dev/SKILL.md 开发指南体系)展开,完整继承其操作流程,并结合仓库源码补充原理依据:读完你能掌握一套"复现 → 对比 → 假设验证 → 上报"的可复制回归定位方法,知道为什么应该以编译产物为准、以及如何用最小补丁在坏版本安装目录里现场验证修复。

何时用这套方法,以及它的适用边界

该文档的核心主张是:用户报告的"1.58 正常、1.59.1 坏了"这类已发布版本之间的回归,应从 npm 两侧复现,而不是对着 monorepo 源码做 bisect。理由有二:

1. 阅读 node_modules/playwright/lib/** 里的编译 JS 比构建/切分支快得多,且不会陷入构建与分支混乱;
2. 用户实际运行的是已发布产物。源码里对应的文件可能已经在 main 分支上被重构或修复,直接映射源码容易得到"看起来没问题"的假象。

需要注意这条方法线在仓库中的定位:它是 .claude/skills/playwright-dev/ 下 Playwright 开发指南集的一篇,与 library.md(库架构)、api.md(API 增改)等并列,服务于 Playwright 自身的维护与回归调查。仓库里还有一个"兄弟工具" utils/bisect-chromium.mjs——但它二分的是 Chrome for Testing 的 per-commit 浏览器构建(通过 --good <rev> --bad <rev> 在 Chromium 各提交构建间做二分查找),用于定位浏览器引擎侧的回归。本文方法针对的是 Playwright 库自身版本之间的回归,两者对象不同,不要混淆。

一个关键实现事实支撑了"对比编译产物"的可行性:从 packages/playwright-core/package.json 的 exports 字段可以看到,发布的 playwright-core 包对外暴露了 ./lib/bootstrap、./lib/coreBundle、./lib/utilsBundle 等 lib/ 下的入口——即 npm 包本身就是以编译后的 lib/ 目录为运行载体的,用户环境中 node_modules/playwright/lib/... 里的 JS 就是真实执行路径。

搭建双版本并排安装环境

目录约定与安装命令

原文档规定使用 ~/tmp/<version-tag>/ 而不是 /tmp/——因为用户的交互式 shell 会话默认工作目录是 ~/tmp,保持一致可以避免工具调用之间 cwd 漂移带来的混乱。完整命令如下:

mkdir -p ~/tmp/<good>/tests ~/tmp/<bad>/tests

# 跳过 `npm init playwright@latest` —— 它是交互式脚手架,
# 且默认模板会拉入 3 个浏览器项目(chromium/firefox/webkit),
# 一个 spec 会产生 6 次测试运行,输出极其混乱。改用:
( cd ~/tmp/<good> && npm init -y && npm install @playwright/test@<good-ver> && npx playwright install chromium)
( cd ~/tmp/<bad>  && npm install @playwright/test@<bad-ver> && npx playwright install chromium )

几点实操要点(均出自原文档,并可在仓库中印证):

• 不要用 npm init playwright@latest:它是交互式的,--quiet 也不能跳过提示;npm init -y + npm install @playwright/test@<具体版本> 更快且确定性强。
• 括号子 shell ( cd ... && ... ) 的写法很重要——不要在单次 shell 调用里跨命令 cd 而不用 && 串联,否则工作目录会在命令之间被重置。
• 只安装 chromium 浏览器即可,绝大多数复现场景单浏览器足够(见下文"坑位"一节的解释)。

最小化 Playwright 配置

脚手架默认生成的配置包含 3 个浏览器项目,会把同一份 spec 跑 6 次(chromium 项目 + 报告/分片机制),严重干扰对"差异是否真实"的判断。文档要求写一个仅含单个 chromium 项目的最小 playwright.config.ts:

import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
  testDir: './tests',
  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
});

然后把复现 spec(及所需辅助文件)原封不动地放进两个目录,分别运行:

( cd ~/tmp/<good> && npx playwright test )
( cd ~/tmp/<bad>  && npx playwright test )

在开始任何调查之前,先确认差异真实存在:good 版本必须稳定通过,bad 版本必须稳定失败。这一步是整个方法的"端点校验",与仓库内 utils/bisect-chromium.mjs 在二分开始前先"Verifying endpoints"、若端点状态与预期不符立即中止的做法是同一思想——端点不可信,后面的一切对比都没有意义。

在 node_modules 中对比两个版本的差异

为什么按文件 diff 行不通

node_modules/playwright-core/lib/ 与 node_modules/playwright/lib/ 里的编译 JS 是"实际发布内容"的权威来源。但原文档指出一个关键限制:

在较新的 Playwright 版本中,这些文件是打包(bundled)在一起的,因此无法逐文件对比。不过可以用 grep 从 bundle 中提取特定文件的内容再做对比。

这一说法与仓库构建体系一致:仓库根 package.json 的依赖中包含 esbuild,构建链通过 esbuild 将各模块打入 bundle;CLAUDE.md 的包结构表也说明 playwright-core 是"浏览器自动化引擎:client、server、dispatchers、protocol",这些模块在发布产物中会被合并进少数几个 bundle 文件(如 coreBundle.js、utilsBundle.js,可从 packages/playwright-core/package.json 的 exports 看到对应入口)。

定位候选函数并做最小 diff

对比的具体做法:

1. 从失败栈跟踪/报错信息中提取函数名或特征字符串;
2. 在两个版本的 node_modules/playwright/lib/ 下分别 grep 该函数,提取其实现;
3. 对候选函数做并排 diff——这类回归的补丁通常只有 1–3 行,定位后差异往往一目了然。

原文档对这条路径的取舍是明确的:先查 node_modules/,只有在需要向上游提交补丁时,才把修复映射回 monorepo 源码。此时仓库结构知识就有用武之地——CLAUDE.md 给出了各包职责表(playwright-core 为引擎、@playwright/test 为测试运行器入口等)以及 docs/src/api/ 是公开 TypeScript 类型的事实来源,帮助你把 bundle 中的某段行为对应到 packages/playwright/src/ 或 packages/playwright-core/src/ 下的源码文件。

验证假设:直接改编译 JS,无需构建

这是该方法最精巧的一步:直接编辑 ~/tmp/<bad>/node_modules/playwright/lib/... 中的编译 JS 并重跑测试。Node 按原样加载这些 JS,没有构建步骤;验证完恢复原样(或直接删掉整个目录)即可。等于在用户环境里做了一次"热修复实验"——若改动后坏版本通过,根因假设即被证实。

原文档特别提到栈跟踪类(stack-trace bugs)的技巧:在捕获点插入 console.log(new Error().stack),可以立刻分辨问题究竟属于"微任务边界(microtask boundary)相关"、"栈过滤(stack-filter)回归"还是其他原因。这一建议直接对应仓库源码中的真实实现:

• captureRawStack() 定义在 packages/utils/stackTrace.ts;
• 断言路径在 packages/playwright/src/matchers/expect.ts 中调用 expectConfig().filteredStackTrace(captureRawStack()) 完成原始栈捕获与过滤;
• 另外 packages/playwright/src/worker/testInfo.ts 也引用了 captureRawStack,说明栈捕获在 worker 侧同样存在捕获点。

也就是说,在坏版本的 expect.js 对应位置插入一行 console.log(new Error().stack),打印出的原始栈与过滤后栈的对比,能直接回答"过滤逻辑是否误删了用户代码帧"这一类问题。

上报:四要素 + gh issue comment

根因确认后,原文档规定上报必须包含四要素,缺一不可:

1. 引用坏版本 node_modules/.../lib/... 中有问题的行,并给出文件路径;
2. 给出好版本的对应代码,形成对照;
3. 解释该改动为什么会破坏用户场景——不能只丢一个 diff;
4. 提出并通过最小补丁(就地修改坏版本安装目录)验证过的修复方案。

最后将完整 writeup 作为评论发到原始 issue 上,原文给出的命令模板为:

gh issue comment <number> --repo microsoft/playwright --body "$(cat <<'EOF'
...
EOF
)"

这一上报结构与仓库 CLAUDE.md 中"提交约定"一脉相承:语义化、短小、可验证(修复建议必须已经过就地补丁验证),并且该仓库明确要求 PR/issue 评论中不得附带任何 AI 工具署名——若由 Agent 代为撰写,需遵守这条约定。

坑位清单(全部继承自原文档)

以下 6 条 Pitfalls 是该流程的血泪总结,原文逐条列出,此处完整保留:

• 不要运行 npm init playwright@latest——它是交互式的,且 --quiet 不会跳过提示;npm init -y + npm install @playwright/test@<ver> 更快且可确定复现。
• 不要用脚手架默认配置——3 个浏览器项目会把测试运行次数乘以 3,混淆输出;99% 的复现场景一个 chromium 项目足够。
• 单次 shell 调用中跨命令 cd 必须用 && 串联——否则工具调用之间 shell 工作目录会重置。
• /tmp/ 不等于 ~/tmp/——选一个并保持一致;用户的交互式 shell 默认在 ~/tmp/,所以优先用它。
• 未经确认不要 rm -rf 已存在的 ~/tmp/<ver>/——那可能是用户此前的工作产物;应就地编辑。
• 不要试图先把 bug 映射到 monorepo 源码——用户运行的是已发布 JS,源码可能已在 main 上被重构或修复;先查 node_modules/,只在提议上游补丁时才映射回源码。

小结:方法论要点回顾

阶段	关键动作	依据
复现	双目录 npm 并排安装指定版本,最小 chromium-only 配置	bisect-published-versions.md Setup 一节
对比	以 node_modules/playwright{,-core}/lib/ 编译产物为准,grep 提取函数后做 1–3 行级 diff	发布包 exports 暴露 ./lib/* 入口,见 packages/playwright-core/package.json
验证	就地编辑坏版本编译 JS 重跑,无需构建;栈类问题在 captureRawStack 捕获点打印 new Error().stack	captureRawStack 定义于 packages/utils/stackTrace.ts,被 expect.ts 调用
上报	坏版本代码引用 + 好版本对照 + 破坏原因解释 + 已验证的最小补丁	Reporting 一节四要素

这套流程的本质是把"版本回归排查"从源码考古降维成产物级二进制 diff:先确认端点、再在最小单元(1–3 行)上收敛假设、用零构建成本的热补丁完成闭环验证,最后以可复现的证据链上报。它同样适用于任何"多版本发布物之间定位回归"的场景,而 Playwright 的 bundle 化发布结构则要求你放弃逐文件对比、改用 grep 提取后并排比较——这正是该文档与通用 git-bisect 教程最大的差异点。