Community코딩 & 개발github.com

visual-verify

실제 헤드리스 브라우저(Playwright: Chromium, iPhone용 WebKit; Docker 설치 시 Playwright Docker 이미지 사용)를 구동하여 실행 중인 웹 앱의 스크린샷을 찍고 결과를 확인하거나, 시각적 변경 사항에 대해 BEFORE/AFTER 합성 이미지를 생성합니다.

visual-verify란 무엇인가요?

이 스킬은 개발자가 웹 애플리케이션의 시각적 상태를 실제 헤드리스 브라우저를 통해 확인할 수 있도록 지원합니다. Playwright 라이브러리를 Node.js 스크립트로 구동하며, MCP 도구 없이 독립적으로 작동합니다. 사용자는 'Verify' 모드로 현재 UI의 스크린샷을 찍어 렌더링 상태를 직접 확인하거나, 'Before/After' 모드로 시각적 변경 전후를 나란히 비교하는 합성 이미지를 얻을 수 있습니다. 또한 iOS/Android 터치 환경을 에뮬레이션하여 터치 대상 크기 감사, 탭, 드래그 등의 모바일 상호작용을 테스트하는 'Touch' 모드를 제공합니다. 스크립트는 Docker 컨테이너 또는 로컬 설치 브라우저 바이너리를 통해 실행되며, 사용자가 선택한 기기 뷰포트에 맞춰 반응형 버그를 재현하고 검증하는 데 특화되어 있습니다. 캡처된 모든 이미지는 AI가 직접 읽고 판단하여 결과를 보고하므로, 단순한 스크린샷 제공이 아닌 검증된 판단을 전달합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/conorjwryan/skills/tree/main/visual-verify

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

미리보기

스킬 README에서

caption

문서

Visual verify

버전: 1.1.0. 1.0.0 이전 버전은 이 저장소에서 추적되지 않습니다.

헤드리스 브라우저에서 실제 실행 중인 앱을 보고, 본 내용을 정직하게 보고합니다. 두 가지 모드:

  • Verify (기본) — 현재 상태의 스크린샷 하나(또는 여러 개)를 캡처하고 직접 읽어서 특정 기능이 렌더링되는지, 수정 사항이 적용되었는지, 특정 너비에서 레이아웃이 올바른지 확인합니다.
  • Before/after — 시각적 변경 사항에 대해 변경 전후를 전환하여 라벨이 붙은 나란히 BEFORE/AFTER 합성 이미지를 생성합니다.
  • Touch (iOS / Android) — 휴대폰을 에뮬레이션하고, 손가락으로 탭하고 드래그하며, 터치 대상 크기를 감사합니다. 아래 모바일 터치 확인을 참조하세요.

사용자의 요청에 따라 모드를 선택하세요. "이게 제대로 보이나요 / 작동하나요 / 휴대폰 너비로 보여주세요" → verify. "전후 비교 / 이게 시각적으로 고쳐졌나요" → before/after.

사용자가 요청하면 실행하세요

사용자가 무언가를 시각적으로 확인해달라고 요청하면 (또는 스크린샷 / 어떻게 보이는지 확인), 그 요청 자체가 허가입니다. 직접 전체 확인을 실행하세요: 캡처, 이미지 읽기, 제대로 되었는지 명확히 진술. 제안만 하고 멈추지 마세요.

모든 변경 후 스스로의 주도로 무단 실행하지 마세요. 브라우저를 구동하고 이미지를 읽어 토큰을 소모합니다. 요청되지 않은 시각적 변경 후에는 제안할 수 있으며 ("전후 합성 이미지를 원하시나요 — 모바일, 데스크톱, 또는 둘 다?"), 사용자가 결정하도록 하세요.

매번 확인한 내용을 보여주세요

