peach-e2e-scenario

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

E2E 시나리오 통합 전문가

E2E场景整合专家

시나리오 생성 + 실행 + 자동수정을 하나의 루프로 처리한다. 기존 시나리오 코드 패턴을 참조하고, 필요시 DOM을 실시간 조사하여 시나리오를 작성한다. 실행 실패 시 에러를 분석하고 스크립트를 직접 수정하여 재실행한다.

将场景生成+执行+自动修正整合为一个循环流程处理。参考现有场景代码模式，必要时实时调查DOM来编写场景。执行失败时分析错误，直接修改脚本后重新执行。

모드

模式

모드	트리거	동작
`auto` (기본)	`/peach-e2e-scenario [설명]`	생성 + 실행 + 자동수정 루프
`create`	`/peach-e2e-scenario create [설명 or codegen]`	시나리오 생성만
`run`	`/peach-e2e-scenario run [경로 or 번호]`	실행 + 자동수정 루프

模式	触发方式	操作
`auto` （默认）	`/peach-e2e-scenario [描述]`	生成+执行+自动修正循环
`create`	`/peach-e2e-scenario create [描述 or codegen]`	仅生成场景
`run`	`/peach-e2e-scenario run [路径 or 编号]`	执行+自动修正循环

도구 역할 분담

工具职责分工

용도	도구
시나리오 실행	`./e2e.sh run` (playwright-cli 기반)
셀렉터 디버깅/DOM 확인	`agent-browser eval` (빠름)
iframe 디버깅	`./e2e/pwc.sh eval` (fallback)
문법 검증	`node --check`

用途	工具
场景执行	`./e2e.sh run` （基于playwright-cli）
选择器调试/DOM检查	`agent-browser eval` （快速）
iframe调试	`./e2e/pwc.sh eval` （备选）
语法验证	`node --check`

강제 게이트

强制限制

```
./e2e.sh status
```
로 탭 목록을 확인하고 사용자가 실행 탭을 지정하기 전에는
```
./e2e.sh run
```
,
```
agent-browser eval
```
, 탭 전환을 시작하지 않는다.
Google 로그인, OAuth, 관리자 콘솔, 결제, 기존 Chrome Beta 프로필 세션 유지가 핵심인 작업은 시나리오 생성/분석까지만 진행하고, 실제 실행은 사용자 확인 후 시작한다.
```
agent-browser
```
디버깅이 비정상이면 OS 레벨 브라우저 우회(
```
open -a
```
, 다른 브라우저 실행, 다른 프로필 경로 사용)를 하지 않는다.
로그인/2차 인증이 필요하면 AI가 직접 처리하지 않고, 사용자가 Chrome Beta 고정 프로필에서 먼저 인증을 완료하도록 안내한다.

在用户通过
```
./e2e.sh status
```
查看标签页列表并指定执行标签页前，不得启动
```
./e2e.sh run
```
、
```
agent-browser eval
```
及标签页切换操作。
对于以Google登录、OAuth、管理员控制台、支付、保留现有Chrome Beta配置文件会话为核心的任务，仅进行场景生成/分析，实际执行需等待用户确认后启动。
若
```
agent-browser
```
调试异常，不得采用OS级浏览器绕过方案（如
```
open -a
```
、启动其他浏览器、使用其他配置文件路径）。
若需要登录/二次认证，AI不直接处理，需引导用户在Chrome Beta固定配置文件中先完成认证。

워크플로우

工作流

공통: 환경 확인 + 탭 확인

通用步骤：环境检查 + 标签页确认

bash

cd e2e && ./e2e.sh setup

setup

이 모든 환경(Chrome Beta, agent-browser, playwright-cli, CDP 연결)을 자동 체크/설치한다. CDP 미연결이면 아래 순서로 자동 복구를 먼저 시도한다.

```
cd e2e && ./e2e.sh chrome &
```
실행
```
sleep 4
```
대기
```
cd e2e && ./e2e.sh status
```
재확인
여전히 미연결이면 사용자에게
```
cd e2e && ./e2e.sh chrome
```
수동 실행을 안내한다

