Combining unit scenarios (.js) into business flow units, create integration test scenarios as mdand, by reading the md, sequential execution + step-by-step verification + code/DB verificationis handled as well.
The upper orchestration layer of peach-e2e-scenario (unit execution).
Mode
| Mode | Trigger | Action |
|---|---|---|
auto (default) |
/peach-e2e-suite [설명] |
Create + execute |
create |
/peach-e2e-suite create [설명] |
Create integration scenario md only |
run |
/peach-e2e-suite run [md 파일명] |
Read existing md and execute |
recheck |
/peach-e2e-suite recheck |
Detect source changes → re-execute only selected related scenarios |
Created file path
docs/e2e-suite/
└── {한글카테고리}/
└── {NN}-{스위트명}.md
예: 주문/01-주문-결제-검증.md
회원/01-회원가입-로그인-검증.md
공통검색/01-검색필터-자동검색.md
{한글카테고리}uses Korean folders based on general business domains.- File names are within category folders
NN-with a two-digit sequence number attached. - Sequence numbers are independent per category and not global sequence numbers.
- Existing flat-structure files are not immediately moved in bulk, but are gradually migrated to the new rules only at the point of modification/rewriting.
- When migrating, specify the existing path and new path in the completion report, and also update the executable file paths inside the suite md.
Details: references/suite-scenario-파일구조.md reference
Chrome Beta launch invariant rules
When launching Chrome Beta in CDP mode, the fixed profile option is mandatory. A launch missing the profile option is considered a session persistence failure.
- Allowed:
cd e2e && ./e2e.sh chrome - Mandatory option when running directly:
--remote-debugging-port=9222,--remote-allow-origins=*,--user-data-dir=$HOME/.chrome-beta-e2e-profile,--disable-extensions - macOS direct execution standard:
/usr/bin/open -na "Google Chrome Beta" --args ... - Forbidden:
open -a "Google Chrome Beta"standalone launch,--argswithoutopenexecution,--user-data-dirChrome Beta execution without , arbitrary use of other profile paths, bypassing with default Chrome or another browser
Workflow
Common: Environment check
cd e2e && ./e2e.sh setup
cd e2e && ./e2e.sh status
statusif ❌ Chrome CDP 미연결is shown, first attempt automatic recovery in the following order.
cd e2e && ./e2e.sh chrome &executionsleep 4waitcd e2e && ./e2e.sh statusrecheck- If still not connected, guide the user to run
cd e2e && ./e2e.sh chromemanually
./e2e.sh chromeis the standard path for launching Chrome Beta with the fixed profile ($HOME/.chrome-beta-e2e-profile). Even when launching Chrome directly instead of this command, do not omit the--user-data-diroption.
Show the tab list to the user and confirm the tab number.
For integration flows where Google/OAuth/admin/payment/existing Chrome Beta profile session persistence is key, proceed only up to md creation/analysis, and start actual Step execution after user approval.
Tab drift prevention: after responding with the tab number,
agent-browser tab Nimmediately afteragent-browser eval "document.title + ' | ' + location.href"re-verify with . If it differs from expectations,./e2e.sh statusre-output and reselect.
When including file upload Step: To block the OS native file dialog,
Page.setInterceptFileChooserDialogmethod is used. (Details:peach-e2e-browse/references/SPA-프레임워크-입력패턴.md §3)
create mode
- Identify request — Identify the target business flow from the user's natural language request
- Search unit scenarios — Check the existing scenario list
cd e2e && ./e2e.sh list ls e2e/시나리오/**/*.js - Analyze scenario code — Read related unit scenario .js files to understand behavior/input-output
- Pre-inspect DOM (if needed) — Check page structure with agent-browser eval
- Confirm information — Confirm with the user:
- Integrated scenario name (Korean, kebab-case)
- Save category folder (Korean business domain)
- Sequence number within category (
NN-) - List of unit scenarios to include + order
- Verification points for each step
- Code/DB verification items (if any)
- Create md —
references/suite-템플릿.mdWrite with reference to - Save —
docs/e2e-suite/{한글카테고리}/{NN}-{스위트명}.md- Auto-create category folder if it does not exist
- Report completion
run mode
- Initialize state.json (ensure clean execution)
rm -f e2e/.tmp/e2e_*_state.json - Select md file
User specifies a file, or selects from the list (show both category folders + flat structure)find docs/e2e-suite -type f -name "*.md" | sort - Parse md — Read frontmatter + scenario flow
- Check preconditions — Read the preconditions section of the md and check whether they are satisfied
- Confirm execution approval — For sensitive sessions/fixed profile maintenance flows, confirm user approval before executing actual Steps
- Sequential execution loop — For each Step:
a. Execute unit scenario:
cd e2e && ./e2e.sh run --tab N 시나리오/경로b. On failure: apply peach-e2e-scenario's auto-fix pattern (error parsing → DOM check → fix → rerun, up to 3 times) c. Check verification points: verify DOM/URL state with agent-browser eval d. Extract passed data: keep data needed for the next Step in context (e.g., orderId) e. Inject data: pass as environment variables when executing the next Step (E2E_ORDER_ID=xxx) - Code verification (if the md has a section) — Check the relevant file with Read/Grep
- DB verification (if the md has a section) — peach-db-query skill or direct SELECT execution
- Read (SELECT) only. INSERT/UPDATE/DELETE are fixtures, not verification, so separate them into a separate fixture Step.
- Post-execution registration summary — Read the state file (
e2e/.tmp/*.json)의registrations[]and output as a table. Organize the steps/names/PKs/times where registration occurred into one table and report to the user. If the state file does not exist orregistrationsis empty, display "no new registrations". - Report suite completion — Output in the standard format below (do not output the entire execution log)
✅ suite 완료 — {기능명} ({통과수}/{전체수})
| 시나리오 | 결과 | 비고 |
|---|---|---|
| {그룹명} 01~0N | ✅ 전체 통과 | |
| {그룹명} 0N | ✅ | 신규 PK={값} ({이름}) |
| {그룹명} 0N | ❌ | {실패 원인 1줄} |
AI 판단:
- 자동 수정: {있으면 "XX 수정 (N회)" / 없으면 "없음"}
- 잔여 이슈: {있으면 1줄 / 없으면 "없음"}
팀장 확인 필요: {있으면만 표시, 없으면 이 줄 생략}
recheck mode
After changing the program source, only the related scenarios are selectively re-run. Saves tokens and time compared to running the entire suite.
-
Detect changed files
git diff --name-only HEAD~1 HEAD -- src/ -
Select related scenarios
Changed file pattern Execution target lib/*/dao/All scenarios of the corresponding module lib/*/service/All scenarios of the corresponding module skin/.../insert.phpRegistered scenarios skin/.../update.phpModified scenarios controller/All scenarios related to the corresponding URL -
state.json initialization
rm -f e2e/.tmp/e2e_*_state.json -
Run only the selected scenarios sequentially (including the auto-fix loop)
-
suite completion report (standard format, specify excluded scenarios)
auto mode (default)
create → run executed consecutively. Run immediately after creation to verify.
Scope of AI autonomous handling
Clearly distinguish between what the AI decides and handles on its own and what requires user confirmation.
| Situation | AI autonomous handling | User confirmation required |
|---|---|---|
| Scenario execution | ✅ | |
| Error cause analysis | ✅ | |
| Scenario code modification (within 3 attempts) | ✅ | |
| Failure even after 3 modifications | ✅ | |
| Entire suite passed → completion report | ✅ | ✅ Feedback |
| Partial failure + auto-fix success → include modification details in the report | ✅ | ✅ Feedback |
| Commit·push | ✅ Always | |
| Create·delete scenario files | ✅ Always |
Per-step failure handling
| Situation | Handling |
|---|---|
| Unit scenario execution failure | Attempt the auto-fix loop 3 times (peach-e2e-scenario pattern) |
| Auto-fix failed 3 times | Stop at the corresponding Step, report failure |
| Verification point mismatch (suite md error) | Autonomously correct the suite md based on execution results → re-run |
| Passed data path error (suite md error) | After checking the actual DOM/URL, autonomously correct the suite md → re-run |
| Code/DB verification failure | Report the mismatch details, request user judgment |
Scope of autonomous suite md correction
AI can autonomously correct:
- Verification points (DOM selectors, URL patterns, expected values)
- Passed data extraction method
- Pre-injected environment variable names
User confirmation required:
- Change Step order
- Add·delete scenario files
- Change preconditions
When a Step fails, subsequent Steps are not executed (due to data dependency). A suite failure does not immediately repeat the entire suite. First reproduce/fix the unit scenario of the failed Step based on
peach-e2e-scenario runcriteria, then resume the suite after it passes.
Data passing method
Unit scenarios are independent processes (node) is executed, so memory cannot be shared.
Use the two methods according to the situation.
Method A: state.json file (multi-step scenario PK sharing — recommended)
// 01-등록 시나리오 마지막에 저장
const STATE_FILE = path.join(__dirname, '../../.tmp/e2e_{기능명}_state.json');
let state = {};
try { state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8')); } catch (_) {}
state.user = { {PK_FIELD}: N, name: TEST_NAME };
fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
// 02-수정 시나리오 시작에서 로드
let state = {};
try { state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8')); } catch (_) {}
const PK = state.user?.{PK_FIELD}
? String(state.user.{PK_FIELD})
: (process.env.E2E_PK || null); // 단독 실행 fallback
if (!PK) throw new Error('state.json 없음. 01-등록 시나리오를 먼저 실행하세요.');
e2e/.gitignore에.tmp/Must be added. Automatically initialized before run mode starts.
Method B: Environment variable injection (simple value passing)
# Step 1에서 orderId 추출
agent-browser eval "location.pathname.split('/').pop()"
# → orderId = "12345"
# Step 2에 주입
cd e2e && E2E_ORDER_ID=12345 ./e2e.sh run --tab 0 시나리오/주문/02-결제.js
In the unit scenario .js code,
process.env.E2E_ORDER_IDcan be accessed via .
md structure
references/suite-템플릿.md Refer to.
frontmatter
---
name: 주문-결제-검증
module: {PROJECT}
created: 2026-04-14
---
Body structure
# {통합 시나리오 이름}
## 사전조건
- Chrome Beta CDP 연결, 로그인 완료
- {필요한 데이터/상태}
- 탭: {시작 페이지}
## 시나리오 흐름
### Step 1: {단계명}
- 실행: `시나리오/{한글카테고리}/{NN}-{시나리오명}.js`
- 검증:
- {DOM/URL 검증 포인트}
- 전달 데이터: `{변수명}` ({추출 방법})
### Step 2: {단계명}
- 실행: `시나리오/{한글카테고리}/{NN}-{시나리오명}.js`
- 사전 주입: `E2E_{변수명}=${값}`
- 검증:
- {검증 포인트}
### Step N: 결과 검증
- 실행: 없음 (AI가 직접 확인)
- DB 검증: `{SQL}` → {기대값}
- 코드 검증: `{파일경로}` — {확인할 로직}
## 최종 통합 기준
- {전체 통과 조건}
## 실행 이력
| 일시 | 결과 | 비고 |
|------|------|------|
Domain configuration pattern (E2E_BASE)
When running the scenario, E2E_BASE specify the domain via an environment variable. If unspecified, the default value in the scenario file is used.
# 로컬 (기본값)
./e2e.sh run --tab N 시나리오/경로.js
# 개발서버 지정
E2E_BASE=https://dev.example.com ./e2e.sh run --tab N 시나리오/경로.js
In the suite MD, place a "Domain Configuration" section summarizing the two environment execution methods in a table (references/suite-템플릿.md .
Unit vs integration responsibility boundary
- Unit scenario (peach-e2e-scenario): Verifies that the behavior of one screen/one action is correct. Prepares its own starting data, runs independently, and is reusable.
- Integration suite (peach-e2e-suite): Combines multiple units into business lifecycle units to verify that the user flow runs to completion. Do not modify unit .js.
If the same flow repeats at the unit level, express it as an integration suite combination.
Principles for reusing unit scenarios
A suite is an integration document that combines unit scenarios. Unit scenarios are reuse targets.
- While writing a suite, do not modify unit .js. If a defect is found in a unit, send it back to
peach-e2e-scenario. - The suite defines only the unit scenario's order, data passing, and verification point combination.
- The same unit must be usable in multiple suites. Do not create units exclusively for a suite.
- Creating new or changing the structure of a unit .js always goes through
peach-e2e-scenario.
During the auto-fix loop (3 times), supplements that do not break reusabilitysuch as correcting the selector/wait pattern of a unit .js are allowed. However, changes that alter the unit's scope of responsibility (flow splitting/merging, changing starting state assumptions) must always be sent back to
peach-e2e-scenario.
Responsibility boundary between TDD and E2E
A suite is a layer that assembles business flow unit verification. Enforce the following separation principles.
- Unit scenario (.js): Handles only UI manipulation and UI result verification. DB reading and writing are both prohibited(the scenario execution environment has no DB client, so require itself is ENOENT). If DB consistency verification is needed, perform it only in the DB verification step of the suite md or in the
peach-db-queryskill. - DB preconditions/seed data: suite md의 fixture Stepshould be separated out. Never place them inside a unit scenario.
- Restart/session reset: Separate it into a distinct Step in the suite md. Do not handle it inside a unit scenario.
- Logic unit verification: Handle it in backend/store TDD, not in the suite (
peach-gen-backend/peach-gen-storereference). Do not try to cover all logic branch cases with the suite.
If a violation case is found (DB read/write inside a scenario, restart within a scenario), notify the user and first propose separating the fixture/Step.
Core principles
- Creating new unit scenario .js files and changing their structure go through peach-e2e-scenario. The suite performs .js supplementation through combination definition + execution + auto-fix loop (3 times).
- Execution must be
e2e.sh runthrough — directlynodecalling prohibited - Describe verification points in natural language — AI interprets them and confirms with agent-browser eval
- If a Step fails, do not execute subsequent Steps (data dependency)
- Check execution history in git log. The suite md file contains only scenario definitions and is not changed by execution results.
Tool role division
| Purpose | Tool |
|---|---|
| Unit scenario execution | ./e2e.sh run |
| Verification point confirmation | agent-browser eval |
| Code verification | Read, Grep |
| DB verification | peach-db-query or direct SELECT |
| iframe verification | ./e2e/pwc.sh eval (fallback) |
Reference documents
| Document | Purpose | Load condition |
|---|---|---|
references/suite-템플릿.md |
md creation template | create, auto |
references/suite-scenario-파일구조.md |
Category/sequence folder rules, gradual migration policy | create, auto |
Guidance after completion
통합 시나리오가 완료되었습니다.
📄 파일: docs/e2e-suite/{한글카테고리}/{NN}-{스위트명}.md
**관련 스킬:**
- `/peach-e2e-scenario` — 단위 시나리오 생성/실행/자동수정
- `/peach-e2e-browse` — DOM 탐색/디버깅
- `/peach-e2e-suite run {파일명}` — 이 통합 시나리오 재실행