VibeCheck

VibeCheck 웹 테스터

이 프로젝트는 GitHub Copilot, Cursor, Roo Code 등과 같은 AI 코딩 어시스턴트를 사용하는 개발자를 위해 웹 테스트 워크플로를 간소화하도록 설계된 AI 기반 에이전트를 제공합니다. 이 에이전트는 MCP(머신 명령 프로토콜) 를 통해 이러한 어시스턴트에 직접 통합되므로 자연어 프롬프트를 사용하여 테스트 기록, 실행 및 검색을 자동화할 수 있습니다.

문제점: AI 어시스턴트로 코드를 생성한 후 웹 애플리케이션을 수동으로 테스트하는 것은 시간이 많이 걸리고 오류가 발생하기 쉽습니다. 더욱이, AI 기반 코드 변경으로 인해 이전에 작동하던 기능에 의도치 않게 회귀가 발생할 수 있습니다.

솔루션: 이 도구는 AI 코딩 어시스턴트가 다음을 수행할 수 있도록 하여 격차를 메웁니다.

1. 새로운 테스트 흐름 기록: 자연어로 사용자 여정을 설명하면, 에이전트는 AI의 안내에 따라 브라우저(Playwright 사용)와 상호 작용하여 재현 가능한 테스트 스크립트(JSON 형식)를 생성합니다.
2. 기존 테스트 실행: 이전에 기록된 테스트 스크립트를 실행하여 회귀 테스트를 수행하고, 새로운 코드 변경으로 인해 기존 기능이 손상되지 않았는지 확인합니다.
3. 잠재적인 테스트 단계를 찾아보세요. 웹사이트를 크롤링하고, 비전과 DOM 구조를 사용하여 페이지를 분석하고, LLM에게 다양한 페이지에 대한 관련 테스트 단계를 제안해 달라고 요청하세요.

이를 통해 피드백 루프가 더욱 긴밀해지고, 테스트 프로세스가 자동화되며, AI 도우미(및 개발자)가 문제나 회귀를 신속하게 식별하여 수정할 수 있습니다.

데모 (클릭하여 이 동영상을 재생하세요)

특징

• MCP 통합: Cursor/Windsurf/Github Copilot/Roo Code와 완벽하게 통합됩니다.
• AI 지원 테스트 녹화: 자연어 설명으로부터 Playwright 기반 테스트 스크립트를 생성합니다(자동 모드).
• 결정론적 테스트 실행: Playwright를 사용하여 기록된 JSON 테스트 파일을 안정적으로 실행합니다.
• AI 기반 테스트 검색: 웹사이트를 크롤링하고 모든 LLM(OpenAI 호환 형식)을 활용하여 검색된 페이지에 대한 테스트 단계를 제안합니다.
• 회귀 테스트: 기존 테스트 모음을 쉽게 실행하여 회귀를 포착합니다.
• 자동 피드백 루프: 실행 결과(실패, 스크린샷, 콘솔 로그 포함)가 반환되어 AI 도우미에게 직접적인 피드백을 제공합니다.
• 자가 복구: 코드 변경 시 기존 테스트가 자가 복구되므로 수동으로 업데이트할 필요가 없습니다.
• UI 테스트: Playwright에서 직접 지원하지 않는 UI 테스트도 지원됩니다. 예를 들어, Check if the text is overflowing in the div .
• 시각적 회귀 테스트 : 전통적인 픽셀 매칭과 비전 LLM 접근 방식을 사용합니다.

작동 원리

지엑스피1

1. 사용자: AI 코딩 어시스턴트에게 메시지를 표시합니다(예: "로그인 흐름에 대한 테스트를 기록하세요", "회귀 테스트 'test_login.json'을 실행하세요").
2. AI 코딩 에이전트: 의도를 인식하고 MCP를 사용하여 MCP Server 에서 제공하는 적절한 도구를 호출합니다.
3. MCP 서버: 요청을 해당 함수( record_test_flow , run_regression_test , discover_test_flows , list_recorded_tests )로 라우팅합니다.
4. 웹 테스트 에이전트:
   • 녹음: WebAgent (자동 모드)는 LLM과 상호 작용하여 단계를 계획하고, BrowserController (Playwright)를 통해 브라우저를 제어하고, HTML/Vision을 처리하고, 결과 테스트 단계를 output/ 디렉토리의 JSON 파일에 저장합니다.
   • 실행: TestExecutor 지정된 JSON 테스트 파일을 로드하고, BrowserController 사용하여 기록된 단계에 따라 브라우저와 상호 작용하고, 결과, 스크린샷 및 콘솔 로그를 캡처합니다.
   • 발견: CrawlerAgent``BrowserController 와 LLMClient 사용하여 페이지를 크롤링하고 테스트 단계를 제안합니다.