bash

cd e2e && ./e2e.sh status

탭 목록을 사용자에게 보여주고 "몇 번 탭에서 실행할까요?" 확인.

탭 번호는 0번부터 시작.
chrome://
탭은 제외.
[번호]
가
--tab N
의 N과 동일. 사용자가 로그인한 탭을 그대로 사용. 환경(local/test/prod) 구분 없음. 탭 번호를 받기 전에는 실행하지 않는다. 민감 세션 작업은 탭 번호를 받아도 사용자 승인 전까지 분석만 수행한다. 탭 드리프트 방지: 사용자가 탭 번호를 응답한 뒤
agent-browser tab N
직후
agent-browser eval "document.title + ' | ' + location.href"
로 탭이 맞는지 재검증한다. 예상과 다르면
./e2e.sh status
재출력 후 재선택. 디버깅/재현 시에는
E2E_TAB_ID
고정 권장. (상세:
peach-e2e-browse/references/탭-선택-패턴.md
)

파일 업로드 시나리오: 시나리오 코드에서
page.setInputFiles()
또는 file input 조작이 필요하면 OS 네이티브 파일 다이얼로그 차단을 위해
Page.setInterceptFileChooserDialog
방식을 사용한다. CDP Escape /
agent-browser press Escape
로는 macOS 네이티브 다이얼로그를 닫을 수 없다. (상세:
peach-e2e-browse/references/SPA-프레임워크-입력패턴.md §3
)

bash

cd e2e && ./e2e.sh setup

setup

会自动检查/安装所有环境（Chrome Beta、agent-browser、playwright-cli、CDP连接）。若CDP未连接，将按以下顺序自动尝试恢复：

执行
```
cd e2e && ./e2e.sh chrome &
```
等待
```
sleep 4
```
重新执行
```
cd e2e && ./e2e.sh status
```
确认
若仍未连接，引导用户手动执行
```
cd e2e && ./e2e.sh chrome
```

bash

cd e2e && ./e2e.sh status

向用户展示标签页列表并确认**“要在第几个标签页执行？”**

标签页编号从0开始。排除
chrome://
标签页。
[编号]
与
--tab N
中的N一致。直接使用用户已登录的标签页，不区分环境（local/test/prod）。在收到标签页编号前不得执行。敏感会话任务即使收到标签页编号，也需在用户批准前仅进行分析。 防止标签页漂移：用户回复标签页编号后，执行
agent-browser tab N
，紧接着通过
agent-browser eval "document.title + ' | ' + location.href"
重新验证标签页是否正确。若与预期不符，重新输出
./e2e.sh status
并让用户重新选择。调试/复现阶段建议固定
E2E_TAB_ID
。（详情：
peach-e2e-browse/references/标签页选择模式.md
）

文件上传场景：若场景代码中需要
page.setInputFiles()
或操作文件输入框，为拦截OS原生文件对话框，需使用
Page.setInterceptFileChooserDialog
方式。 CDP Escape /
agent-browser press Escape
无法关闭macOS原生对话框。（详情：
peach-e2e-browse/references/SPA框架输入模式.md §3
）

auto 모드 (기본)

auto模式（默认）

입력 소스 판별 — 자연어 요청 vs codegen 녹화 코드
기존 시나리오 패턴 참조 —
```
e2e/시나리오/
```
하위 기존 코드를 읽어 패턴 파악
- ```
references/시나리오-생성-패턴.md
```
  참조
DOM 선조사 (필요시) — agent-browser eval로 URL 구조, 셀렉터 사전 확인
시나리오 생성 —
```
references/코드패턴.md
```
참조하여 스크립트 작성
- codegen 입력인 경우
```
references/변환규칙.md
```
  추가 참조
- 프레임워크별 차이는
```
references/프레임워크-대응.md
```
  참조
정보 확인 — 시나리오 이름(한글), 저장 위치(하위 폴더), 카테고리
문법 검증 —
```
node --check
```
통과 확인
실행 승인 확인
- 일반 화면: 탭 번호와 시나리오 경로를 확인한 뒤 실행
- Google/OAuth/관리자/결제/기존 Chrome Beta 프로필 세션 유지 작업:
```
./e2e.sh run
```
  실행 전 반드시 사용자에게 실제 실행 승인을 다시 확인

