peach-e2e-setup

peach-e2e-setup — E2E test environment setup

Set up E2E test infrastructure in the target project. Check npm global tool installation, verify the presence of Chrome Beta, and deploy infrastructure code to the e2e/ folder.

Persona

E2E environment setup expert. Check that global tools and Chrome Beta are ready, and copy infrastructure code into the project. Never touch existing scenario folders.

---

Prerequisites

• Target project rootrun from (the target project, not peach-harness itself)
• macOS or Windows environment (Windows requires Git Bash)

---

Workflow

Step 1: Check npm global tool installation

Check whether the following 3 tools are installed:

# agent-browser (탐색/검증/확인용 기본 도구)
command -v agent-browser && echo "✅ agent-browser 설치됨" || echo "❌ agent-browser 미설치"

# playwright-cli (시나리오 실행 + iframe fallback용)
command -v playwright-cli && echo "✅ playwright-cli 설치됨" || echo "❌ playwright-cli 미설치"

# playwright-core (CDP 연결 라이브러리)
node -e "require('playwright-core')" 2>/dev/null && echo "✅ playwright-core 설치됨" || echo "❌ playwright-core 미설치"

If any tool is not installed, guide the user:

• agent-browser: npm install -g agent-browser
• playwright-cli: npm install -g @playwright/cli
• playwright-core: npm install -g playwright-core
• Install all at once: npm install -g agent-browser @playwright/cli playwright-core

Do not install automatically. Guide the user with the command and get confirmation.

Step 2: Check whether Chrome Beta is installed

The path differs depending on the OS:

macOS:

ls -d "/Applications/Google Chrome Beta.app" 2>/dev/null && echo "✅ Chrome Beta 설치됨" || echo "❌ Chrome Beta 미설치"

Windows (Git Bash):

[ -f "/c/Program Files/Google/Chrome Beta/Application/chrome.exe" ] && echo "✅ Chrome Beta 설치됨" || echo "❌ Chrome Beta 미설치"

If not installed, guide:

• Install URL: https://www.google.com/chrome/beta/
• Can run simultaneously with regular Chrome, used separately for E2E only

Note: e2e.sh는 uname -sautomatically detects the OS and branches the Chrome path. You do not need to hardcode the path directly. Strict rule: Chrome Beta must be run with the $HOME/.chrome-beta-e2e-profile fixed profile. A run missing the profile option is considered a session persistence failure. Afterward, the AI continues work by inheriting the same profile session, and if authentication is needed again, the user completes login/authentication directly in that profile.

Step 3: Create the e2e/ folder in the project root

mkdir -p e2e/lib

Step 4: Copy infrastructure code

references/ Copy the 4 infrastructure code files from the e2e/folder to

Source (references/)	Target (e2e/)
e2e.sh	e2e/e2e.sh
pwc.sh	e2e/pwc.sh
connect.js	e2e/lib/connect.js
selector.js	e2e/lib/selector.js
gmail-메일목록.js	e2e/시나리오/gmail-메일목록.js (first time only, only when absent)

Read the references file with the Read tool, then write it to the target path with the Write tool. Always overwrite infrastructure files with the latest version (overwrite even if the file already exists).

Step 5: Create scenario folder + deploy test scenarios

# 시나리오 폴더가 없을 때만 생성. 있으면 절대 건드리지 않음.
if [ ! -d "e2e/시나리오" ]; then
  mkdir -p "e2e/시나리오"
  echo "✅ e2e/시나리오/ 폴더 생성됨"
else
  echo "✅ e2e/시나리오/ 폴더 이미 존재 (건드리지 않음)"
fi

Deploy test scenarios (for operation verification during initial setup):

• references/gmail-메일목록.js → e2e/시나리오/gmail-메일목록.js
• If absent, always copy (initial installation)
• If present, compare contents and ask the user whether to update only if different

Processing order:

1. If the file is absent → always copy, no questions
2. If the file is present → compare with references contents
   • If identical → output "up to date" message and skip
   • If different → show a change summary and ask "Do you want to update? (y/N)"
     • y → overwrite
     • N (default) → skip

파일 없음          → 복사 (질문 없음)
파일 있음 + 동일   → "✅ gmail-메일목록.js 최신 상태"
파일 있음 + 다름   → diff 요약 출력 → "업데이트하시겠습니까? (y/N)"
                      y → 덮어씀 / N → 스킵

For comparison, read both files with the Read tool and check whether the contents are identical. The diff summary briefly explains the key changed parts (such as how many lines changed).

Step 6: Grant execution permissions

chmod +x e2e/e2e.sh e2e/pwc.sh

Step 7: Completion message

Output a summary of the setup results:

✅ E2E 환경 설정 완료

배포된 인프라 코드:
  e2e/e2e.sh        — E2E 통합 CLI
  e2e/pwc.sh        — playwright-cli CDP 래퍼
  e2e/lib/connect.js — Chrome CDP 연결 모듈
  e2e/lib/selector.js — 탭/시나리오 선택기

다음 단계:
  1. cd e2e && ./e2e.sh setup    — 환경 자동 체크 + 설정
  2. cd e2e && ./e2e.sh chrome   — Chrome Beta CDP 모드 실행 (고정 프로필 필수)
  3. Chrome Beta 고정 프로필에서 Google 로그인/필요한 인증 완료
  4. cd e2e && ./e2e.sh run 시나리오/gmail-메일목록.js  — 테스트 시나리오 실행

---

Precautions

• Protect scenario folders: e2e/시나리오/ If the folder already exists, never overwrite or delete it
• Infrastructure files are always overwritten: e2e.sh, pwc.sh, connect.js, selector.jsis always replaced with the latest version from references
• Do not auto-install global tools: Guide the user through the commands and proceed after getting confirmation
• Chrome Beta fixed profile required: ./e2e.sh chromeas the standard execution path, and when running directly, --user-data-dir=$HOME/.chrome-beta-e2e-profileis not omitted
• Scenario execution must use ./e2e.sh run: node 시나리오.js When running directly, playwright-corenot found. e2e.sh가 NODE_PATHYou must set the global npm module path for it to work properly
• Check for resident daemons before manual dialog verification: agent-browser connect 9222 The resident daemon created when running can automatically close native alert/confirm. If manual verification is needed, lsof -iTCP:9222 -sTCP:ESTABLISHED -n -Pcheck and then terminate. Details: peach-e2e-browse/references/native-dialog-주의사항.md
• targetId Tab pinning execution based on: When you need to specify an exact tab, use --tab N instead of E2E_TAB_ID environment variable. Details: peach-e2e-browse/references/탭-선택-패턴.md
• Authentication is handled directly by the user: Login, two-factor authentication, and security verification are completed directly by the user in the Chrome Beta fixed profile. AI only takes over completed sessions.

---

Completion criteria checklist

• Installation status of 3 npm global tools confirmed (agent-browser, playwright-cli, playwright-core)
• Chrome Beta installation status confirmed
• e2e/ folder structure created
• 4 infrastructure code files copied (e2e.sh, pwc.sh, connect.js, selector.js)
• e2e/scenario/ folder created (unchanged if it already exists)
• Test scenario gmail-mail-list.js deployed (copied if absent, updated after user confirmation if present and different)
• Execution permissions granted for e2e.sh and pwc.sh
• Completion message output
• Instructions provided for checking resident daemons before manual dialog verification