web-infra-dev/midscene

Midscene.js – 비전 기반 GUI 에이전트를 통한 E2E 테스트

개요 – 웹, 모바일, 데스크톱 애플리케이션을 위한 엔드투엔드(E2E) 테스트를 자연어로 작성할 수 있는 JavaScript 라이브러리입니다. 비전 모델을 사용하여 UI를 "보고", 스크린샷에서 요소를 찾고, 작업(클릭, 입력, 스크롤)을 수행하며 사용자가 실제로 보는 것을 검증합니다.

주요 개념

자연어 테스트 단계 – aiAct, aiWaitFor, aiAssert 호출(또는 YAML 케이스)을 작성하여 사용자 작업과 예상 결과를 설명합니다.
비전 기반 요소 찾기 – CSS 선택자나 DOM 쿼리가 필요 없습니다. 에이전트는 UI 요소를 외관으로 매칭하므로 캔버스 기반 컨트롤, 아이콘 전용 버튼, 교차 출처 iframe 등에서도 작동합니다.
크로스 플랫폼 API – 동일한 PlaywrightAgent, PuppeteerAgent 또는 일반 Agent를 웹 브라우저, Android/iOS 기기, HarmonyOS, 원격 데스크톱 세션에서 사용할 수 있습니다.
모델 비종속 및 저비용 – 다양한 멀티모달 LLM(Qwen‑VL, Gemini‑Flash, Doubao‑Seed, UI‑TARS 등)을 구성 가능한 가격으로 지원하며, 스크린샷 전용 입력으로 토큰 사용량을 절약합니다.
HTML 리포트 – 실행 후 스크린샷, 요소 위치, AI 결정, 어서션 결과를 포함한 시각적 리포트를 생성하여 디버깅을 용이하게 합니다.

사용 방법

Midscene Test 프로젝트를 생성(또는 기존 Playwright/Puppeteer 테스트에 Agent를 추가).
비전 모델을 구성(예: Qwen3.x 또는 gemini‑3.5‑flash).

단계를 작성(YAML 파일로):

cases:
  - name: $100 미만 헤드폰 찾기
    steps:
      - aiAct: 헤드폰을 검색하고 결과를 $100 미만 가격으로 필터링
      - aiWaitFor: 필터링된 검색 결과가 표시됨
      - aiAssert: 검색 결과에 제품이 있으며 각각 $100 미만임

또는 JavaScript로 직접:

await agent.aiAct('헤드폰을 검색하고 결과를 $100 미만 가격으로 필터링');
await agent.aiWaitFor('필터링된 검색 결과가 표시됨');
await agent.aiAssert('검색 결과에 제품이 있으며 각각 $100 미만임');

테스트 실행 – Midscene이 스크린샷을 캡처하고 모델에 전송하여 작업을 수행하고 인터랙티브 HTML 리포트를 생성합니다.

지원 플랫폼

플랫폼	통합
웹	Playwright, Puppeteer 또는 Chrome 브리지 모드
Android	ADB 제어 기기/에뮬레이터
iOS	WebDriverAgent 제어 기기/시뮬레이터
HarmonyOS	HDC 제어 기기
데스크톱(macOS/Windows/Linux)	원격 RDP 또는 네이티브 키보드/마우스 제어
사용자 정의 UI	스크린샷 및 액션 훅 제공

벤치마크 – AndroidWorld에서 93% 이상, MobileWorld에서 78% 이상, AppControlBench에서 96% 이상의 통과율이 보고되었으며, 전체 스위트에 대해 $1 미만의 모델 비용으로 정확성과 비용 효율성을 입증합니다.

시작하기

패키지 설치: npm i @midscene/web (또는 Playwright 특정 번들).
웹사이트의 빠른 시작 가이드 또는 Playground Chrome 확장 프로그램을 따라 코드 없이 테스트를 시도할 수 있습니다.
대규모 스위트의 경우 Midscene Test 프로젝트(@midscene/test)를 만들고 재사용 가능한 비즈니스 로직을 위한 사용자 정의 TypeScript 노드를 추가하세요.

커뮤니티 및 생태계

공식 문서: https://midscenejs.com
샘플 저장소: https://github.com/web-infra-dev/midscene-example
다른 언어(Python, Java 등)의 SDK는 커뮤니티에서 유지 관리합니다.
활발한 Discord, X, Lark 그룹이 지원합니다.

중요한 이유 – 기존 UI 테스트 프레임워크는 취약한 선택자와 DOM 지식에 의존합니다. Midscene은 접근 방식을 바꿉니다. AI가 인간처럼 UI를 "보기" 때문에 테스트는 UI 변경에 더 강력하며 코드만으로 어설션하기 어려운 시각적 측면(색상, 테두리, 캔버스 드로잉)을 테스트할 수 있습니다.

Midscene.js는 MIT 라이선스로 제공되며 스타와 기여를 환영합니다.

web-infra-dev/midscene

Midscene.js – 비전 기반 GUI 에이전트를 통한 E2E 테스트

관련