2026 OpenClaw 프론트 실전:
원격 Mac에서 시각 회귀 diff 보고서를 파싱·PR 요약으로 회수
시각 회귀는 스크린샷 한 장보다 머신 리더블 JSON·아티팩트가 먼저입니다. Percy·Chromatic·자체 파이프라인 중 무엇을 쓰든, 원격 Mac 러너에서 동일한 단계로 실패 스냅샷을 모아 PR 코멘트나 Webhook으로 돌려보내는 흐름을 고정하면 팀이 같은 속도로 대응합니다.
01 콘솔 딥링크 대신 계약 우선
벤더 웹 콘솔 URL은 세션·조직 경계에 묶이기 쉽고, 리포지토리에 하드코딩하면 로그인 없이는 열리지 않는 링크가 됩니다. 대신 CI가 만든 JSON·아티팩트 ZIP·공식 CLI의 stdout만 입력으로 인정하고, 사람이 볼 URL이 필요하면 워크플로가 런타임에 조합한 값을 환경 변수로 넘기세요.
동일한 규칙은 번들 분석기 임계·PR 요약 파이프라인과 맞추면, OpenClaw 게이트웨이의 허용 경로·보고서 디렉터리 규칙을 한 번만 설명해도 됩니다.
02 Percy / Chromatic / 자체 diff JSON
벤더별 필드 이름은 다르지만, 에이전트가 읽을 공통 스키마만 정하면 됩니다. 아래는 정규화 전 단계에서 채울 최소 열입니다.
| 공통 필드 | 의미 |
|---|---|
story_key |
컴포넌트·스토리·경로 식별자(브랜치와 무관한 안정 키) |
viewport |
뷰포트·브라우저·테마 등 변형 축 |
status |
pass / fail / flaky 등 이진 판정 전 단계 |
diff_metric |
픽셀 비율·SSIM·벤더 고유 점수 중 하나를 숫자로 |
artifact_ref |
CI 아티팩트 이름 또는 객체 스토리지 키(비밀 없음) |
자체 도구는 Storybook·Playwright 스냅샷 등에서 visual_diff.json 한 파일로 떨어뜨리고, Chromatic/Percy는 각 문서에 나온 export·API·CLI JSON 모드를 얇은 래퍼 스크립트로 감싸 같은 스키마로 변환합니다. 스토리 단위 게이트는 스토리북 정적 자산 게이트 글과 병행하면 회귀 신호가 한 디렉터리에 모입니다.
03 빌드·시각 잡 트리거
PR 이벤트·수동 workflow_dispatch·야간 스케줄 중 팀 표준을 하나 고릅니다. 중요한 것은 커밋 SHA·런 ID·브랜치 이름이 아티팩트 키에 들어가 충돌을 줄이는 것과, 프론트 빌드 산출물과 시각 잡이 같은 노드(또는 캐시 계층)를 참조하는 것입니다. Apple Silicon 원격 Mac에서 WebKit·폰트 렌더까지 맞추려면 사전 스모크 절차를 E2E 로그 트리아지 런북과 같은 깃 워크플로에 넣어 두면 재현 논쟁이 줄어듭니다.
04 보고서 가져오기
Git 호스팅이라면 Actions/GitLab API 등으로 아티팩트를 내려받고, 토큰은 해당 저장소 읽기만 허용합니다. 벤더 API를 쓸 때는 키를 리포지토리 시크릿에만 두고, 스크립트에는 REPORT_FETCH_URL 같은 자리표시자만 남깁니다. 네트워크가 불안정하면 타임아웃을 짧게 두고 아래 패턴으로 재시도하세요.
# 의사 코드: 지수 백오프 (최대 5회, 429·5xx만)
delay = 1
for attempt in range(5):
r = http_get(artifact_url, headers=auth_headers)
if r.ok: break
if r.status in (429, 500, 502, 503, 504):
sleep(delay); delay = min(delay * 2, 32)
else: raise05 OpenClaw로 실패만 요약
정규화된 배열에서 status != pass인 항목만 남기고, 스토리 키로 정렬한 뒤 상위 20건과 건수·치명도 한 줄을 마크다운으로 만듭니다. 에이전트 프롬프트에는 “스크린샷 바이너리는 붙이지 말고 경로·메트릭만”을 명시해 토큰과 유출 면적을 줄입니다. 출력은 .openclaw/reports/<sha>/visual_pr_summary.md처럼 커밋 SHA 아래에만 쓰게 하면 다른 OpenClaw 작업과 권한 모델이 일치합니다.
06 Git PR 코멘트·Webhook
GitHub 예시로는 gh pr comment 또는 REST 한 엔드포인트에 pull request 쓰기 한정 토큰만 씁니다. 사내 게이트웨이는 HMAC 서명·Idempotency-Key 헤더로 동일 요약의 중복 전송을 막고, 429·게이트웨이 오류에는 위와 같은 백오프를 공유합니다. 코멘트 본문에는 “원본 JSON 아티팩트 이름” 정도만 적고, 로그인이 필요한 벤더 UI 링크는 넣지 않습니다.
- 토큰: 단일 레포, 최소 스코프, 만료 짧게, 봇 계정 분리.
- 재시도: 멱등 키가 있으면 POST도 안전하게 반복 가능.
- 감사: 누가 어떤 SHA에 어떤 요약을 올렸는지 로그 한 줄.
07 요약
시각 회귀 자동화의 핵심은 벤더 UI가 아니라 JSON 계약·최소 권한·재시도 가능한 전송입니다. 절차를 고정한 뒤에는 기술 인사이트 블로그의 인접 런북과 묶어 팀 온보딩 비용을 줄이세요. 원격 Mac·SSH·VNC 안내는 도움말에서 로그인 없이 확인할 수 있습니다.