e2e-agent-browser

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 "[email protected]"  # 텍스트 입력
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 "[email protected]"

# 비밀번호 입력
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