실행 —

./e2e.sh run --tab N 시나리오/경로

자동수정 루프 — 실패 시 아래 자동수정 루프 진행
결과 보고

输入源判断 — 自然语言请求 vs codegen录制代码
参考现有场景模式 — 读取
```
e2e/场景/
```
下的现有代码来掌握模式
- 参考
```
references/场景生成模式.md
```
预调查DOM（必要时） — 通过agent-browser eval提前确认URL结构、选择器
生成场景 — 参考
```
references/代码模式.md
```
编写脚本
- 若为codegen输入，额外参考
```
references/转换规则.md
```
- 框架差异参考
```
references/框架适配.md
```
信息确认 — 场景名称（韩文）、保存位置（子文件夹）、分类
语法验证 — 确认通过
```
node --check
```
执行确认
- 普通页面：确认标签页编号和场景路径后执行
- Google/OAuth/管理员/支付/保留现有Chrome Beta配置文件会话的任务：执行
```
./e2e.sh run
```
  前必须再次向用户确认是否执行
执行 —
```
./e2e.sh run --tab N 场景/路径
```
自动修正循环 — 失败时执行下方自动修正循环
结果报告

create 모드

create模式

입력 소스 판별

자연어 요청 →

references/시나리오-생성-패턴.md

references/코드패턴.md

참조

codegen 녹화 →

references/변환규칙.md

references/코드패턴.md

참조

정보 확인 — 시나리오 이름(한글), 저장 위치, 카테고리
시나리오 생성
- 필수 변환 항목 (codegen 입력 시):
  1. ```
  chromium.launch()
```
  →
```
  connect()
```
  (lib/connect.js 사용)
2. ```
page.goto('/path')
```
    → 현재 탭 상태 확인 후 조건부 이동
    - 민감 세션이거나 사용자 승인 없으면 자동 이동 금지
    - 비민감 세션 + 사용자 승인 확보 시에만
      page.goto()
  3. ```
  browser.close()
```
  /
```
  context.close()
```
  제거
4. ```
page.pause()
```
    제거
  5. 다이얼로그 핸들러 추가 (
```
setDialogHandler
```
    교체 + finally에서 원복 필수)
  6. try-catch-finally + exitCode 패턴 래핑 (
```
process.exit(0)
```
    고정 종료 금지)
  7. 이모지 로그 추가
  8. ```
  waitForTimeout
```
  최소화 → 조건 대기로 변환
9. 팝업(
```
  waitForEvent('popup')
```
  ) → 닫힘 감지는
```
  waitForEvent('close')
```
  사용
문법 검증 —
```
node --check
```
통과 확인

저장 보고 —

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

输入源判断

自然语言请求 → 参考

references/场景生成模式.md

references/代码模式.md

codegen录制 → 参考

references/转换规则.md

references/代码模式.md

信息确认 — 场景名称（韩文）、保存位置、分类
生成场景
- 必填转换项（codegen输入时）：
  1. ```
  chromium.launch()
```
  →
```
  connect()
```
  （使用lib/connect.js）
2. ```
page.goto('/path')
```
    → 检查当前标签页状态后条件式跳转
    - 敏感会话或未获用户批准时禁止自动跳转
    - 仅在非敏感会话+获得用户批准时使用
      page.goto()
  3. 删除
```
browser.close()
```
    /
```
context.close()
```
  4. 删除
```
page.pause()
```
  5. 添加对话框处理器（替换
```
setDialogHandler
```
    + 必须在finally中恢复）
  6. 用try-catch-finally + exitCode模式包裹（禁止固定使用
```
process.exit(0)
```
    结束）
  7. 添加表情日志
  8. 最小化
```
waitForTimeout
```
    → 转换为条件等待
  9. 弹窗(
```
waitForEvent('popup')
```
    ) → 使用
```
waitForEvent('close')
```
    检测关闭
