peachsolution/peach-e2e-scenario

E2E 시나리오 통합 전문가

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

모드

| 모드 | 트리거 | 동작 | |------|--------|------| | 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 |

강제 게이트

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

Chrome Beta 실행 불변 규칙

Chrome Beta를 CDP 모드로 실행할 때는 고정 프로필 옵션이 필수다. 프로필 옵션이 빠진 실행은 세션 유지 실패로 간주한다.

• 허용: cd e2e && ./e2e.sh chrome
• 직접 실행 시 필수 옵션: --remote-debugging-port=9222, --remote-allow-origins=*, --user-data-dir=$HOME/.chrome-beta-e2e-profile, --disable-extensions
• macOS 직접 실행 표준: /usr/bin/open -na "Google Chrome Beta" --args ...
• 금지: open -a "Google Chrome Beta" 단독 실행, --args 없는 open 실행, --user-data-dir 없는 Chrome Beta 실행, 다른 프로필 경로 임의 사용, 기본 Chrome 또는 다른 브라우저 우회

워크플로우

공통: 환경 확인 + 탭 확인

cd e2e && ./e2e.sh setup

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

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

./e2e.sh chrome은 고정 프로필($HOME/.chrome-beta-e2e-profile)로 Chrome Beta를 실행하는 표준 경로다. 이 명령 대신 직접 Chrome을 실행할 때도 --user-data-dir 옵션을 생략하지 않는다.

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)

auto 모드 (기본)

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

create 모드

1. 입력 소스 판별
   • 자연어 요청 → references/시나리오-생성-패턴.md + references/코드패턴.md 참조
   • codegen 녹화 → references/변환규칙.md + references/코드패턴.md 참조
2. 정보 확인 — 시나리오 이름(한글), 저장 카테고리 폴더(한글 업무 도메인), 카테고리 내 순번(NN-), 이 시나리오가 남기는 state 계약, 이 시나리오가 요구하는 선행 state 계약
3. 시나리오 생성
   • 필수 변환 항목 (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') 사용
4. 문법 검증 — node --check 통과 확인
5. 저장 보고 — e2e/시나리오/{한글카테고리}/{NN}-{시나리오명}.js
   • 카테고리 폴더 없으면 자동 생성
   • 기존 flat 구조 파일은 즉시 일괄 이동하지 않고, 수정/재작성 시점에만 새 규칙으로 점진 이전
   • 이전 시 기존 경로와 새 경로를 완료 보고에 명시

run 모드

1. 시나리오 선택

   cd e2e && ./e2e.sh list
   

2. 실행 승인 확인
   • 로그인된 실탭/고정 프로필 세션 유지가 핵심인 시나리오는 실행 전 사용자 승인 필수
3. 실행

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

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

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

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

자동수정 중 셀렉터/DOM/프레임워크 상호작용 문제가 의심되면 peach-e2e-browse의 의사결정 트리를 적용해 현재 탭에서 DOM과 상호작용 방식을 재확인한다. 확인한 셀렉터와 이벤트 패턴을 시나리오 코드에 반영한 뒤 재실행한다.

상세: 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, 네트워크 에러) | 자동수정 불가 → 사용자에게 보고 후 중단 |

루프 절차

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

3회 실패 시 진단 패키지 출력

자동수정 3회가 모두 실패하면 anchoring(누적 오답 편향) 위험이 커진다. 같은 컨텍스트에서 무리하게 4회·5회로 늘리지 말고, 새 대화창에서 깨끗한 컨텍스트로 디버깅할 수 있도록 진단 패키지를 구조화하여 출력한다.

출력 형식

🩺 자동수정 3회 실패 — 진단 패키지

## 시나리오
- 파일: <시나리오 파일 절대경로>
- 대상 URL: <실행 대상 URL>
- 탭 ID: <E2E_TAB_ID>

## 시도 이력 (3회)
| 회차 | 추정 원인 | 적용한 수정 | 재실행 결과 |
|------|----------|------------|-----------|
| 1    | <유형>   | <변경 요약> | <에러 메시지 첫 줄> |
| 2    | <유형>   | <변경 요약> | <에러 메시지 첫 줄> |
| 3    | <유형>   | <변경 요약> | <에러 메시지 첫 줄> |

