Payload e2e 测试修复工作流：UI 组件变更后的 Playwright 测试系统性定位与修复方法

Payload 是一个开源的 Next.js 全栈框架，自带 TypeScript 后端与 Admin Panel 后台。它的管理界面（packages/ui）拥有数百个共享组件，任何一次选择器、结构或文案改动都可能连带破坏分散在几十个测试套件中的 Playwright e2e 用例。本文以仓库中的 ui4-convert-tests 技能文档 为主体，完整还原"UI 改完之后如何系统性找到并修好受影响的 e2e 测试"这一工作流：从 diff 影响面分析、受影响测试的定位策略，到七类修复模式、失败日志判读，再到隔离端口/隔离数据库的测试运行方式，并结合 E2E 运行器 与 Playwright 配置 的源码实现讲清每条命令背后的真实行为。读完后你可以直接照此流程处理一次 UI 重构引发的 CI 失败。

一、适用场景：什么时候需要这套流程

该技能文档明确了三个触发时机：

• UI 改动已经定稿（finalized），准备进入修测试阶段；
• CI 因你的 UI 改动而挂在了 e2e 测试上；
• 打开 PR 之前，确保相关测试套件全部通过。

它的核心思想不是"哪个测试挂了改哪个"，而是先分析变更的性质（what kind of change），而不是只看变更了哪些文件——因为变更类型直接决定了测试受影响的模式（选择器失效、需要新增弹窗打开步骤、断言文本不匹配等）。

适用前提：Payload 4（当前仓库根 package.json 中版本为 4.0.0-canary.14），pnpm + turbo 的 monorepo 环境，Playwright 1.59.1（见 package.json 的 @playwright/test 依赖）。

二、Step 1：分析变更性质，预测测试影响面

2.1 圈定变更文件

第一步只关心 packages/ui 里的界面代码：

# 列出相对 main 分支变更的 UI 文件
git diff main --name-only -- 'packages/ui/src/**/*.tsx' 'packages/ui/src/**/*.css'

2.2 把每个文件的改动归入三类

技能文档要求对每个变更文件做"性质归类"，因为不同类别对应完全不同的测试修复策略：

A 类：选择器变更（ID、className）

git diff main -- <file> | grep -E '^\-.*className|^\-.*id=|^\+.*className|^\+.*id='

B 类：结构变更（元素被移动/包裹/条件化）

重点观察组件是否被：移入 Popup、PopupList、Drawer 或 Dropdown；被新的父元素包裹；被改成条件渲染。检测命令：

git diff main -- <file> | grep -E 'Popup|PopupList|Drawer|Dropdown'

C 类：文本/标签变更

# 翻译 key 变更
git diff main -- <file> | grep -E "t\('|i18n\.t\("

# 硬编码文本（placeholder、aria-label）变更
git diff main -- <file> | grep -E 'placeholder=|aria-label='

2.3 产出"变更摘要表"

归类完成后应形成一张可指导后续步骤的摘要表（以下为原文档给出的示例）：

变更类型	具体变化	对测试的影响
Selector	.btn:has-text("Create") → #create-new-doc	更新 locator
Structure	按钮移入 popup	增加"打开 popup"步骤
Text	"Search by ID" → "Search"	更新断言

这张表就是后面"找测试"与"定修复策略"两个环节的输入。

三、Step 2：定位受影响的测试——先撒大网，再收窄

3.1 搜索策略：组件名 + 选择器 + 文本，三路并进

文档强调不要只搜精确选择器，还应搜组件名（如 QueryPreset、ListHeader）和功能名（如 preset、filter、search）：

# 搜索组件名引用（而非仅选择器）
grep -rn "QueryPreset\|query-preset\|preset" test/**/*.ts --include="*.spec.ts" --include="*.ts"

# 搜索 Step 1 中得到的具体选择器
grep -rn "\.list-header\|Create New\|#create-new" test/**/*.ts

3.2 测试代码的位置分布

Payload 的 e2e 测试按套件（suite）组织在 test/<feature>/ 下，关键位置速查：