사용자가 파일을 열지 않고도 결과를 볼 수 있어야 합니다. 확인한 내용을 보고하는 답변에서 확인한 모든 기능에 대한 after 이미지를 보여주세요 — 기능당 하나의 이미지, 즉 세 가지를 확인했다면 최소 세 개의 이미지입니다. 각 이미지 옆에 한 줄 캡션으로 무엇을 보여주는지와 올바른지 여부를 명시하세요 (예: "삭제 확인, 휴대폰 너비 — Cancel에 포커스").

  • Markdown과 절대 경로를 사용하여 이미지를 인라인으로 표시하세요. ![caption](/abs/path/to/image.png) 형식으로 클라이언트가 렌더링합니다. 그렇지 않으면 첨부하세요 (예: SendUserFile). 항상 경로도 함께 제공하세요.
  • 가장 선명한 샷을 선택하세요: 전체 페이지에서 기능이 묻힐 경우 자르거나 클립하세요.
  • before/after의 경우 합성 이미지를 보여주세요.
  • 시스템 UI, 안전 영역 등 정직하게 보여줄 수 없는 경우 오해의 소지가 있는 이미지 대신 그 사실을 말하세요.

항상 캡처한 내용을 확인하세요

스크린샷이 최종 결과물이 아닙니다. 검증된 판단이 중요합니다. 보고하기 전에, 그리고 합성 이미지를 보내기 전에 캡처한 모든 이미지를 읽어서 실제로 주장하는 내용이 보이는지 확인하세요. 예상과 다르면 조사하세요. 읽지 않은 샷으로 성공을 보고하지 마세요.

올바른 뷰포트 선택 — 중요합니다

반응형 버그는 종종 특정 너비에서만 재현됩니다. 사용자의 기기에 맞추세요. 사용자가 스크린샷을 보냈다면 CSS 너비를 유도하세요:

css_width = screenshot_pixel_width / devicePixelRatio

최신 iPhone은 DPR 3입니다 (예: 1320px 너비 스크린샷 ⇒ 440 CSS px; Pro Max 클래스). 일반적인 Android는 DPR ~2.6–3입니다. 확실하지 않으면 여러 너비(예: 320, 360, 390, 440)를 스위핑하세요 — 스크린샷 스크립트가 이 작업을 저렴하게 만듭니다. 터치/모바일 에뮬레이션을 위해 --mobile을 전달하세요. 모든 너비에 적용되는 일반적인 디자인 변경의 경우 데스크톱과 모바일 모두 확인하세요.

스크립트 (Bash로 실행; MCP 없음)

browser_* / Playwright MCP 도구를 찾지 마세요 — 설치되어 있지 않습니다. 모든 것은 일반 Node 스크립트를 통해 실행됩니다. 이 설치된 SKILL.md가 포함된 절대 디렉토리를 확인한 다음, 셸에서 VISUAL_VERIFY_DIR을 해당 디렉토리로 설정하세요. 이는 프로젝트 설치 또는 전역 설치일 수 있습니다. 하드코딩된 전역 경로가 아닌, 현재 읽고 있는 지침의 복사본을 사용하세요. 작업 디렉토리는 앱 프로젝트 루트로 유지하세요. 각 셸 명령에서 이 변수를 재사용하세요 (또는 셸 상태가 유지되지 않는 경우 다시 설정하세요):

VISUAL_VERIFY_DIR="/절대/경로/설치된/visual-verify"

번들된 스크립트:

"$VISUAL_VERIFY_DIR/scripts/screenshot.mjs"   # URL 캡처 → png
"$VISUAL_VERIFY_DIR/scripts/composite.mjs"     # 두 png → 라벨이 붙은 before/after
"$VISUAL_VERIFY_DIR/scripts/touch.mjs"         # 휴대폰 터치: 탭, 드래그, 대상 감사

런타임 및 브라우저 설정. 이 스킬은 정확한 Playwright 종속성과 잠금 파일을 소유합니다. 전역 또는 프로젝트 Playwright 패키지를 확인하지 않습니다. 스킬을 설치하거나 업데이트한 후 명시적으로 설치 프로그램을 실행하세요. 일반 확인은 패키지, 이미지 또는 브라우저를 다운로드하지 않습니다. Node.js 20+, npm 및 Bash를 사용하세요. 이 스킬을 위해 호스트 시스템 패키지를 설치하지 마세요.

