MigoXLab/webqa-agent

WebQA Agent가 마음에 드신다면, GitHub에서 ⭐를 눌러주세요!

🤖 WebQA Agent는 인간처럼 웹을 이해하는 완전 자동화된 웹 테스트 에이전트(agent)입니다. 테스트 케이스 생성부터 기능, 성능, UX(사용자 경험)를 엔드 투 엔드(end-to-end)로 평가합니다. ✨ GUI/CLI를 통해 직접 사용하거나, OpenClaw 스킬로 사용할 수 있습니다.

• 핵심 기능 (Core Features)
• 예시 (Examples)
• 빠른 시작 (Quick Start)
• CLI 사용법 (CLI Usage)
• WebQA Agent 도구 확장하기 (Extending WebQA Agent Tools)
• 배포 (Deployment)
• 로드맵 (RoadMap)
• 감사 (Acknowledgements)
• 라이선스 (License)

WebQA-Agent는 서로 다른 시나리오를 지원하기 위해 두 가지 테스트 모드인 **🤖 생성 모드 (Generate Mode)**와 **📋 실행 모드 (Run Mode)**를 제공합니다.

기능 (Capability)	🤖 생성 모드 (Generate Mode)	📋 실행 모드 (Run Mode)
핵심 기능 (Core Features)	AI 기반 탐색 -> 동적 생성 -> 정밀한 실행	지침 및 예상 검증 결과에 기반한 실행
사용 사례 (Use Cases)	새로운 기능, 종합적인 품질 보증 (QA)	반복 가능하고 회귀 테스트 (regression testing)가 필요한 시나리오
사용자 입력 (User Input)	최소한의 입력: URL 또는 한 문장의 비즈니스 목표	구조화된 입력: 간단한 자연어 단계 설명
장점 (Advantages)	성찰 기반 계획(Reflection-based planning), UI 변경에 대한 적응성; 종합적인 QA를 위한 기능/성능/보안/UX 평가 설정 가능	안정적이고 예측 가능한 결과; 셀렉터(selector) 유지보수 불필요; 실시간 콘솔(Console) 및 네트워크(Network) 모니터링

사용 및 배포 (Usage & Deployment): CLI 실행을 지원합니다 (CLI 사용법 참조). 또한 시각적 관리를 위한 웹 인터페이스와 함께 풀스택 배포(Local / Docker / K8s)를 지원합니다. 배포(Deployment) 섹션을 참조하세요.

기본 도구 (Default Tools) (항상 활성화됨):

UI 액션 (UI Actions): 브라우저 상호작용 (클릭, 타이핑, 탐색)
UI 어설션 (UI Assertions): 상태 검증
UX 검증 (UX Verification): 텍스트 오타 확인, 레이아웃 분석

커스텀 도구 (Custom Tools) (선택 사항, 설정 가능):

성능 (Performance): Lighthouse 기반 성능 테스트
보안 (Security): Nuclei 취약점 스캐닝
링크 탐지 (Link Detection): 동적 링크 탐색

config.yaml에서 커스텀 도구를 활성화할 수 있습니다:

test_config:
  custom_tools:
    enabled:
      ...

🛠️ CLI 빠른 시작 (CLI Quick Start) 또는 🖥️ 풀스택 배포 (Full-stack Deployment, 웹 대시보드) 중에서 선택하세요.

uv (Python>=3.11) 사용을 권장합니다:

# 1) 프로젝트 생성 및 설치
uv init my-webqa && cd my-webqa
uv add webqa-agent
...

CLI 사용법(CLI Usage)에서 더 자세한 CLI 관련 내용을 확인하세요.

시각적 대시보드(Visual Dashboard), 테스트 관리(Test Management) 및 히스토리(History)를 사용하려면 Docker Compose로 시작하세요:

git clone https://github.com/MigoXLab/webqa-agent.git
cd webqa-agent/deploy/docker-compose
cp .env.example .env
...

다음 주소로 접속하세요:

http://localhost

다른 배포 방법은 배포(Deployment) 섹션을 참조하세요.

WebQA Agent는 초기화(Initialization), 자율 탐색(Autonomous Exploration), 케이스 실행(Case Execution) 및 Web UI 실행을 위한 간결한 명령줄 인터페이스(CLI)를 제공합니다.

명령 (Command)	설명 (Description)	일반적인 인자 (Common Arguments)
init	설정 파일 초기화	-m <gen/run> : 모드 지정; -o <path> : 출력 경로; --force : 기존 파일 덮어쓰기
gen	생성 모드 (Generate Mode): AI 기반 테스트 생성 및 실행	-c <path> : 설정 경로; -w <n> : 병렬 워커 (Parallel Workers)
run	실행 모드 (Run Mode): YAML로 정의된 테스트 케이스 실행	-c <path/dir> : 설정 파일 또는 폴더; -w <n> : 병렬 워커 (Parallel Workers)

예시 (Examples):