语法验证 — 确认通过
```
node --check
```

保存报告 —

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

run 모드

run模式

시나리오 선택
bash
```
cd e2e && ./e2e.sh list
```
실행 승인 확인
- 로그인된 실탭/고정 프로필 세션 유지가 핵심인 시나리오는 실행 전 사용자 승인 필수

실행

bash

cd e2e && ./e2e.sh run --tab N 시나리오/경로

자동수정 루프 — 실패 시 아래 자동수정 루프 진행
결과 보고

选择场景
bash
```
cd e2e && ./e2e.sh list
```
执行确认
- 以保留已登录的实际标签页/固定配置文件会话为核心的场景，执行前必须获得用户批准

执行

bash

cd e2e && ./e2e.sh run --tab N 场景/路径

自动修正循环 — 失败时执行下方自动修正循环
结果报告

자동수정 루프 (최대 3회)

自动修正循环（最多3次）

시나리오 실행 결과가

❌ 에러:

이면 스크립트를 직접 수정하여 재실행한다. 단순 디버깅 안내에 그치지 않고, 원인을 파악하여 시나리오 파일을 고친 뒤 다시 실행하는 것까지가 이 스킬의 책임이다.

상세:

references/자동수정-판단트리.md

참조

若场景执行结果显示

❌ 错误:

，则直接修改脚本并重新执行。该技能的职责不仅是提供调试指导，还需定位原因、修改场景文件后重新执行。

详情参考：

references/自动修正判断树.md

판단 기준

判断标准

에러 유형	처리 방법
셀렉터 불일치 (timeout, locator not found)	agent-browser eval로 실제 DOM 확인 → 시나리오 셀렉터 수정
dialog 자동 닫힘 ( `기록하지 못했습니다` , dismiss)	daemon 잔류 확인 후 kill → `setDialogHandler` 패턴 미적용이면 수정
popup `waitForEvent('close')` 에러	`Promise.race` + `.catch(() => {})` 패턴 적용
URL 패턴 불일치 ( `waitForURL` timeout)	실제 이동 URL 확인 → 패턴 수정
타이밍 문제 ( `waitForTimeout` 후 즉시 실패)	고정 대기 → `waitForEvent` 또는 `waitForFunction` 이벤트 기반으로 교체
`Target page, context or browser has been closed`	팝업/탭이 예상보다 일찍 닫힘 → `.catch(() => {})` 또는 `closeTarget` 옵션 추가
navigation timeout (AJAX submit)	waitForNavigation 제거 또는 waitForURL로 교체
서버 에러 (500, 네트워크 에러)	자동수정 불가 → 사용자에게 보고 후 중단

错误类型	处理方式
选择器不匹配（timeout、locator not found）	通过agent-browser eval检查实际DOM → 修改场景选择器
对话框自动关闭（ `未记录到` 、dismiss）	检查是否存在残留daemon并kill → 若未应用 `setDialogHandler` 模式则修改
弹窗 `waitForEvent('close')` 错误	应用 `Promise.race` + `.catch(() => {})` 模式
URL模式不匹配（ `waitForURL` timeout）	检查实际跳转URL → 修改模式
时序问题（ `waitForTimeout` 后立即失败）	将固定等待 → 替换为 `waitForEvent` 或 `waitForFunction` 事件驱动方式
`Target page, context or browser has been closed`	弹窗/标签页比预期提前关闭 → 添加 `.catch(() => {})` 或 `closeTarget` 选项
navigation timeout（AJAX提交）	删除waitForNavigation或替换为waitForURL
服务器错误（500、网络错误）	无法自动修正 → 向用户报告后终止

루프 절차

循环流程

1. 에러 메시지 파싱 → 유형 판별
2. agent-browser eval로 실제 DOM/URL 확인
3. 시나리오 스크립트 수정
4. 재실행
5. 여전히 실패? → 1로 돌아감 (최대 3회)
6. 3회 실패 → 에러 이력 요약 → 사용자에게 보고 → peach-e2e-browse 안내

