测试框架迁移时如何增量迁移并保持覆盖率不丢失

当需要把测试套件从一个框架迁移到另一个框架（如 Selenium/Cypress/Protractor→Playwright、Jest/Mocha→Vitest）时，用增量迁移 + 双套件并行 CI 的方式保证覆盖率不泄漏。

适用场景

解决思路

1. 先检查 `.agents/qa-project-context.md`，若存在则作为上下文并跳过已回答的问题；否则先澄清：从哪个框架迁到哪个、测试数量与 flaky/skip 率、当前覆盖率基线、现有基础设施（page object、自定义命令、fixture、数据工厂）、认证/会话处理方式、CI 能否同时跑两个框架、时间压力、双套件预算、团队对目标框架的熟悉度。
2. 按六阶段推进：Phase 1 审计现有套件（按类别统计测试数、skip/flaky 比例、覆盖率、运行时长、page object/工具文件、自定义插件、CI 阶段），并把每个测试分为 Critical（营收流程）→ High（核心旅程）→ Medium（次要）→ Low（管理/边缘）→ Skip（禁用、重复、过时）。
3. Phase 2 并行安装目标框架：创建配置（`playwright.config.ts` / `vitest.config.ts`）、独立测试目录、非阻塞 CI 阶段、一个冒烟测试验证搭建、与现有格式一致的 reporter、共享环境变量与密钥。
4. Phase 3 先迁移共享基础设施，顺序为：base page object/test base → auth helpers → API client helpers → 通用 page object（nav/header/footer）→ 数据工厂 → 自定义断言 → 各功能 page object（连同其测试）；在此阶段捕获 `storageState`，让迁移后的测试跳过登录流程。
5. Phase 4 按优先级迁移测试：读旧测试并理解它实际验证什么 → 用现代模式从零重写（不要逐行翻译）→ 本地跑绿 → CI 跑绿 → 给旧测试打上 “migrated” 标签（不要删除）→ 并行通过一个 sprint 后再删除旧测试。
6. Phase 5 全程在 CI 中并行运行两套件：旧套件保持非阻塞（`continue-on-error: true`），直到新套件达到覆盖率对等，然后把阻塞切到新套件并移除旧 job。
7. Phase 6 仅在满足以下条件后下线旧框架：所有 critical/high 测试已迁移、新套件在 CI 连续 2+ 个 sprint 全绿、新套件 flaky 率 ≤ 旧套件、覆盖率对比无回退、团队已连续 2+ 个 sprint 用新框架写测试；然后从 `package.json` 删除旧依赖、删除（而非禁用）旧测试文件、更新 CI 只跑新套件、更新文档。
8. 选择合适的一次性转换工具：Cypress→Playwright 用官方 cy2pw web 转换器（[demo.playwright.dev/cy2pw](https://demo.playwright.dev/cy2pw/)）处理简单 spec，或用社区 CLI `npx @11joselu/cypress-to-playwright <dir>` 做目录级首轮转换；自定义命令与 fixture 翻译用 AI agent（Claude Code、Cursor）；Playwright 1.59+ 的 agentic CLI（`npx playwright trace`、`--debug=cli`）只用于迁移后失败测试的排查，不用于迁移本身。
9. 不要使用 `npx playwright migrate`——该内置命令不存在，会在终端报错；改用 cy2pw 或上述社区 CLI。
10. 在让 AI 或 codemod 批量处理前，先手工迁移一个代表性测试并提交为团队规范模式（如 `e2e/_golden/login.spec.ts`），把它作为 few-shot 参考喂给 AI 并指引人工 reviewer，后续所有迁移都锚定这个文件。
11. 按映射表翻译定位器：`By.id('submit-btn')`→`page.getByRole('button', { name: 'Submit' })`；`By.css('.nav-item.active')`→`page.getByRole('link', { name: 'Dashboard' })`；`By.xpath('//div[@class="modal"]')`→`page.getByRole('dialog')`；`By.css('[data-testid="user-menu"]')`→`page.getByTestId('user-menu')`；`cy.get('.product-card').first()`→`page.getByRole('article').first()`；`cy.contains('Add to cart')`→`page.getByRole('button', { name: 'Add to cart' })`；`element(by.model('username'))`→`page.getByLabel('Username')`；role/label 名称需替换为应用实际渲染的可访问名称。
12. 按映射表翻译等待策略：`Thread.sleep(3000)`、`WebDriverWait(...).until(visible)`、`cy.wait(2000)`、`implicitlyWait(10, SECONDS)` 全部删除（Playwright 自动等待，超时在 config 的 `actionTimeout` 配置）；`cy.wait('@apiCall')`→`page.waitForResponse(/\/api\/data/)`（在动作前启动 promise）；`browser.wait(EC.presenceOf(...))`→`await expect(locator).toBeVisible()`；`FluentWait` 轮询→`await expect(locator).toHaveText('Done')`。
13. 按映射表翻译断言：`assert element.is_displayed()`→`await expect(locator).toBeVisible()`；`cy.get('.msg').should('have.text', 'Done')`→`await expect(locator).toHaveText('Done')`；`expect(element.getText()).toBe('Done')`→`await expect(locator).toHaveText('Done')`；`cy.url().should('include', '/dashboard')`→`await expect(page).toHaveURL(/dashboard/)`；`assert len(elements) == 5`→`await expect(locator).toHaveCount(5)`。
14. 按映射表翻译 Cypress→Playwright 配置：`baseUrl`→`use.baseURL`；`defaultCommandTimeout: 10000`→`use.actionTimeout: 10000`；`pageLoadTimeout: 30000`→`use.navigationTimeout: 30000`；`retries: { runMode: 2 }`→`retries: 2`；`video: true`→`use.video: 'on'`；`screenshotOnRunFailure: true`→`use.screenshot: 'only-on-failure'`。
15. 各路径要点：Selenium→Playwright 删除所有显式等待、字符串定位器换成 `getByRole`/`getByLabel`/`getByTestId`、WebDriver session 换成 `BrowserContext`、用 `storageState` 代替重复登录；Jest→Vitest（目标 Vitest 4.x）把 `jest.` 换成 `vi.`、`jest.config.js` 转 `vitest.config.ts`、去掉 Babel/ts-jest transform（若用 emotion/styled-components 等自定义 Babel 插件则保留 esbuild/SWC 等价物）、用 Vitest 4.1 的 test `tags` 做增量切换；Cypress→Playwright（目标 PW ≥ 1.50）核心是命令队列→async/await、`cy.intercept()`+`cy.wait()`→`page.route()`+`page.waitForResponse()`、自定义命令→fixture，注意 1.52 的 `page.route()` glob 与 Cookie header 破坏性变更（用 `browserContext.addCookies()` 而非 header override）；Mocha→Vitest 近乎 1:1，`describe`/`it`/hooks 不变，chai matcher 转换（`to.equal`→`toBe`、`to.deep.equal`→`toEqual`、`to.contain`→`toContain`），`sinon`→`vi.fn()`/`vi.spyOn()`；Protractor→Playwright 因 2023 EOL 属紧急，移除 `waitForAngular`、`by.model`/`by.binding` 映射为 `getByLabel`/`getByText`/`getByTestId`、`onPrepare` 变 `globalSetup`。
16. 用覆盖率对比表跟踪对等性，按功能区域记录 Old Suite Tests / New Suite Tests / Parity / Notes，作为下线时的客观依据。
17. 按渐进切换时间线规划：200 个测试约 10 个 sprint——搭建+基础设施（Sprint 1-2）、关键路径迁移（Sprint 3-5，约 50 个测试）、批量迁移（Sprint 6-8）、清理+下线（Sprint 9-10）；旧套件从阻塞逐步变为非阻塞，从 Sprint 3 起新测试只用新框架写。
18. 旧测试先打 “migrated” 标签而非立即删除；仅当新等价测试在 CI 通过 2+ 周且人工复核确认没有丢失独有断言后才删除；若旧测试捕获到新测试漏掉的回归，先增强新测试。
19. 避免大爆炸迁移：不要停掉所有开发 3 个月一次性重写全部测试；改为每 sprint 迁移一个模块、双套件并行、新测试从第一天就用新框架写。
20. 避免只翻译不现代化：不要逐行把 Selenium 测试翻成 Playwright 并保留显式等待、CSS 选择器和脆弱模式；每个测试都用目标框架最佳实践重写（`getByRole` 代替 CSS、无显式等待、fixture 代替 `beforeEach`）。
21. 避免把 AI codemod 当最终答案：先在单个文件上跑工具并与源文件 diff，若正确现代化再批量；若只是翻译，则写自己的 golden-reference 文件作为 few-shot；每次转换后与原始套件并行运行，结果不一致说明工具出错，先排查再推广。
22. 避免不并行运行就下线旧套件：达到对等后至少并行跑 2 个 sprint，旧套件是廉价保险，只有新套件能独立捕获回归后才下线。
23. 避免迁移中丢失覆盖率：在覆盖率表中显式映射每个旧测试到新等价测试；若有意不迁移，记录原因并验证其覆盖由别处提供。
24. 避免原样迁移 flaky 测试：先诊断 flaky 根因（共享状态、时序假设、非确定性数据）并修复，再把修复写进新测试；迁移是修 flaky 的最佳时机。
25. 避免团队无培训：迁移前做 2 小时 workshop，前 10 个迁移测试由 champion 与团队成员结对完成，编写新框架团队风格指南，每个迁移测试要求 2+ reviewer。
26. 排查失败模式：迁移后每次全新登录/会话丢失→未用 `storageState`，在 `globalSetup` 捕获并在每个测试复用，`cy.setCookie`/`driver.add_cookie`→`browserContext.addCookies()`；`npx playwright migrate` 报 unknown command→该内置命令不存在，改用 cy2pw 或 `@11joselu/cypress-to-playwright`；迁移后 intercept 不匹配→1.52 glob 变更去掉了 `?`/`[]`，转义字符或改写成 regex；`route.continue()` 设置的 cookie 被忽略→Cookie header 从 cookie store 加载而非你的 override，改用 `browserContext.addCookies()`；本地通过 CI flaky→旧时序假设被字面翻译，把 `waitForTimeout`/显式等待换成 web-first `expect(...)` 断言；codemod 后测试数下降→codemod 静默跳过不支持的语法，推广前按功能区域与对等表 diff 测试数。
27. 验证迁移产物（从最小检查开始）：`npx playwright test <migrated-file>`（或 `npx vitest run <migrated-file>`）退出码为 0；按功能区域 diff 新旧测试数并与覆盖率表核对（用 `npx playwright test --list | wc -l` 按区域统计）；并行 CI workflow 中旧 job 为 `continue-on-error: true`、新 job 阻塞且两者都出现在 pipeline 中；删除任何旧测试前新套件连续 2+ 个 sprint CI 全绿。
28. 完成标准：迁移范围已定义（先迁关键路径、后迁低优先级、有意不迁的每个都在覆盖率表中记录理由）；覆盖率对等表显示所有 critical/high 功能区域 100% 且测试数相对映射的旧测试无下降；两个框架已在 CI 并行运行至少 2 个连续 sprint 且新套件全绿；存在迁移回顾文档记录 flaky 根因、模式改进与团队培训缺口；旧框架完全移除（`package.json` 删除依赖、删除而非禁用旧测试文件、CI 只跑新套件）。

适用边界 · 注意事项

• 同一框架下 UI 重构后需要批量重新生成选择器时——用 selector-drift-recovery。
• 运行时修复单个 flaky 测试时——用 test-reliability。
• 不更换框架、只想现代化测试模式时——用 ai-qa-review。