브라우저가 실행되는 위치. Docker를 사용할 수 있는 경우, 각 실행은 정확히 일치하는 이미 설치된 Playwright 이미지에서 자체 컨테이너를 시작합니다. Docker는 고유한 루프백 포트를 할당합니다. 헬퍼는 컨테이너 ID를 확인하고 해당 엔드포인트에 연결합니다. 설치된 Node 종속성은 읽기 전용으로 마운트되므로 서버에 패키지 다운로드가 필요하지 않습니다. Playwright는 루프백 요청을 클라이언트로 전달하여 호스트 네트워킹 없이 로컬 앱 URL을 허용합니다. 정상 종료, 시작 실패 및 처리된 종료 시 해당 실행의 컨테이너만 정리합니다. 강제 종료 또는 호스트 충돌은 라벨이 붙은 컨테이너를 남길 수 있습니다. 명시적 정리 전에 소유권을 검사하세요. 기존 컨테이너를 교체하거나 중지하지 않습니다. Docker Desktop/macOS 네트워킹은 여전히 별도의 검증이 필요합니다. Linux 확인 결과를 주장하지 마세요.

Docker 없이 헬퍼는 설치된 로컬 브라우저 바이너리를 사용합니다. 로컬 모드를 강제하려면 VISUAL_VERIFY_DOCKER=0을 설정하세요. 실행 API는 명시적 백엔드도 허용합니다. JSON 출력은 실제 백엔드와 버전을 지정합니다.

프로젝트 스크립트용 지원 런처

// 설치된 스킬 디렉토리를 기준으로 이 import를 확인하세요.
const { launchBrowser } = await import("<설치된-스킬>/scripts/load-playwright.mjs");
const { browser, where } = await launchBrowser("chromium", {
  backend: "auto", // auto, docker, local
  timeout: 30000,
  launchOptions: { headless: true },
});
try {
  // browser.newContext() 등 사용. 증거와 함께 `where`를 보고하세요.
} finally {
  await browser.close();
}

launchOptions는 로컬 launch 또는 고정된 Docker 서버 브라우저 실행 요청으로 전달됩니다. 전체 Playwright 서버는 요청된 클라이언트 루프백 전달을 활성화합니다. Docker가 서버 호스트와 포트를 소유합니다. 호스트별 실행 파일 경로 및 기타 시스템별 옵션은 호출자의 책임입니다. 기존 loadChromium() 및 loadBrowser(name) 내보내기는 로컬 전용 호환성 API로 남아 있습니다. Docker를 실행하거나 누락된 브라우저를 복구하지 않습니다. 설정이 동작을 변경한다고 가정하지 않고 호출자를 의도적으로 마이그레이션하세요.

Docker 실행은 각 호출에 대해 새롭고 고유한 이름의 서버 컨테이너를 사용합니다. Docker는 원자적으로 루프백 포트를 할당합니다. 클라이언트는 컨테이너 메타데이터를 확인하고 보고된 WebSocket 경로에 연결합니다. Playwright는 클라이언트 루프백 트래픽을 전달하여 호스트 네트워킹 없이 로컬 개발 앱에 대한 액세스를 유지합니다. 종료, 시작 실패 및 처리된 종료 시 컨테이너가 제거됩니다. 이는 웜 서버 재사용을 엔드포인트 격리와 맞바꿉니다. 이전 공유 포트 컨테이너는 그대로 둡니다. 강제 종료 또는 Docker 실패는 고아 컨테이너를 남길 수 있습니다. doctor 출력을 검사하고 명시적으로 제거하기 전에 정확한 컨테이너의 소유권을 확인하세요. 일치하는 모든 프로세스/컨테이너를 중지하지 마세요. 크로스 플랫폼 Docker 동작은 여전히 독립적인 검증이 필요합니다.

screenshot.mjs 플래그: --url --out [--width 390] [--height 844] [--dpr 2] [--mobile] [--wait 2000] [--click "텍스트 또는 선택자"] [--scroll-bottom "셀"] [--eval "js"] [--clip x,y,w,h] [--full]. --click은 반복 가능하며 먼저 버튼의 접근 가능한 이름을 일치시킨 다음 CSS 선택자를 일치시킵니다. 탭/메뉴/대화 상자 뒤의 상태에 도달하는 데 사용하세요.

