/e2e-agent-browser

name: e2e-agent-browser
description: >
  agent-browser CLI를 활용한 E2E 테스트 자동화. 스냅샷 기반 접근성 트리와 ref 시스템으로 안정적인 브라우저 테스트를 수행.
  트리거: "E2E", "브라우저 테스트", "agent-browser", "e2e 테스트 작성", "E2E 테스트", "브라우저 자동화"
  안티-트리거: "유닛 테스트", "API 테스트", "pytest", "Jest 테스트만", "Playwright 직접 사용"
user-invocable: false

E2E Testing with agent-browser

AI 에이전트를 위한 헤드리스 브라우저 자동화 CLI `agent-browser`를 활용하여 E2E 테스트를 작성하고 실행하는 종합 가이드입니다.

이 스킬을 사용할 때

• 웹 애플리케이션 E2E 테스트 작성
• 로그인/회원가입 플로우 테스트
• 폼 입력 및 제출 테스트
• 네비게이션 및 라우팅 테스트
• UI 상호작용 테스트 (클릭, 호버, 스크롤)
• 시각적 상태 확인 (요소 존재, 텍스트 내용)
• CI/CD 파이프라인에서 브라우저 테스트 실행

설치

# npm으로 설치 (권장)
npm install -g agent-browser

# Chromium 브라우저 다운로드
agent-browser setup

# Linux의 경우 시스템 의존성 추가 설치
agent-browser setup --with-deps

핵심 개념

1. 스냅샷 + Ref 워크플로우

agent-browser의 핵심은 **접근성 트리(Accessibility Tree)**와 **ref 시스템**입니다.

# 1. 페이지 열기
agent-browser open https://example.com

# 2. 접근성 스냅샷 가져오기 (ref 포함)
agent-browser snapshot -i
# 출력:
# - heading "Example Domain" [ref=e1] [level=1]
# - button "Submit" [ref=e2]
# - textbox "Email" [ref=e3]
# - link "Learn more" [ref=e4]

# 3. ref를 사용하여 요소와 상호작용
agent-browser click @e2        # 버튼 클릭
agent-browser fill @e3 "test@example.com"  # 텍스트 입력
agent-browser text @e1         # 텍스트 가져오기

2. 스냅샷 옵션

# 전체 접근성 트리
agent-browser snapshot

# 인터랙티브 요소만 (버튼, 입력, 링크)
agent-browser snapshot -i

# 컴팩트 모드 (빈 구조 요소 제거)
agent-browser snapshot -c

# 깊이 제한
agent-browser snapshot -d 3

# CSS 선택자로 범위 제한
agent-browser snapshot -s "#main"

# 옵션 조합
agent-browser snapshot -i -c -d 5

3. JSON 모드 (AI 에이전트용)

# JSON 출력으로 파싱 가능한 결과 반환
agent-browser snapshot --json
# {"success":true,"data":{"snapshot":"...","refs":{"e1":{"role":"heading","name":"Title"},...}}}

E2E 테스트 패턴

패턴 1: 기본 페이지 테스트

#!/bin/bash
# test_homepage.sh

set -e  # 에러 시 즉시 중단

# 페이지 열기
agent-browser open https://myapp.com

# 페이지 타이틀 확인
TITLE=$(agent-browser title)
if [[ "$TITLE" != "My App" ]]; then
  echo "FAIL: Expected title 'My App', got '$TITLE'"
  exit 1
fi

# 주요 요소 존재 확인
agent-browser snapshot -i | grep -q "button.*Login" || {
  echo "FAIL: Login button not found"
  exit 1
}

echo "PASS: Homepage test"
agent-browser close

패턴 2: 로그인 플로우 테스트

#!/bin/bash
# test_login.sh

set -e

# 로그인 페이지 열기
agent-browser open https://myapp.com/login

# 스냅샷으로 요소 ref 확인
agent-browser snapshot -i
# - textbox "Email" [ref=e1]
# - textbox "Password" [ref=e2]
# - button "Sign In" [ref=e3]

# 이메일 입력
agent-browser fill @e1 "test@example.com"

# 비밀번호 입력
agent-browser fill @e2 "password123"

# 로그인 버튼 클릭
agent-browser click @e3

# URL 변경 대기
agent-browser wait url "**/dashboard"