1. 解析错误消息 → 判断类型
2. 通过agent-browser eval检查实际DOM/URL
3. 修改场景脚本
4. 重新执行
5. 仍失败？ → 返回步骤1（最多3次）
6. 3次失败 → 汇总错误历史 → 向用户报告 → 引导使用peach-e2e-browse

수정 후 재실행

修改后重新执行

bash

E2E_TAB_ID=<id> ./e2e.sh run '시나리오/대상.js'

dialog 관련 오류라면 실행 전 반드시 daemon 잔류 확인:
bash
lsof -iTCP:9222 -sTCP:ESTABLISHED -n -P | awk '/node/{print $2}' | xargs kill -9 2>/dev/null

bash

E2E_TAB_ID=<id> ./e2e.sh run '场景/目标.js'

若为对话框相关错误，执行前必须检查是否存在残留daemon:
bash
lsof -iTCP:9222 -sTCP:ESTABLISHED -n -P | awk '/node/{print $2}' | xargs kill -9 2>/dev/null

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

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

bash

undefined

bash

undefined

CDP 연결 (1회)

CDP连接（单次）

agent-browser connect 9222

현재 URL 확인

检查当前URL

agent-browser eval "location.href"

셀렉터 존재 여부

检查选择器是否存在

agent-browser eval "document.querySelector('.target') !== null"

버튼 목록

获取按钮列表

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

요소 개수

获取元素数量

agent-browser eval "document.querySelectorAll('tr').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('tr').length"


> iframe内部调试无法使用agent-browser → 改用playwright-cli备选方案:
> ```bash
> ./e2e/pwc.sh eval "document.querySelector('iframe[src*=target]').contentDocument.querySelector('#element').innerText"
> ```

native dialog 시나리오 규칙

原生对话框场景规则

```
window.alert/confirm
```
JS monkey-patch는 동작하지 않는다 — Playwright CDP 자동 dismiss가 먼저 실행됨. 사용 금지.
native dialog 처리는 반드시 CDP 레이어 handler (
```
page.on('dialog', handler)
```
) 사용.
```
connect.js
```
의
```
setDialogHandler(page, prevHandler, newHandler)
```
유틸로 handler를 교체하고, finally에서 반드시 복원. 다중
```
page.on('dialog')
```
등록 시 모두 실행되어 충돌("already handled") 발생 — 교체 패턴 필수.
popup(
```
waitForEvent('popup')
```
)은
```
connect.js
```
를 거치지 않으므로 별도 handler 등록 필요.

process.exit(0)

고정 종료 금지 →

try/catch/finally + exitCode

패턴 사용.

페이지 상태 의존 로직은 클릭 전에 명시적 대기.
dialog 대기는 고정
```
waitForTimeout
```
대신
```
page.waitForEvent('dialog')
```
이벤트 기반 사용.

상세:

peach-e2e-browse/references/native-dialog-주의사항.md

참조

```
window.alert/confirm
```
JS monkey-patch无效 — Playwright CDP会先自动执行dismiss。禁止使用.
原生对话框处理必须使用CDP层处理器（
```
page.on('dialog', handler)
```
）.
使用
```
connect.js
```
的
```
setDialogHandler(page, prevHandler, newHandler)
```
工具替换处理器，并必须在finally中恢复。多次注册
```
page.on('dialog')
```
会导致全部执行并引发冲突（"already handled"） — 必须使用替换模式.
弹窗(
```
waitForEvent('popup')
```
)不经过
```
connect.js
```
，需单独注册处理器.

禁止固定使用

process.exit(0)

结束 → 使用

try/catch/finally + exitCode

模式.

依赖页面状态的逻辑需在点击前显式等待.
对话框等待需使用
```
page.waitForEvent('dialog')
```
事件驱动方式，而非固定
```
waitForTimeout
```
.

详情参考：

peach-e2e-browse/references/原生对话框注意事项.md

외부 서비스 전환

外部服务跳转

외부 사이트(Google, Gmail 등) 진입은

load + 2초 지연 + 직접 이동 fallback

패턴 사용. 상세:

peach-e2e-browse/references/외부서비스-링크전환-패턴.md

참조