일회성 설치 (머신당)

bash "$VISUAL_VERIFY_DIR/scripts/install.sh"

잠긴 종속성을 이 스킬의 자체 node_modules에 설치합니다. 기본 auto 설정은 Docker를 사용할 수 있는 경우 일치하는 Docker 이미지를 가져오고, 그렇지 않으면 로컬 Chromium을 설치합니다. 설치 프로그램에 docker 또는 local을 전달하여 명시적으로 선택하세요. 이 명령으로 로컬 WebKit은 설치되지 않습니다. 전역 npm 패키지나 시스템 패키지는 변경되지 않습니다.

브라우저를 시작하거나 이미지를 가져오거나 컨테이너를 변경하지 않고 전제 조건을 검사하세요:

node "$VISUAL_VERIFY_DIR/scripts/doctor.mjs"

Doctor는 스킬/런타임 버전, 런타임 경로, 로컬 실행 파일 존재 여부, Docker 이미지 사용 가능 여부 및 활성 Visual Verify 컨테이너/엔드포인트(레거시 이름 포함)를 보고합니다. 종료 상태는 선택된 기본 백엔드에 대한 Chromium 전제 조건을 확인합니다. 브라우저 실행 또는 WebKit 사용 가능 여부를 증명하지는 않습니다. 파일 설치와 브라우저 성공적 실행은 별개의 증거입니다.

다음으로 확인하세요:

node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
  --url https://example.com --out /tmp/_vv_check.png --width 390 --height 844

이미지와 백엔드 JSON을 검사하여 이 스모크 테스트가 작동했는지 확인하세요.

확인 중인 상태를 기다리세요

스크린샷 및 터치 명령은 다음 사후 작업 옵션을 지원합니다:

  • --ready-selector "<선택자>": 일치하는 첫 번째 요소가 표시될 때까지 기다립니다.
  • --ready-js "<표현식>": 페이지 표현식(프라미스 포함)이 참이 될 때까지 폴링합니다.
  • --ready-timeout 10000: 양수 준비 타임아웃(밀리초)이며, 선택자 및 조건문 대기에서 공유됩니다. 또한 --eval 및 --report 평가를 별도로 제한합니다.
  • --settle 0: 준비 후 애니메이션을 위한 선택적 음이 아닌 지연 시간입니다.

이러한 조건은 모든 클릭/탭, 스크롤, 평가 및 드래그 후, 감사 및 캡처 전에 실행됩니다. 두 조건이 모두 제공되면 모두 통과해야 합니다. 실패 시 0이 아닌 값으로 종료되며 새 성공 스크린샷을 작성하지 않습니다(기존 출력 파일은 제거되지 않습니다). 고유한 출력 경로를 선택하세요. --wait는 레거시 사전 작업 지연을 유지합니다. 고정된 클릭/드래그 지연은 준비 증거가 아닌 호환성 안정화 지연으로 남아 있습니다. 선택한 조건이 무엇을 증명하는지 명시하세요.

node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
  --url "<로컬-앱-url>" --out visual-checks/search-desktop.png \
  --click "Search" --ready-selector "[data-search-results]" \
  --ready-js "document.querySelectorAll('[data-result]').length > 0"

이미 페이지에 있는 오래된 요소가 아니라 예상되는 새 상태에 특화된 조건을 사용하세요. 비동기 결과가 필요한 중간 단계의 경우 실행 API와 Playwright 로케이터를 사용하여 작업 사이에 어설션을 사용하세요. 응답을 기다려야 하는 경우 요청을 트리거하기 전에 대기를 등록한 다음 렌더링된 상태를 어설션하세요. 응답만으로는 렌더링이 증명되지 않습니다. 디바운스된 앱의 경우 임의의 지연 또는 network-idle을 완료 보장으로 처리하지 마세요.

출력 위치

생성된 이미지를 저장소 루트의 gitignored된 visual-checks/ 디렉토리에 작성하세요 (mkdir -p visual-checks). 저장소 내에 있지 않거나 파일을 추가하고 싶지 않은 경우 대신 임시 디렉토리를 사용하세요. 사용자에게 파일을 보낼 때 안정적인 경로를 참조하세요.

