migrate

迁移到 Playwright

从 Cypress 或 Selenium 逐文件交互式迁移到 Playwright。

输入

$ARGUMENTS 可以是：

• "from cypress"：迁移 Cypress 测试套件
• "from selenium"：迁移 Selenium/WebDriver 测试
• 文件路径：转换指定的测试文件
• 留空：自动检测源框架

步骤

1. 检测源框架

使用 Explore 子 Agent 扫描：

• cypress/ 目录或 cypress.config.ts → Cypress
• package.json 依赖中的 selenium、webdriver → Selenium
• 导入了 selenium 的 .py 测试文件 → Selenium（Python）

2. 评估迁移范围

统计文件数量并分类：

Migration Assessment:
- Total test files: X
- Cypress custom commands: Y
- Cypress fixtures: Z
- Estimated effort: [small|medium|large]

规模	文件数	方式
小型（1-10）	顺序转换	直接转换
中型（11-30）	每 5 个一组分批处理	使用子 Agent
大型（31+）	使用 /batch	使用 /batch 并行转换

3. 设置 Playwright（如未配置）

如果尚未配置 Playwright，请先运行 /pw:pw-init。

4. 转换文件

对每个文件，应用相应的映射规则：

Cypress → Playwright

完整参考请加载 cypress-mapping.md。

主要转换规则：

cy.visit(url)           → page.goto(url)
cy.get(selector)        → page.locator(selector) or page.getByRole(...)
cy.contains(text)       → page.getByText(text)
cy.find(selector)       → locator.locator(selector)
cy.click()              → locator.click()
cy.type(text)           → locator.fill(text)
cy.should('be.visible') → expect(locator).toBeVisible()
cy.should('have.text')  → expect(locator).toHaveText(text)
cy.intercept()          → page.route()
cy.wait('@alias')       → page.waitForResponse()
cy.fixture()            → JSON import or test data file

Cypress 自定义命令 → Playwright fixtures 或辅助函数 Cypress 插件 → Playwright 配置或 fixtures before/beforeEach → test.beforeAll() / test.beforeEach()

Selenium → Playwright

完整参考请加载 selenium-mapping.md。

主要转换规则：

driver.get(url)                    → page.goto(url)
driver.findElement(By.id('x'))     → page.locator('#x') or page.getByTestId('x')
driver.findElement(By.css('.x'))   → page.locator('.x') or page.getByRole(...)
element.click()                    → locator.click()
element.sendKeys(text)             → locator.fill(text)
element.getText()                  → locator.textContent()
WebDriverWait + ExpectedConditions → expect(locator).toBeVisible()
driver.switchTo().frame()          → page.frameLocator()
Actions                            → locator.hover(), locator.dragTo()

5. 升级定位器

转换过程中，将选择器升级为 Playwright 最佳实践：

• #id → getByTestId() 或 getByRole()
• .class → getByRole() 或 getByText()
• [data-testid] → getByTestId()
• XPath → 基于角色的定位器

6. 转换自定义命令 / 工具函数

• Cypress 自定义命令 → 通过 test.extend() 实现的 Playwright 自定义 fixtures
• Selenium page objects → Playwright page objects（保持结构，更新 API）
• 共享辅助函数 → TypeScript 工具函数

7. 验证每个已转换的文件

转换每个文件后：

npx playwright test <converted-file> --reporter=list

在进入下一个文件之前，修复所有编译或运行时错误。

8. 清理

所有文件转换完成后：

• 从 package.json 中移除 Cypress/Selenium 依赖
• 删除旧的配置文件（cypress.config.ts 等）
• 更新 CI 工作流以使用 Playwright
• 更新 README，写入新的测试命令

删除任何内容前须先询问用户。

输出

• 转换摘要：已转换的文件数、迁移的测试总数
• 无法自动转换的测试（需要人工介入）
• 更新后的 CI 配置
• 测试运行结果的前后对比