# 실행(Run) 모드 설정 초기화
webqa-agent init -m run
# 4개의 병렬 워커로 디렉토리 내의 모든 케이스 실행
...

• 성능 테스트 (Lighthouse):
  npm install lighthouse chrome-launcher

(Node.js ≥18 필요) - 보안 테스트 (Nuclei):

brew install nuclei # macOS
nuclei -ut # 템플릿 업데이트
# Linux/Windows: https://github.com/projectdiscovery/nuclei/releases

설정 파일에는 테스트 유형을 정의하기 위해 test_config 필드가 반드시 포함되어야 합니다.

비즈니스 목표 (Business Objectives): AI 테스트의 초점과 커버리지(Coverage)를 안내하기 위한 비즈니스 목표를 지정합니다.
커스텀 도구 (Custom Tools): 성능 (Lighthouse), 보안 (Nuclei), 버튼 체크 및 링크 탐지(Link Detection)와 같은 선택적 도구입니다.
동적 단계 생성 (Dynamic Step Generation): 실행 중 새로운 UI 요소가 감지되면 추가 테스트 단계를 자동으로 생성합니다.
필터 모델 (Filter Model): 계획 효율성(Planning Efficiency)을 높이기 위해 페이지 요소를 사전 필터링하는 경량 모델을 구성합니다.

자세한 내용은 docs/MODES&CLI.md를 참조하십시오.

target:
url: https://example.com # 테스트할 웹사이트 URL
description: 웹사이트 QA 테스트
...

실행 모드(Run Mode) 설정에는 반드시 cases 필드가 포함되어야 합니다.

멀티모달 상호작용 (Multi-modal Interaction): action을 사용하여 페이지의 가시적인 텍스트, 이미지 또는 상대적 위치를 설명합니다. 지원되는 브라우저 액션(browser actions)에는 클릭(click), 호버(hover), 입력(input), 삭제(clear), 키보드 입력(keyboard input), 스크롤(scrolling), 마우스 이동(mouse movement), 파일 업로드(file upload), 드래그 앤 드롭(drag-and-drop), 대기(wait)가 포함되며, 페이지 액션(page actions)에는 탐색(navigation), 뒤로 가기(back)가 포함됩니다.

멀티모달 검증 (Multi-modal Verification): verify를 사용하여 에이전트가 경로를 이탈하지 않는지 확인하며, 시각적 콘텐츠, URL, 경로 및 이미지-요소 결합 조건을 검증합니다.

엔드 투 엔드 모니터링 (End-to-End Monitoring): Console 로그와 Network 요청 상태를 모니터링하며, 알려진 오류를 무시하기 위한 ignore_rules 설정을 지원합니다.

자세한 내용과 테스트 케이스 작성 사양은 docs/MODES&CLI.md를 참조하십시오.

target:
url: https://example.com # 대상 웹사이트 URL
llm_config: # LLM 설정
...

테스트 보고서는 reports/ 디렉토리에 생성됩니다. HTML 파일을 열어 상세 결과를 확인하십시오.

WebQA Agent는 도메인 특화 테스트 역량을 위한 **커스텀 도구 개발 (custom tool development)**을 지원합니다.

문서	설명
커스텀 도구 개발 (Custom Tool Development)	커스텀 도구 생성을 위한 빠른 참조
LLM 컨텍스트 문서 (LLM Context Document)	AI 보조 개발을 위한 종합 가이드 (vibe coding에 유용)

기여(contributions)를 환영합니다! 예시를 보려면 기존 도구들을 확인해 보세요.

테스트 관리, 예약된 작업 및 실행 이력을 갖춘 **지속적인 웹 대시보드 (persistent web dashboard)**가 필요한 팀은 풀스택 플랫폼을 배포하십시오:

방법	사용 사례	가이드
로컬 개발 (Local Development)	개인 개발 및 디버깅	deploy/README.md
...

💡 내부 로직 확장: WebQA Agent는 팀의 인프라(내부 SSO, OSS 객체 스토리지, 내부 LLM 통합 등)를 기반으로 내부 로직을 확장하는 것을 지원합니다. 필요에 맞게 자유롭게 커스터마이징하고 개발할 수 있습니다. deploy/README.md

참고: 웹 대시보드 플랫폼은 현재 중국어로만 제공됩니다.

• 상호작용 및 시각화 (Interaction & Visualization): 추론 과정 (reasoning processes)의 실시간 표시

• 생성 모드 확장 (Generate Mode Expansion): 추가적인 평가 차원 (evaluation dimensions)의 통합

• 도구 에이전트 컨텍스트 통합 (Tool Agent Context Integration): 더욱 포괄적이고 정밀한 실행

• natbot: GPT-3를 이용한 브라우저 제어

• Midscene.js: 웹, Android, 자동화 및 테스트를 위한 AI 오퍼레이터 (AI Operator)

• browser-use: 브라우저 제어를 위한 AI 에이전트 (AI Agent)

이 프로젝트는 Apache 2.0 라이선스 (Apache 2.0 License) 하에 배포됩니다.