한 번의 실행에서 모든 이미지에 공유 <변경> 접두사를 부여하여 무엇을 보여주는지 설명하세요 (예: import-export-tab, header-nav) — 일반적인 before.png/after.png가 아닙니다. 디렉토리를 보면 파일이 어떤 실행에 속하는지 알 수 있습니다:

visual-checks/<변경>-<뷰포트>.png                 # verify 모드: 단일 샷
visual-checks/<변경>-<뷰포트>-before.png          # before/after 모드
visual-checks/<변경>-<뷰포트>-after.png
visual-checks/<변경>-<뷰포트>-before-after.png    # 합성 이미지

여기서 <뷰포트>는 mobile 또는 desktop입니다.

워크플로우 — verify 모드

  1. 앱이 실행 중이고 URL이 있는지 확인하세요 (이 프로젝트가 실행되는 방식으로 시작하세요 — 아래 앱 실행 참조). mkdir -p visual-checks.
  2. 확인할 상태를 캡처하고, 필요한 경우 --click / --eval / --scroll-bottom으로 도달하세요:
    node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
      --url "<실행 중인 앱 url>" --out visual-checks/<변경>-mobile.png \
      --width 440 --height 800 --mobile --wait 2000
    
    필요에 따라 여러 너비를 스위핑하거나 --mobile을 제거하고 데스크톱의 경우 --width 1280 --height 800 등을 사용하세요.
  3. 각 이미지를 읽고 올바른지 여부를 명확히 보고하세요. 수정 사항을 확인하는 경우 깨진 부분이 실제로 사라졌는지 확인하고, 기능을 확인하는 경우 실제로 렌더링되는지 확인하세요.
  4. 답변에 관련 샷을 표시하세요 — 기능당 하나씩 (위의 확인한 내용 표시 참조).

워크플로우 — before/after 모드

  1. 범위와 뷰포트를 확인하세요. mkdir -p visual-checks. 공유 <변경> 접두사를 선택하세요.
  2. AFTER 캡처 — 작업 트리에는 이미 변경 사항이 있습니다:
    node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
      --url "<실행 중인 앱 url>" --out visual-checks/<변경>-mobile-after.png \
      --width 440 --height 800 --mobile --wait 2000
    
    데스크톱의 경우 --mobile을 제거하고 --width 1280 --height 800 등을 사용하며 파일명에 -desktop-after.png 접미사를 사용하세요.
  3. BEFORE 캡처 — 시각적 변경만 임시로 되돌리고 <변경>-<뷰포트>-before.png로 스크린샷을 찍은 후 복원하세요. 복원을 잊지 않도록 git을 선호합니다:
    • 커밋되지 않은 변경: git stash push -- <파일> → 스크린샷 → git stash pop
    • 커밋된 변경: git show HEAD~1:<경로> > <경로> (또는 git checkout <부모> -- <파일>) → 스크린샷 → git checkout -- <파일> 토글과 샷 사이에 dev 서버가 핫 리로드될 때까지 기다리세요 (--wait).
  4. 합성 — 동일한 접두사, -before-after.png 접미사:
    node "$VISUAL_VERIFY_DIR/scripts/composite.mjs" \
      --before visual-checks/<변경>-mobile-before.png --after visual-checks/<변경>-mobile-after.png \
      --out visual-checks/<변경>-mobile-before-after.png \
      --title "440px (iPhone 너비)의 헤더" \
      --before-label "BEFORE — 제목이 찌그러짐" \
      --after-label  "AFTER — 제목이 전체 너비"
    
  5. 합성 이미지를 읽고 주장하는 내용이 표시되는지 확인한 후 답변에 표시하세요.
  6. BEFORE 토글을 복원하세요. 임시 BEFORE 변경 사항이 여전히 적용된 상태로 커밋하거나 배포하지 마세요. 완료하기 전에 git status / git diff를 다시 확인하세요.

모바일 터치 확인

(…

[번역을 위해 잘림]

관련 스킬