peach-e2e-convert

E2E scenario conversion expert

Converts scripts recorded with Playwright codegen into CDP scenario files and verifies them by running them directly.

Workflow

Step 1: Receive input

The user provides the Playwright codegen recorded code.

Step 2: Confirm information

Ask the user for the following:

• Scenario name: Korean (e.g., 3-배송정보)
• Save location: Scenario subfolder name (e.g., 시나리오-사용자, 시나리오-백오피스)
• Category: Subfolder name (e.g., 조제등록, 주문관리)
• If it does not exist in an existing category, create a new folder

Step 3: Execute conversion

references/변환규칙.md와 references/코드패턴.mdRefer to and convert.

Required conversion items:

1. chromium.launch() → connect() (use lib/connect.js)
2. page.goto('/path') → Automatically navigate after page check
3. browser.close() / context.close() Remove
4. page.pause() Remove
5. Add dialog handler (must keep reference + removeListener in finally)
6. Wrap in try-catch-finally + exitCode pattern (process.exit(0) Do not force exit → process.exit(exitCode))
7. Add emoji logs
8. waitForTimeout Minimize → Convert to conditional wait
9. Popup (waitForEvent('popup')) → Detect closing with waitForEvent('close') use

Step 4: Save and verify execution

• Save file: e2e/시나리오/{저장위치}/{카테고리}/{이름}.js
• After saving, verify by running directly immediately:
  1. Check CDP connection:

     cd e2e && ./e2e.sh status
     

     If CDP is not connected, guide the user: cd e2e && ./e2e.sh chrome request execution.
  2. Scenario execution (playwright-cli based):

     cd e2e && ./e2e.sh run 시나리오/{저장위치}/{카테고리}/{이름}.js
     # 탭 지정 시:
     cd e2e && ./e2e.sh run --tab 0 시나리오/{저장위치}/{카테고리}/{이름}.js
     

  3. Analyze execution log:
     • ✨ 완료! Check log → success
     • ❌ 에러: Log occurs → analyze cause, fix code → rerun
     • CDP error: Session not found → Session disconnection recovery:

       agent-browser connect 9222
       agent-browser tab list
       agent-browser tab N
       agent-browser eval "document.title"  # 복구 확인 후 재실행
       

     • Repeat fix-rerun until the error is resolved
  4. Syntax validation immediately after saving:

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

     If there is a syntax error, fix it before execution.

Selector debugging (agent-browser eval preferred)

If a selector error occurs during scenario execution, agent-browser evalcheck the current DOM with.

# 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 확인
agent-browser eval "location.pathname"

# 요소 개수 확인
agent-browser eval "document.querySelectorAll('.target').length"

Debugging elements inside an iframe is not possible with agent-browser → playwright-cli fallback:

./e2e/pwc.sh eval "document.querySelector('iframe[src*=target]').contentDocument.querySelector('#element').innerText"

Framework-specific handling

Selector and wait strategies differ depending on the framework of the target project. references/프레임워크-대응.mdRefer to and apply the appropriate pattern.

Core principles

• Understand the DOM structure of the target project and apply an appropriate selector strategy
• Modal handling: refer to framework-specific patterns (iframe vs Portal/Teleport)
• Always lib/connect.js의 connect() use function
• Execution must be node — buncannot use CDP WebSocket connection
• dialog handler is installed conditionally, not globally. In the codegen result, page.on('dialog', ...)If present, narrow the review to a local recorder or a step-by-step handler
• In a saved scenario, window.alert/confirm if there is an override, finallyin, restore code is required
• External service link switching is click() apply the fallback URL reachability rule rather than a single line (peach-e2e-browse/references/외부서비스-링크전환-패턴.md)
• Immediately after saving, node --checksyntax validation is required with

Reference document

Document	Purpose
references/변환규칙.md	General CDP conversion rules + troubleshooting
references/코드패턴.md	Basic structure of scenario files and emoji log rules
references/프레임워크-대응.md	Differences by framework such as React/Vue/Next.js