# 대시보드 확인
URL=$(agent-browser url)
if [[ "$URL" != *"dashboard"* ]]; then
  echo "FAIL: Not redirected to dashboard"
  exit 1
fi

echo "PASS: Login flow"
agent-browser close

패턴 3: 폼 입력 및 유효성 검사 테스트

#!/bin/bash
# test_form_validation.sh

set -e

agent-browser open https://myapp.com/register

# 스냅샷으로 폼 요소 확인
agent-browser snapshot -i

# 빈 폼 제출 시도
agent-browser click @submit-btn

# 에러 메시지 대기
agent-browser wait text "Email is required"

# 에러 메시지 확인
agent-browser snapshot -i | grep -q "Email is required" || {
  echo "FAIL: Validation error not shown"
  exit 1
}

# 유효한 이메일 입력
agent-browser fill @email "valid@example.com"

# 이메일 에러 메시지 사라짐 확인
agent-browser snapshot -i | grep -q "Email is required" && {
  echo "FAIL: Email error should be gone"
  exit 1
}

echo "PASS: Form validation"
agent-browser close

패턴 4: 네비게이션 테스트

#!/bin/bash
# test_navigation.sh

set -e

agent-browser open https://myapp.com

# 네비게이션 메뉴 클릭
agent-browser click role:link "About"
agent-browser wait url "**/about"

# 뒤로 가기
agent-browser back
agent-browser wait url "**/home"

# 앞으로 가기
agent-browser forward
agent-browser wait url "**/about"

echo "PASS: Navigation test"
agent-browser close

패턴 5: 모달/다이얼로그 테스트

#!/bin/bash
# test_modal.sh

set -e

agent-browser open https://myapp.com

# 모달 트리거 버튼 클릭
agent-browser click @open-modal-btn

# 모달 나타날 때까지 대기
agent-browser wait @modal-dialog

# 모달 내용 확인
agent-browser snapshot -s "[role=dialog]" -i

# 모달 닫기
agent-browser click @close-modal-btn

# 모달 사라짐 확인 (isvisible 사용)
VISIBLE=$(agent-browser isvisible @modal-dialog 2>/dev/null || echo "false")
if [[ "$VISIBLE" == "true" ]]; then
  echo "FAIL: Modal should be closed"
  exit 1
fi

echo "PASS: Modal test"
agent-browser close

패턴 6: 드래그 앤 드롭 테스트

#!/bin/bash
# test_dnd.sh

set -e

agent-browser open https://myapp.com/kanban

# 드래그 앤 드롭 실행
agent-browser drag @task-1 @column-done

# 결과 확인
agent-browser snapshot -s "#column-done" | grep -q "Task 1" || {
  echo "FAIL: Task not moved"
  exit 1
}

echo "PASS: Drag and drop test"
agent-browser close

패턴 7: 파일 업로드 테스트

#!/bin/bash
# test_upload.sh

set -e

agent-browser open https://myapp.com/upload

# 파일 업로드
agent-browser upload @file-input "./test-file.pdf"

# 업로드 완료 대기
agent-browser wait text "Upload complete"

echo "PASS: File upload test"
agent-browser close

고급 기능

인증 세션 유지

# 프로필 디렉토리로 로그인 상태 유지
agent-browser open https://myapp.com --profile ~/.browser-profile/myapp

# 환경 변수로 설정
export AGENT_BROWSER_PROFILE=~/.browser-profile/myapp
agent-browser open https://myapp.com

세션 분리

# 독립된 세션으로 병렬 테스트
AGENT_BROWSER_SESSION=test1 agent-browser open https://myapp.com &
AGENT_BROWSER_SESSION=test2 agent-browser open https://myapp.com &
wait

# 세션 목록 확인
agent-browser sessions

네트워크 인터셉트

# 특정 요청 차단
agent-browser block "*.png"
agent-browser block "*analytics*"

# API 응답 모킹
agent-browser mock "/api/users" '{"users": [{"id": 1, "name": "Test"}]}'

# 네트워크 요청 모니터링
agent-browser requests

스크린샷 및 PDF

# 현재 화면 스크린샷
agent-browser screenshot ./screenshot.png

# 전체 페이지 스크린샷
agent-browser screenshot ./full.png --full

# PDF로 저장
agent-browser pdf ./page.pdf

JavaScript 실행

# JS 코드 실행
agent-browser eval "document.title"