migrate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrate to Playwright

迁移至Playwright

Interactive migration from Cypress or Selenium to Playwright with file-by-file conversion.

支持从Cypress或Selenium交互式迁移至Playwright，支持逐文件转换。

Input

输入

$ARGUMENTS

can be:

```
"from cypress"
```
— migrate Cypress test suite
```
"from selenium"
```
— migrate Selenium/WebDriver tests
A file path: convert a specific test file
Empty: auto-detect source framework

$ARGUMENTS

可以是：

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

Steps

步骤

1. Detect Source Framework

1. 检测源框架

Use

Explore

subagent to scan:

```
cypress/
```
directory or
```
cypress.config.ts
```
→ Cypress
```
selenium
```
,
```
webdriver
```
in
```
package.json
```
deps → Selenium
```
.py
```
test files with
```
selenium
```
imports → Selenium (Python)

使用

Explore

子代理进行扫描：

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

2. Assess Migration Scope

2. 评估迁移范围

Count files and categorize:

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

Size	Files	Approach
Small (1-10)	Convert sequentially	Direct conversion
Medium (11-30)	Batch in groups of 5	Use sub-agents
Large (31+)	Use `/batch`	Parallel conversion with `/batch`

统计文件数量并分类：

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

规模	文件数量	处理方式
小型（1-10个）	顺序转换	直接转换
中型（11-30个）	按5个一组批量处理	使用子代理
大型（31个以上）	使用 `/batch` 命令	通过 `/batch` 并行转换

3. Set Up Playwright (If Not Present)

3. 配置Playwright（若未配置）

Run

/pw:init

first if Playwright isn't configured.

如果尚未配置Playwright，请先运行

/pw:init

。

4. Convert Files

4. 转换文件

For each file, apply the appropriate mapping:

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

Cypress → Playwright

Load

cypress-mapping.md

for complete reference.

Key translations:

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 custom commands → Playwright fixtures or helper functions Cypress plugins → Playwright config or fixtures before
/
beforeEach
→

test.beforeAll()

test.beforeEach()

查看

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 fixture或辅助函数 Cypress插件 → Playwright配置或fixture before
/
beforeEach
→

test.beforeAll()

test.beforeEach()

Selenium → Playwright

Load

selenium-mapping.md

for complete reference.

Key translations:

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()

查看

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. Upgrade Locators

5. 升级定位器

During conversion, upgrade selectors to Playwright best practices:

```
#id
```
→
```
getByTestId()
```
or
```
getByRole()
```
```
.class
```
→
```
getByRole()
```
or
```
getByText()
```
```
[data-testid]
```
→
```
getByTestId()
```
XPath → role-based locators

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

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

6. Convert Custom Commands / Utilities

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

Cypress custom commands → Playwright custom fixtures via
```
test.extend()
```
Selenium page objects → Playwright page objects (keep structure, update API)
Shared helpers → TypeScript utility functions

Cypress自定义命令 → 通过
```
test.extend()
```
实现Playwright自定义fixture
Selenium页面对象 → Playwright页面对象（保留结构，更新API）
共享辅助函数 → TypeScript工具函数

7. Verify Each Converted File

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

After converting each file:

bash

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

Fix any compilation or runtime errors before moving to the next file.

转换每个文件后：

bash

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

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

8. Clean Up

8. 清理工作

After all files are converted:

Remove Cypress/Selenium dependencies from
```
package.json
```
Remove old config files (
```
cypress.config.ts
```
, etc.)
Update CI workflow to use Playwright
Update README with new test commands

Ask user before deleting anything.

所有文件转换完成后：

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

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

Output

输出

Conversion summary: files converted, total tests migrated
Any tests that couldn't be auto-converted (manual intervention needed)
Updated CI config
Before/after comparison of test run results

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