模式	去哪里找
组件专属测试	test/<feature>/e2e.spec.ts
套件内共享 helper	test/<feature>/helpers/*.ts
跨套件共享 helper	test/__helpers/e2e/*.ts
多个特性使用同一组件	搜索全部 test 目录

这一布局在仓库中可以直接验证：如 test/query-presets/e2e.spec.ts 与套件内 test/query-presets/helpers 目录并存；跨套件共享的交互工具（toggleListMenu.ts、toggleListDrawer.ts、navigateToListView.ts、playwright.ts 等）集中在 test/__helpers/e2e 目录。

四、Step 3：修之前先读懂测试的依赖关系

技能文档要求在动手前先做三件事：

1. 通读完整测试——弄清它实际在测什么；
2. 检查 helper——这个选择器是否由某个共享 helper 封装；
3. 找模式——是否多个测试在做同一件事。

如果多个测试使用同一选择器，正确做法是新建/更新 helper 来集中修复。文档给出的示例：

// test/<feature>/helpers/togglePreset.ts
export async function openCreatePreset(page: Page) {
  await page.click('#select-preset') // 先打开 popup
  await page.click('#create-new-preset')
}

这一做法的好处是"修复集中在一处，并防止未来重复"。从源码结构看，仓库本身也遵循同一约定：跨套件复用逻辑放在 test/__helpers/e2e 下按交互命名（如 openDocControls.ts、toggleCollapsible.ts），套件级复用逻辑放在各自的 helpers/ 目录。

五、Step 4：把待修复项按类型分类

变更类型	修复策略
选择器重命名	直接字符串替换
元素移入 popup	点击元素前先点击打开 popup
元素移入 drawer	增加 drawer 打开/关闭处理
文本简化	更新断言以匹配新文本
元素被移除	重构测试逻辑或删除测试
Props 变更	更新属性断言
条件渲染	可能需要在元素出现前先构造状态

六、Step 5：先跑测试确认失败，再记录失败模式

文档特别强调在修复之前先运行测试，确认它真的会失败（"If a test passes, don't change it"）：

# 使用隔离端口避免冲突
PORT=3150 pnpm test:e2e <suite> --max-failures=1

# 按名字运行单个测试
PORT=3150 pnpm test:e2e <suite> -g "test name" --max-failures=1

并记录失败日志与变更类型的对应关系：

• Timeout waiting for locator('.old-selector') → 选择器变了；
• locator resolved to 0 elements → 元素被移动或移除；
• expected "New Text" received "Old Text" → 文本内容变了。

源码佐证：pnpm test:e2e 实际指向根 package.json 中的 "test:e2e": "pnpm runts ./test/runE2E.ts"，test/runE2E.ts 会解析第一个位置参数作为套件名，然后用 createServer().listen(PORT) 探测端口占用状态——端口空闲则 spawn('pnpm dev <suite> --no-seed') 启动 dev server，端口被占用则打印 "reusing existing dev server" 直接复用。这印证了文档"自动启动或复用 dev server"的说法，也解释了为什么 PORT 必须设为独立值：同一端口上如果还挂着别的套件的 dev server，运行器会直接复用它，导致测试打在错误的 Payload 配置上（这正是后文"常见错误"中的一条）。

七、Step 6：按四种典型模式实施修复

修复优先级：先修 helper，再修各个独立测试。

模式 1：选择器重命名——优先使用 ID

// Before
await page.click('.list-header .btn:has-text("Create")')

// After - prefer IDs when available
await page.click('#create-new-doc')

模式 2：元素移入 Popup——先打开再点

// Before - 直接点击
await page.click('#edit-preset')

// After - 先打开 popup
await page.click('#select-preset') // 打开 popup
await page.click('#edit-preset')   // 此时在 popup 内可见

模式 3：文本简化——更新断言

// Before - 精确的旧 placeholder
await expect(input).toHaveAttribute('placeholder', /(Search by ID)/)

// After - 简化后的文本
await expect(input).toHaveAttribute('placeholder', 'Search')

模式 4：抽取出可复用 helper

同一交互被多个测试需要时：

// test/<feature>/helpers/interactions.ts
export async function openEditPreset(page: Page) {
  await page.click('#select-preset')
  await page.click('#edit-preset')
}

// 测试中导入使用
import { openEditPreset } from './helpers/interactions.js'
await openEditPreset(page)

八、Step 7：验证修复

# 重跑之前失败的测试
PORT=3150 pnpm test:e2e <suite> --max-failures=1

只有测试通过后才能提交。

九、五个"真实案例"级常见模式

这部分是技能文档最有实战价值的沉淀——每个模式都给出"症状 → 检测方法 → 修复方式"三段式。

模式 A：按钮被移入 Popup 菜单

症状：测试超时等待原本直接可见的按钮。检测：git diff main -- <file> | grep -E 'PopupList|Popup'，确认按钮是否被 <Popup>/<PopupList> 包裹。修复：在点击目标按钮前增加 popup 触发器点击：

// Before: 按钮直接在工具栏上
await page.click('#edit-preset')

// After: 按钮位于 popup 内
await page.click('#select-preset') // 打开 popup
await page.click('#edit-preset')   // 此时可见

若多个测试需要该操作，进一步抽 helper。

模式 B：Class 选择器 → ID 选择器

症状：.some-class 或 :has-text("Button Text") 找不到元素。检测：git diff main -- <file> | grep -E '^\+.*id='，确认组件新增了 id= 属性。修复：换用更稳定的 ID：

// Before: 脆弱的 class + 文本选择器
await page.click('.list-header .btn:has-text("Create New")')

// After: 稳定的 ID 选择器
await page.click('#create-new-doc')

模式 C：Placeholder / Label 文本简化

症状：断言报 expected "New Text" received "Old Text"。检测：git diff main -- <file> | grep -E 'placeholder=|t\('。修复：把断言改为新文本：

// Before: 冗长的旧 placeholder
await expect(input).toHaveAttribute('placeholder', /(Search by ID, Title)/)

// After: 简化后
await expect(input).toHaveAttribute('placeholder', 'Search')

模式 D：同一修复横跨多个测试

症状：不同套件中多个测试因相似选择器问题失败。检测：

# 找出所有使用旧选择的测试
grep -rn "old-selector\|.old-class" test/**/*.ts

