| name | visual-regression-until-match |
| description | UI 변경에 Playwright나 Percy 비주얼 스냅샷을 돌려서, 의도치 않은 시각적 diff는 고치고 의도된 변경만 베이스라인에 반영해 스냅샷이 깔끔히 일치(종료 코드 0)할 때까지 자동으로 반복하는 닫힌 루프입니다. 사용자가 "비주얼 회귀 테스트 돌려줘", "UI 바뀐 거 스크린샷 diff 잡아줘", "Playwright 비주얼 스냅샷 맞을 때까지", "의도 안 한 시각 변화 고쳐줘", "Percy/Chromatic 베이스라인 일치시켜줘", "visual regression until match", "run visual snapshot tests", "fix unintended visual diffs until baselines match"처럼 요청하거나, 디자인 변경 후 픽셀 단위 회귀를 반복적으로 고쳐 베이스라인에 수렴시키고 싶을 때 사용하세요. (구분: 전체 E2E 사용자 흐름 검증은 looping:e2e-until-green, 접근성 위반 점검은 looping:a11y-audit-until-clean, 일반 단위·통합 테스트 스위트를 green까지는 looping:test-until-green) |
비주얼 회귀 일치까지 (Visual Regression Until Match)
UI 변경에 Playwright/Percy 비주얼 스냅샷을 돌리고, 의도치 않은 diff를 고쳐 베이스라인이 의도대로 일치할 때까지 반복합니다.
| 항목 | 값 |
|---|
| 카테고리 | 테스트(Testing) |
| 트리거 | 수동(manual) — 사람이 직접 시작 |
| 종료 조건(Exit) | 비주얼 테스트가 종료 코드 0으로 끝날 때 (= 승인된 베이스라인과 일치) |
| 반복 한도(Max iterations) | 6 |
| 매 반복 체크 명령 | npx playwright test --grep @visual |
| 가드레일 | 강화됨(Hardened) |
| 지원 에이전트 | Claude Code · Cursor · Codex |
이 루프는 언제 쓰나
스타일이나 마크업을 손본 뒤 "이 변경이 다른 화면을 의도치 않게 망가뜨리지 않았나?"를 매번 눈으로 확인하기 번거로울 때 씁니다. 한 번 시작하면 에이전트가 비주얼 테스트 실행 → 달라진 스크린샷 식별 → 버그면 수정 / 의도면 베이스라인 승인 → 재실행을 스스로 반복하며 스냅샷이 의도대로 일치하는 상태로 수렴시킵니다. 핵심은 모든 diff를 무턱대고 베이스라인으로 덮어쓰지 않는 것 — 의도치 않은 변화는 CSS/마크업을 고쳐 되돌리고, 진짜 디자인 변경만 리포트로 확인한 뒤 베이스라인에 반영합니다.
루프 흐름
수동 시작 → 비주얼 테스트 실행 → diff 수정 / 의도된 변경은 베이스라인 승인 → 재실행 →〔피드백 게이트〕전부 일치?
↑ │ 아니오
└──────────────────────────────────────────────────────────────────────────┘
│ 예
종료
매 반복(pass)마다 하는 일
- 비주얼 테스트 실행 — 비주얼 회귀 테스트를 돌려, 베이스라인과 달라진 스크린샷을 컴포넌트 이름과 함께 나열합니다.
npx playwright test --grep @visual
- 수정 또는 승인 — diff가 버그면 CSS/마크업을 고칩니다. 의도된 변경이면 리포트에서 직접 확인한 뒤에만 스냅샷(베이스라인)을 업데이트합니다.
가드레일 (점수 조작 방지 규칙)
종료 조건을 "가짜로" 통과시키지 못하게 막는 규칙입니다. 반드시 지키세요.
- 체크 명령이나 종료 기준을 고쳐서 억지로 성공시키지 않는다.
- 체크를 건너뛰거나 비활성화·우회해서 종료 조건을 통과시키지 않는다.
- 여러 번 반복해도 막히면, 지표를 조작하지 말고 멈추고 블로커를 보고한다.
- 스위트를 통과시키려고 테스트를 약화·삭제·skip 하지 않는다.
- 진짜 단언(assertion)을 항상 통과하는 껍데기 테스트로 바꾸지 않는다.
- green으로 만들려고 테스트를 땜질하기보다 프로덕션 코드를 고치는 쪽을 택한다.
Claude Code에서 실행하기
가장 간단합니다. 아래 kickoff 프롬프트를 그대로 붙여넣으면 에이전트가 스스로 반복합니다.
"비주얼 회귀 일치까지(Visual Regression Until Match)" 루프를 시작합니다.
목표: 비주얼 회귀 스위트가 의도된 UI 변경만 반영한 채 통과
최대 반복: 6
매 반복 사이 실행: npx playwright test --grep @visual
종료 조건: 비주얼 테스트가 종료 코드 0으로 끝날 때
1단계: 비주얼 테스트를 실행한다. 의도치 않은 UI diff는 고치고, 베이스라인은 의도된 디자인 변경에 한해서만 업데이트한다.
이 루프를 스스로 페이싱(self-pace)하라. 매 반복 후 체크 명령을 실행하고 출력을 읽어, 종료
조건이 충족되지 않았을 때만 계속한다. 종료 조건이 통과하거나 최대 반복에 도달하면 멈춘다.
매 회차마다 한 줄 상태 업데이트를 남긴다.
팁: npx playwright test --grep @visual은 예시입니다. 프로젝트에 맞게 Percy(percy exec -- ...), Chromatic(npx chromatic), Cypress(cypress run) 등으로 바꾸세요.
팁 / 변형
- 체크 명령 교체: Playwright의
toHaveScreenshot 대신 Percy·Chromatic 같은 클라우드 비주얼 서비스, 혹은 jest-image-snapshot으로 바꿔도 흐름은 같습니다. 체크 명령만 그 생태계의 실행 명령으로 교체하세요.
- 베이스라인 업데이트는 신중히:
--update-snapshots(Playwright)는 강력한 도구입니다. HTML 리포트로 diff를 눈으로 확인하지 않은 채 일괄 업데이트하면 진짜 회귀를 베이스라인으로 덮어쓰게 됩니다. 가드레일대로 "의도된 변경만" 승인하세요.
- 막힐 때: 같은 컴포넌트의 diff가 2회 반복되면 멈추고, 해당 스크린샷과 원인 가설을 함께 사람에게 보고하게 하세요.
- 연관 루프: 전체 E2E 사용자 흐름 검증은
looping:e2e-until-green, 접근성 위반 점검은 looping:a11y-audit-until-clean, 일반 테스트 스위트를 green까지는 looping:test-until-green.
원본 영어 kickoff (loops.elorm.xyz 원문)
Start the "Visual Regression Until Match" loop.
Goal: visual regression suite passes with intentional UI only
Max iterations: 6
Between iterations run: npx playwright test --grep @visual
Exit when: visual tests exit 0
Step 1: Run visual tests. Fix unintended UI diffs; update baselines only for deliberate design changes.
Self-pace this loop. After each iteration, run the check command, read the output, and only continue if the exit condition is not met. Stop when the exit condition passes or max iterations is reached. Give a short status update each pass.
출처: https://loops.elorm.xyz/loops/visual-regression-until-match
