peach-e2e-convert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

E2E 시나리오 변환 전문가

E2E场景转换专家

Playwright codegen으로 녹화한 스크립트를 CDP 시나리오 파일로 변환하고 직접 실행하여 검증한다.

将通过Playwright codegen录制的脚本转换为CDP场景文件并直接运行验证。

워크플로우

工作流

1단계: 입력 수신

第1步：接收输入

사용자가 Playwright codegen 녹화 코드를 전달한다.

用户提交Playwright codegen录制的代码。

2단계: 정보 확인

第2步：确认信息

다음을 사용자에게 물어본다:

시나리오 이름: 한글 (예:
```
3-배송정보
```
)
저장 위치: 시나리오 하위 폴더명 (예:
```
시나리오-사용자
```
,
```
시나리오-백오피스
```
)
카테고리: 하위 폴더명 (예:
```
조제등록
```
,
```
주문관리
```
)
기존 카테고리에 없으면 새 폴더 생성

向用户询问以下内容：

场景名称：韩语（例：
```
3-配送信息
```
）
存储位置：场景下级文件夹名（例：
```
场景-用户
```
、
```
场景-后台
```
）
分类：下级文件夹名（例：
```
调剂登记
```
、
```
订单管理
```
）
现有分类不存在时新建文件夹

3단계: 변환 실행

第3步：执行转换

references/변환규칙.md

와

references/코드패턴.md

를 참조하여 변환한다.

필수 변환 항목:

```
chromium.launch()
```
→
```
connect()
```
(lib/connect.js 사용)
```
page.goto('/path')
```
→ 페이지 체크 후 자동 이동
```
browser.close()
```
/
```
context.close()
```
제거
```
page.pause()
```
제거
다이얼로그 핸들러 추가 (참조 보관 + finally에서 removeListener 해제 필수)
try-catch-finally +
```
process.exit(0)
```
래핑
이모지 로그 추가
```
waitForTimeout
```
최소화 → 조건 대기로 변환

팝업(

waitForEvent('popup')

) → 닫힘 감지는

waitForEvent('close')

사용

参考

references/转换规则.md

和

references/代码模式.md

进行转换。

必填转换项：

```
chromium.launch()
```
→
```
connect()
```
（使用lib/connect.js）
```
page.goto('/path')
```
→ 页面检查后自动跳转
移除
```
browser.close()
```
/
```
context.close()
```
移除
```
page.pause()
```
添加对话框处理器（必须保留引用 + 在finally中移除监听器）
用try-catch-finally +
```
process.exit(0)
```
包裹
添加emoji日志
尽量减少
```
waitForTimeout
```
→ 转换为条件等待

弹窗(

waitForEvent('popup')

) → 关闭检测使用

waitForEvent('close')

4단계: 저장 및 실행 검증

第4步：存储及运行验证

파일 저장:

e2e/시나리오/{저장위치}/{카테고리}/{이름}.js

저장 후 즉시 직접 실행하여 검증:
1. CDP 연결 확인:
  bash
```
cd e2e && ./e2e.sh status
```
  CDP 미연결이면 사용자에게 안내:
```
cd e2e && ./e2e.sh chrome
```
  실행 요청.
2. 시나리오 실행 (playwright-cli 기반):
  bash
```
cd e2e && ./e2e.sh run 시나리오/{저장위치}/{카테고리}/{이름}.js
# 탭 지정 시:
cd e2e && ./e2e.sh run --tab 0 시나리오/{저장위치}/{카테고리}/{이름}.js
```
3. 실행 로그 분석:
  - ```
  ✨ 완료!
```
  로그 확인 → 성공
- ```
❌ 에러:
```
    로그 발생 → 원인 분석 후 코드 수정 → 재실행
  - 에러가 해결될 때까지 수정-재실행 반복

文件存储路径：

e2e/场景/{存储位置}/{分类}/{名称}.js