修复顺序：先查 test/<feature>/helpers/ 是否已有 helper；有则修 helper（一次修复全部测试）；没有则新建一个并重构测试使用它。

模式 E：不同套件的测试共享同一组件

当你修改的是 ListControls、QueryPresetBar 这类共享组件，多个测试套件都会受影响。检测方式：

# 跨全部测试搜索组件名引用，去重得到受影响的测试文件
grep -rn "QueryPreset\|ListControl" test/**/*.ts | cut -d: -f1 | sort -u

文档列出的典型跨套件组件：ListControls（影响所有列表视图测试）、QueryPresetBar（影响 query-presets、group-by、admin 套件）、Search（影响 i18n、admin 及大多数 collection 测试）、Button（几乎是所有测试）。

源码佐证：#select-preset、.popup-button-list__button 这类选择器并非虚构，它们在 packages/ui 中有对应的 CSS 定义，例如 QueryPresetBar 样式 与 PopupButtonList 样式（.popup-button-list__button 类名即定义于此）。修测试时可以直接回到这些源文件核对当前真实的 id 与 class 名。

十、速查表：Payload 常用 e2e 选择器

原文档附带的快速参考表（可作为断言与定位的起点）：

组件	常用选择器
Search	.search-filter__input、#search-filter-input
List View	.collection-list、tbody tr、.table-row
Popup	.popup__content、.popup-button-list__button
Modal	dialog、[id^=doc-drawer_]、[id^=list-drawer_]
Buttons	.btn、button[type="button"]
Query Presets	#select-preset、.query-preset-bar__*

注意：这类选择器会随 UI 迭代变化，使用前应先到 packages/ui/src 对应组件的 tsx/css 中确认当前值（见上文模式 B 的检测命令）。

十一、测试命令全参考与底层实现

11.1 常用命令

# 运行某套件的全部 e2e 测试（自动启动 dev server）
PORT=3150 pnpm test:e2e <suite-name>

# 运行指定测试文件
PORT=3150 pnpm test:e2e test/<suite>/e2e.spec.ts