5. 브라우저: Playwright는 실제 브라우저 상호작용을 주도합니다.
6. 피드백: 결과(성공/실패, 파일 경로, 오류 메시지, 발견된 단계)는 MCP 서버를 통해 AI 코딩 어시스턴트로 반환되고, 이후 사용자에게 표시됩니다.

시작하기

필수 조건

• 파이썬 3.10+
• 모든 LLM에 액세스 가능(테스트 결과 Gemini 2.0 플래시가 무료로 가장 잘 작동함)
• MCP 설치됨( pip install mcp[cli] )
• Playwright 브라우저 설치됨( playwright install )

설치

1. 저장소를 복제합니다.
   git clone <repository-url> cd <repository-name>
2. 가상 환경을 만듭니다(권장):
   python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows
3. 종속성 설치:
   pip install -r requirements.txt
4. Playwright 브라우저 설치:
   playwright install --with-deps # Installs browsers and OS dependencies

구성

1. 프로젝트 루트 디렉토리에서 .env.example 파일의 이름을 .env로 바꿉니다.
2. LLM API 키와 기타 필요한 세부 정보를 추가하세요.
   # .env LLM_API_KEY="YOUR_LLM_API_KEY"
   • YOUR_LLM_API_KEY 실제 키로 바꾸세요.

MCP 서버 추가

mcp 설정에 다음을 추가하세요:

AI 코딩 어시스턴트와 상호 작용하는 동안 이 서버를 계속 실행하세요.

용법

자연어를 사용하는 MCP 지원 AI 코딩 도우미를 통해 에이전트와 상호 작용하세요.

예:

• 테스트 기록:

  "테스트 녹화: https://practicetestautomation.com/practice-test-login/ 으로 가서 사용자 이름 필드에 'student'를 입력하고, 비밀번호 필드에 'Password123'을 입력하고, 제출 버튼을 클릭하고 'Congratulations student'라는 텍스트가 보이는지 확인하세요."

  • (에이전트는 이러한 작업을 자동으로 수행하고 output/ 에 test_....json 파일을 저장합니다.)
• 테스트 실행:

  "회귀 테스트 output/test_practice_test_login_20231105_103000.json 실행하세요"

  • (에이전트는 지정된 파일의 단계를 실행하고 오류와 세부 정보와 함께 PASS/FAIL 상태를 보고합니다.)
• 테스트 단계 알아보기:

  " https://practicetestautomation.com/practice/ 에서 잠재적인 테스트 단계를 찾아보세요."

  • (에이전트는 사이트를 크롤링하고, 페이지를 분석하고, 각 페이지에 대한 테스트 단계를 제안합니다.)
• 녹화된 테스트 목록:

  "사용 가능한 녹화된 웹 테스트를 나열하세요."

  • (에이전트는 output/ 디렉토리에서 발견된 .json 파일 목록을 반환합니다.)

산출:

• 기록된 테스트: output/ 디렉토리에 JSON 파일로 저장됩니다(형식은 test_schema.md 참조).
• 실행 결과: 실행 결과(상태, 오류, 증거 경로)를 요약한 JSON 객체로 반환됩니다. 전체 결과는 output/execution_result_....json 에도 저장됩니다.
• 검색 결과: 검색된 URL과 제안된 단계를 JSON 객체로 반환합니다. 전체 결과는 output/discovery_results_....json 에 저장됩니다.

영감

• 브라우저 사용 : DOM 컨텍스트 트리 생성은 이들로부터 많은 영감을 받았으며, 정적/동적/시각적 요소를 수용하도록 수정되었습니다. 오픈 소스 기여에 특별히 감사드립니다.

기여하다

기여를 환영합니다! 시작 방법, 문제 보고, 풀 리퀘스트 제출 방법에 대한 자세한 내용은 CONTRIBUTING.md를 참조하세요.

특허

이 프로젝트는 APACHE-2.0 라이선스를 받았습니다.