## 마지막 실패 컨텍스트
- 마지막 에러 메시지 (전문)
- 실패 시점 DOM 스냅샷 또는 셀렉터 평가 결과
- 실패 시점 URL

## 추정 막힌 지점
<3회 모두 같은 유형이면 그 유형, 다르면 "다중 원인 의심" 명시>

## 사용자 다음 액션 가이드
1. 새 대화창에서 위 패키지를 첨부하여 디버깅 진행
2. peach-e2e-browse로 현재 탭 상태 직접 확인
3. 시나리오 의도 자체 재검토 필요 가능성

원칙

• 컨텍스트를 새로 시작할 수 있도록 절대경로·전문 에러·전체 시도 이력을 모두 인라인으로 포함한다 (요약 금지)
• 4회·5회로 자동 확장하지 않는다 (Bounded Autonomy: May Suggest 영역, 사용자 결정)
• 사용자가 같은 세션에서 계속 진행을 원하면 추가 시도하되, anchoring 위험을 한 번 안내한다

수정 후 재실행

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

dialog 관련 오류라면 실행 전 반드시 daemon 잔류 확인:

lsof -iTCP:9222 -sTCP:ESTABLISHED -n -P | awk '/node/{print $2}' | xargs kill -9 2>/dev/null

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

# CDP 연결 (1회)
agent-browser connect 9222

# 현재 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:

./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 참조

외부 서비스 전환

외부 사이트(Google, Gmail 등) 진입은 load + 2초 지연 + 직접 이동 fallback 패턴 사용. 상세: peach-e2e-browse/references/외부서비스-링크전환-패턴.md 참조

탭 선택 규칙

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

# 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로 실행
cd e2e && E2E_TAB_ID=<targetId> ./e2e.sh run '시나리오/대상.js'

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

단위 vs 통합 책임 경계

• 단위 시나리오 (peach-e2e-scenario): 한 화면/한 액션의 동작이 올바른지 검증. 자체 시작 데이터 준비, 독립 실행, 재활용 가능.
• 통합 suite (peach-e2e-suite): 여러 단위를 비즈니스 라이프사이클 단위로 조합해 사용자 흐름이 끝까지 가는지 검증. 단위 .js 수정 금지.

같은 흐름이 단위에서 반복되면 통합 suite 조합으로 표현한다.

단위 시나리오 작성 원칙

단위 시나리오는 suite에서 조합 가능한 재활용 부품이다. 다음 원칙을 따른다.

• 단일 책임: 한 화면 또는 한 비즈니스 액션만 검증한다. 두 개 이상의 핵심 흐름을 한 시나리오에 묶지 않는다.
• 시작 데이터 자체 준비: "기존 데이터가 있다고 가정"하지 않는다. 시나리오 자체가 필요한 시작 상태를 만든다(또는 명시적 입력으로 받는다).
• 독립 실행: 다른 시나리오 실행 결과에 의존하지 않는다. 어떤 순서로 실행해도 같은 결과를 낸다.
• 재활용 가능: suite에서 단위 .js를 수정 없이 그대로 사용할 수 있도록 작성한다. 외부에서 주입할 값이 있으면 명시적 입력(환경변수/state.json)으로 받는다.
• 실패 격리: 한 단위가 실패해도 다른 단위 실행에 영향을 주지 않는다. 정리(cleanup) 책임을 명시한다.

시나리오 설계 원칙

단위 분리 기준 (재사용 단위)

단위 시나리오는 다음 기준으로 나눈다.

• 다음 단계가 재사용할 상태를 남기는 업무 트랜잭션 단위로 분리한다.
• 예: 입력 완료, 처리 완료, 결과 확인. 다음 시나리오에 의미 있는 상태를 state.json 또는 환경변수로 남긴다.
• 클릭/입력 한 번 단위로 과도하게 분리하지 않는다.
• 로그인, 검색, 반복 클릭 같은 반복 기술 함수는 scenario가 아니라 helper로 분리한다.