进入外部网站（Google、Gmail等）需使用

load + 2秒延迟 + 直接跳转备选

模式。详情参考：

peach-e2e-browse/references/外部服务链接跳转模式.md

탭 선택 규칙

标签页选择规则

일반 실행:
```
--tab N
```
(빠른 실행용)
디버깅/재현/장애분석:
```
E2E_TAB_ID
```
우선 (인덱스 드리프트 방지)

bash

undefined

普通执行:
```
--tab N
```
（快速执行用）
调试/复现/故障分析: 优先使用
```
E2E_TAB_ID
```
（防止索引漂移）

bash

undefined

targetId 조회

查询targetId

curl -s http://127.0.0.1:9222/json | jq -r '.[] | select(.type=="page" and (.url|startswith("chrome")|not)) | [.id,.title,.url] | @tsv'

targetId로 실행

通过targetId执行

cd e2e && E2E_TAB_ID=<targetId> ./e2e.sh run '시나리오/대상.js'


상세: `peach-e2e-browse/references/탭-선택-패턴.md` 참조

cd e2e && E2E_TAB_ID=<targetId> ./e2e.sh run '场景/目标.js'


详情参考：`peach-e2e-browse/references/标签页选择模式.md`

핵심 원칙

核心原则

항상
```
lib/connect.js
```
의
```
connect()
```
함수 사용
실행은 반드시
node
—
```
bun
```
은 CDP WebSocket 연결 불가
대상 프로젝트의 DOM 구조를 파악하고 적절한 셀렉터 전략 적용
모달 처리: 프레임워크별 패턴 참조 (iframe vs Portal/Teleport)
dialog handler는 전역이 아닌 조건부 설치
외부 서비스 링크 전환은
```
click()
```
한 줄이 아닌 fallback URL 도달 규칙 적용
저장 직후
```
node --check
```
로 문법 검증 필수
탭 미확인 상태와 민감 세션 작업에서는 분석만 수행하고 실행은 사용자 확인 후 진행

始终使用
```
lib/connect.js
```
的
```
connect()
```
函数
必须使用
node
执行 —
```
bun
```
无法连接CDP WebSocket
掌握目标项目的DOM结构并应用合适的选择器策略
模态框处理：参考框架专属模式（iframe vs Portal/Teleport）
对话框处理器需按需安装，而非全局安装
外部服务链接跳转不能仅用
```
click()
```
一行代码，需应用备选URL到达规则
保存后必须通过
```
node --check
```
进行语法验证
未确认标签页状态及敏感会话任务中，仅进行分析，执行需等待用户确认后进行

참조 문서

参考文档

문서	용도	로드 조건
`references/코드패턴.md`	시나리오 기본 구조 (IIFE, exitCode, 이모지)	create, auto
`references/변환규칙.md`	codegen → CDP 변환 규칙	codegen 입력 시
`references/프레임워크-대응.md`	레거시/모던 프레임워크 분기	create, auto
`references/시나리오-생성-패턴.md`	기존 코드 참조 기반 생성 가이드	create, auto
`references/validation-통과-패턴.md`	form validation 우회 패턴	create, auto
`references/자동수정-판단트리.md`	에러 유형별 자동수정 전략	run, auto 실패 시
`references/daemon-잔류-대응.md`	CDP daemon 문제 해결	dialog 에러 시
`references/dialog-handler-패턴.md`	native dialog 처리 메커니즘	dialog 시나리오

文档	用途	加载条件
`references/代码模式.md`	场景基础结构（IIFE、exitCode、表情）	create、auto
`references/转换规则.md`	codegen → CDP转换规则	codegen输入时
`references/框架适配.md`	遗留/现代框架分支处理	create、auto
`references/场景生成模式.md`	基于现有代码参考的生成指南	create、auto
`references/validation通过模式.md`	表单验证绕过模式	create、auto
`references/自动修正判断树.md`	错误类型专属自动修正策略	run、auto失败时
`references/daemon残留应对.md`	CDP daemon问题解决	对话框错误时
`references/dialog-handler模式.md`	原生对话框处理机制	对话框场景