# 有头浏览器运行（直观看到执行过程）
PORT=3150 pnpm test:e2e:headed test/<suite>/e2e.spec.ts

# 调试模式（单步）
PORT=3150 pnpm test:e2e:debug test/<suite>/e2e.spec.ts

# 按名字模式运行指定测试
PORT=3150 pnpm test:e2e test/<suite>/e2e.spec.ts -g "test name pattern"

# 首个失败即停（调试时常用）
PORT=3150 pnpm test:e2e test/<suite>/e2e.spec.ts --max-failures=1

这些脚本定义在根 package.json：test:e2e 走 runE2E.ts（dev 模式、自动管理 dev server）；test:e2e:headed 与 test:e2e:debug 则直接调用 playwright test --headed / PWDEBUG=1 playwright test（不经过运行器，需自行保证 dev server 已启动）。

运行器的三点自动行为（由 runE2E.ts 源码确认）：

1. 端口空闲时，spawn('pnpm dev <suite> --no-seed') 自动启动该套件的 dev server；
2. 端口被占用时，打印 "Port is already in use — reusing existing dev server" 并直接复用；
3. 测试开始前会调用 POST /api/re-initialize（见 runE2E.ts 中的 resetServer）重置测试数据，然后执行 node_modules/.bin/playwright test <files> -c playwright.config.ts。

11.2 运行器如何透传参数

阅读 runE2E.ts 可以看到，运行器用 minimist 解析参数后，把 --grep/-g、--shard、--workers、--headed、--update-snapshots、--fully-parallel 等逐个拼装进最终的 playwright test 命令行；不带套件名运行时，会用 globby 收集所有 **/*e2e.spec.ts 并逐套件执行（每个套件一个 dev server 实例，跑完即 stopServer 杀掉整个进程组）。从源码结构看，--max-failures 并不在运行器显式解析的参数列表中，因此该标志是否生效取决于具体路径，最稳妥的"快速失败"方式是用 -g "test name" 直接只跑目标测试。

11.3 Playwright 侧的超时与重试设定

test/playwright.config.ts 的关键设定：

• 本地：timeout = 20s、expect.timeout = 6s；CI 环境：测试超时放大 4 倍（beforeAll 用 60s×4），且本地失败保留 trace（trace: 'retain-on-failure'）、CI 首次 retry 才收集 trace；
• 仅使用 Chromium（Desktop Chrome + channel: 'chromium'）；
• 配置文件加载时会读取 test/test.env 与仓库根 .env（dotenv），环境相关的数据库连接串从这里注入。

十二、隔离运行：端口隔离与数据库隔离

12.1 快速上手：MongoDB（默认）只需端口隔离

在 3100–3199 区间选一个端口即可：

# 在隔离端口运行测试（MongoDB 自动启动自己的内存服务器）
PORT=3150 pnpm test:e2e query-presets --max-failures=1

对默认的 MongoDB 适配器，这就够了：从源码结构看，runE2E.ts 在 spawn dev server 前会设置 START_MEMORY_DB=true，每次运行各自启动一个 in-memory MongoDB，天然不存在数据库冲突——冲突只可能发生在端口上。

12.2 Postgres 隔离：每个 worktree/仓库用独立数据库

# 为本 worktree 创建独立数据库
PGPASSWORD=payload psql -h localhost -p 5433 -U payload -c "CREATE DATABASE payload_worktree1;"

# 针对该数据库运行测试
POSTGRES_URL="postgres://payload:payload@localhost:5433/payload_worktree1" \
  PORT=3150 pnpm test:e2e query-presets --max-failures=1

或者用自定义 schema 方式（无需独立数据库）：

# 测试将使用同一数据库内的独立 schema
PAYLOAD_DATABASE=postgres-custom-schema PORT=3150 pnpm test:e2e query-presets

12.3 为什么必须隔离

场景	端口冲突？	数据库冲突？
MongoDB in-memory	是（同端口）	否（每次运行独立服务器）
Postgres	是（同端口）	是（同一批表）
多个 worktree 并行	是	是（仅 Postgres）

结论：始终显式设置 PORT 以避免端口冲突；Postgres 场景还要额外隔离数据库/schema。

十三、常见错误清单

技能文档最后列出的七类高频错误，几乎每一条都能对应到前文的某个机制：

1. Dev server 未启动或端口不对：测试读取 PORT 环境变量（默认 3000）。方案 A（推荐，尤其并行多套件）：PORT=3105 pnpm test:e2e test/query-presets/e2e.spec.ts，由运行器接管一切；方案 B：杀掉占用端口的旧进程后用默认端口：

   lsof -ti:3000,3001,3002,3003,3004,3005,3006,3007,3008,3009 | xargs kill -9 2>/dev/null
   pnpm test:e2e test/query-presets/e2e.spec.ts
   

2. 跑错了测试套件：每个套件（fields、query-presets、localization 等）有自己独立的 Payload 配置（如 test/query-presets/config.ts）；若目标端口上跑的是别的套件的 dev server，运行器会静默复用它，测试将失败或行为异常。

3. 修复前没先运行测试：必须先确认测试确实失败；测试能通过就不要改它。

4. 没检查 helper 文件：test/*/helpers/ 中的共享 helper 往往持有影响多个测试的公共选择器——修 helper 优先于修用例。