存储后立即直接运行验证：
1. 确认CDP连接：
  bash
```
cd e2e && ./e2e.sh status
```
  若CDP未连接则提示用户执行：
```
cd e2e && ./e2e.sh chrome
```
2. 运行场景（基于playwright-cli）：
  bash
```
cd e2e && ./e2e.sh run 场景/{存储位置}/{分类}/{名称}.js
# 指定标签页时：
cd e2e && ./e2e.sh run --tab 0 场景/{存储位置}/{分类}/{名称}.js
```
3. 运行日志分析：
  - 确认出现
```
✨ 完成!
```
    日志 → 转换成功
  - 出现
```
❌ 错误:
```
    日志 → 分析原因修改代码 → 重新运行
  - 重复修改-重运行步骤直到错误完全解决

셀렉터 디버깅 (agent-browser eval 우선)

选择器调试（优先使用agent-browser eval）

시나리오 실행 중 셀렉터 에러가 발생하면 agent-browser eval로 현재 DOM을 확인한다.

bash

undefined

场景运行时出现选择器错误，通过agent-browser eval确认当前DOM状态。

bash

undefined

CDP 연결 (1회)

CDP连接（仅需执行1次）

agent-browser connect 9222

셀렉터 존재 여부 확인

确认选择器是否存在

agent-browser eval "document.querySelector('[role=dialog]') !== null"

버튼 텍스트 목록 확인

确认按钮文本列表

agent-browser eval "JSON.stringify(Array.from(document.querySelectorAll('button')).map(function(b){return b.innerText}))"

현재 URL 확인

确认当前URL

agent-browser eval "location.pathname"

요소 개수 확인

确认元素数量

agent-browser eval "document.querySelectorAll('.target').length"


> iframe 내부 요소 디버깅은 agent-browser로 불가 → playwright-cli fallback:
> ```bash
> ./e2e/pwc.sh eval "document.querySelector('iframe[src*=target]').contentDocument.querySelector('#element').innerText"
> ```

agent-browser eval "document.querySelectorAll('.target').length"


> iframe内部元素无法通过agent-browser调试 → 回退使用playwright-cli：
> ```bash
> ./e2e/pwc.sh eval "document.querySelector('iframe[src*=target]').contentDocument.querySelector('#element').innerText"
> ```

프레임워크별 대응

按框架适配

대상 프로젝트의 프레임워크에 따라 셀렉터와 대기 전략이 달라진다.

references/프레임워크-대응.md

를 참조하여 적절한 패턴을 적용한다.

根据目标项目的框架不同，选择器和等待策略也存在差异。参考

references/框架适配.md

应用合适的适配模式。

핵심 원칙

核心原则

대상 프로젝트의 DOM 구조를 파악하고 적절한 셀렉터 전략 적용
모달 처리: 프레임워크별 패턴 참조 (iframe vs Portal/Teleport)
항상
```
lib/connect.js
```
의
```
connect()
```
함수 사용
실행은 반드시
node
—
```
bun
```
은 CDP WebSocket 연결 불가

掌握目标项目的DOM结构，应用合适的选择器策略
模态框处理：参考各框架适配模式（iframe vs Portal/Teleport）
始终使用
```
lib/connect.js
```
的
```
connect()
```
函数
必须使用
node
运行——
```
bun
```
无法建立CDP WebSocket连接

참조 문서

参考文档

문서	용도
`references/변환규칙.md`	범용 CDP 변환 규칙 + 트러블슈팅
`references/코드패턴.md`	시나리오 파일 기본 구조 및 이모지 로그 규칙
`references/프레임워크-대응.md`	React/Vue/Next.js 등 프레임워크별 차이점

文档	用途
`references/转换规则.md`	通用CDP转换规则 + 故障排查
`references/代码模式.md`	场景文件基础结构及emoji日志规则
`references/框架适配.md`	React/Vue/Next.js等框架差异说明