迁移

迁移至 Playwright

通过逐文件转换，实现从 Cypress 或 Selenium 到 Playwright 的交互式迁移。

输入

$ARGUMENTS 可以是：

• "from cypress" — 迁移 Cypress 测试套件

• "from selenium" — 迁移 Selenium/WebDriver 测试

• 文件路径：转换特定的测试文件

• 为空：自动检测源框架

步骤

1. 检测源框架

使用 Explore 子代理进行扫描：

• cypress/ 目录或 cypress.config.ts → Cypress

• package.json 依赖中包含 selenium 或 webdriver → Selenium

• 包含 selenium 导入的 .py 测试文件 → Selenium (Python)

2. 评估迁移范围

统计文件数量并进行分类：

迁移评估：
测试文件总数：X
Cypress 自定义命令：Y
Cypress 静态数据 (fixtures)：Z
预计工作量：[small|medium|large]

| 规模 | 文件数 | 方案 |
|---|---|---|
| 小 (1-10) | 顺序转换 | 直接转换 |
| 中 (11-30) | 每 5 个一组分批转换 | 使用子代理 |
| 大 (31+) | 使用 /batch | 通过 /batch 进行并行转换 |

3. 安装 Playwright（如果尚未安装）

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

4. 转换文件

针对每个文件，应用相应的映射关系：

#### Cypress → Playwright

加载 cypress-mapping.md 以获取完整参考。

关键转换对照：

cy.visit(url)           → page.goto(url)
cy.get(selector)        → page.locator(selector) 或 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 导入或测试数据文件

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') 或 page.getByTestId('x')
driver.findElement(By.css('.x'))   → page.locator('.x') 或 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 → 基于角色的定位器 (role-based locators)

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

• Cypress 自定义命令 → 通过 test.extend() 实现 Playwright 自定义 fixtures

• Selenium 页面对象 (Page Objects) → Playwright 页面对象（保留结构，更新 API）

• 共享辅助函数 → TypeScript 工具函数

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

在...
逐个转换文件：

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

在转换下一个文件之前，请先修复所有编译或运行时错误。

8. 清理

所有文件转换完成后：

• 从 package.json 中移除 Cypress/Selenium 依赖

• 删除旧的配置文件（如 cypress.config.ts 等）

• 更新 CI 工作流以使用 Playwright

• 在 README 中更新新的测试命令

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

输出

• 转换摘要：转换的文件数、迁移的测试总数

• 无法自动转换的测试（需要手动干预）

• 更新后的 CI 配置

• 测试运行结果的前后对比