5. 漏掉 popup 交互：元素移入 popup 后，测试必须先打开 popup。

6. 忘记确认对话框：删除类操作常伴随确认 modal，测试需要处理 confirm 步骤。

7. 占位符/文案变更与 Modal slug 不匹配：搜索 placeholder、按钮标签等文本可能变化；删除/确认类操作的 modal slug 可能改动——应回到组件代码核对传给 <Modal>/drawer 组件的实际 slug 属性。

十四、贯穿示例：QueryPresetBar 从 Chips 重构为 Popup 下拉

技能文档用一个真实重构把前面所有步骤串起来。旧结构（chips 直接可见按钮）对应的测试代码：

// 按钮直接可见
await page.click('#create-new-preset')
await page.click('#edit-preset')
await page.click('#delete-preset')
await page.click('.chip__remove') // 清除

重构后（popup 下拉结构）的对应测试：

// 先打开 popup
await page.click('#select-preset')
// 再点击菜单项
await page.click('.popup-button-list__button:has-text("Create New")')
await page.click('.popup-button-list__button:has-text("Edit")')
await page.click('.popup-button-list__button:has-text("Delete")')
// 清专用按钮
await page.click('.query-preset-bar__clear')

对照本文流程可以完整复盘：Step 1 的 B 类检测（grep Popup）识别出这是"结构变更"；Step 2 用 grep -rn "QueryPreset\|preset" 撒网找到所有受影响套件；Step 4 归类为"元素移入 popup → 增加打开步骤"；Step 5 先跑 PORT=3150 pnpm test:e2e query-presets 确认 Timeout waiting for locator('#create-new-preset') 这类失败；Step 6 按模式 2 + 模式 4 修复并抽 helper；Step 7 回归验证。

十五、小结：把"修测试"变成可重复的工程流程

这套技能文档的价值在于把一次性的"测试挂了怎么改"经验固化为可执行清单：

1. 先归类，后动手：选择器 / 结构 / 文本三类变更，修复策略互不相同；
2. 搜索要撒大网：组件名、功能名、变更文本三路并进，并区分套件内 helper 与跨套件 helper 两个层级；
3. 失败日志即诊断依据：三种典型失败信息分别对应选择器、结构、文本变更；
4. 修复集中在 helper：一次修改覆盖多个测试，防止选择器再次散落；
5. 隔离是并行开发的前提：MongoDB 靠 in-memory 实例天然隔离数据，只要隔离 PORT；Postgres 还需隔离数据库或 schema；
6. 仓库内有据可查：运行器行为见 test/runE2E.ts，超时与重试见 test/playwright.config.ts，选择器真值在 packages/ui/src 各组件源码中。

掌握这条链路后，无论是本地多 worktree 并行开发，还是处理 UI 组件重构引发的 CI 批量失败，都能在"分析 → 定位 → 确认失败 → 修复 → 验证"的闭环内可控地推进，而不再依赖对某个测试用例的临场猜测。