저장 경로는 e2e/시나리오/{한글카테고리}/{NN}-{시나리오명}.js 형식을 따른다. 상세: peach-e2e-suite/references/suite-scenario-파일구조.md 참조

E2E_BASE 패턴 (도메인 환경변수)

모든 시나리오 파일 최상단에 E2E_BASE 환경변수 패턴을 사용한다. 도메인 하드코딩은 다중 환경 실행을 차단하는 안티패턴이다.

// 시나리오 파일 최상단 필수
const BASE = process.env.E2E_BASE || 'http://local.example.com';

실행 시:

# 로컬 (기본값)
./e2e.sh run --tab N 시나리오/경로.js

# 개발서버 지정
E2E_BASE=https://dev.example.com ./e2e.sh run --tab N 시나리오/경로.js

DB-free 설계 (역할 분리 원칙)

시나리오 .js 파일은 UI 조작과 UI 결과 검증만 담당한다. DB 접속 자체가 구조적으로 불가능하므로 시나리오 안에서는 읽기·쓰기 모두 시도하지 않는다.

• 구조적 제약: e2e.sh 실행 환경의 NODE_PATH에 mysql/postgres 클라이언트가 포함되지 않아 시나리오에서 DB 라이브러리(mysql, dbQuery 등) require 자체가 ENOENT로 실패한다. DB 접속 정보가 시나리오에 들어가면 환경 이식성도 0이 된다.
• 그래서 DB가 필요한 모든 동작은 시나리오 바깥(suite fixture Step, peach-db-query 스킬, 관리자 화면 액션, TDD API)으로 분리한다.
• 위 경계를 위반하는 시나리오 요청(예: "이 시나리오 안에서 INSERT 해서 사전조건 만들어줘")을 받으면 즉시 사용자에게 알리고, 아래 우회 경로 중 하나를 먼저 제안한 뒤 동의를 받는다.

| 목적 | 시나리오 안 시도 (불가) | 우회 경로 | |------|---------------------|---------| | PK 추출 | SELECT pk FROM table WHERE name='...' | 관리자 list DOM input.pk_check[request_name] 속성 | | 저장 검증 | SELECT column FROM table WHERE pk=N | 화면 reload 후 입력 요소 .value 확인 | | DB 사전조건 | INSERT INTO ... | suite fixture Step 또는 peach-db-query 스킬 | | 상태 강제 전환 | UPDATE ... SET status=... | suite fixture Step 또는 관리자 화면 액션을 시나리오에 추가 | | 잔존 데이터 정리 | DELETE FROM ... | suite fixture Step 또는 hardDelete TDD API 호출 | | DB 정합성 확인 | — | suite MD "DB 검증 (선택)" 섹션 + peach-db-query 스킬 (SELECT) |

PK 추출 표준 패턴

등록 후 PK를 관리자 list DOM에서 추출하는 표준 패턴:

await page.evaluate((name) => { $('#page_keyword').val(name); searchFormSubmit(); }, TEST_NAME);
await page.waitForTimeout(1500);
const N = await page.evaluate((name) => {
    const el = document.getElementById('list_inner_html') || document.body;
    const cb = el.querySelector(`input.pk_check[request_name="${name}"]`);
    return cb ? parseInt(cb.value, 10) : null;
}, TEST_NAME);
if (!N || N <= 0) throw new Error('PK 추출 실패');

전제: 관리자 list에 input.pk_check 체크박스가 있고, request_name 속성에 이름, value에 PK가 있어야 함.

핵심 원칙

• 항상 lib/connect.js의 connect() 함수 사용
• 실행은 반드시 node — bun은 CDP WebSocket 연결 불가
• 대상 프로젝트의 DOM 구조를 파악하고 적절한 셀렉터 전략 적용
• 모달 처리: 프레임워크별 패턴 참조 (iframe vs Portal/Teleport)
• dialog handler는 전역이 아닌 조건부 설치
• 외부 서비스 링크 전환은 click() 한 줄이 아닌 fallback 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 시나리오 |