/jaspr-web regression — 화면 틀어짐 자동 검사#

한마디로#

배포 전후로 웹 화면을 페이지마다 자동으로 찍어서, "정답 사진(기준 화면)"과 한 장씩 겹쳐 비교하는 도구입니다. 틀린 그림 찾기처럼, 버튼·여백·색이 살짝이라도 달라지면 바뀐 부분을 빨간 영역으로 짚어 줍니다.

누가·언제 쓰나요#

• 웹 화면을 배포하기 직전, "예전 화면이 나도 모르게 깨지지 않았나" 확인하고 싶은 개발자·QA
• 디자인 시스템(CoUI)이나 공용 컴포넌트를 손본 뒤, 다른 페이지가 줄줄이 틀어지지 않았는지 점검할 때
• 디자인을 의도적으로 바꾼 뒤, "이제 이 모습이 정답"이라고 기준 화면을 새로 갱신하고 싶을 때

무엇을 해주나요#

• 지정한 페이지들을 여러 화면 크기(모바일·태블릿·PC)로 자동 촬영합니다.
• 기준 화면과 비교해 각 페이지를 pass(통과) / within-tolerance(허용 범위 내 차이) / fail(틀어짐) / new(기준 없음)으로 분류합니다.
• 틀어진 페이지는 기준 | 실제 | 차이 강조 3장이 나란히 붙은 비교 이미지를 .claude/docs/jaspr-web/regression-<시각>/diffs/ 폴더에 저장하고, 어느 영역이 얼마나 바뀌었는지 요약을 함께 남깁니다.

어떻게 쓰나요#

/jaspr-web regression \
  --routes=/,/components/button,/components/input,/live-preview-poc \
  --base-url=https://coui.cocode.im \
  --tolerance=pixel=2,color_delta_e=3,percent=0.5

• --routes (필수): 검사할 페이지 경로들을 쉼표로 나열하거나 @<파일> 형태로 YAML 목록을 지정합니다.
• --base-url: 어느 사이트 주소에서 찍을지 (생략하면 현재 브랜치의 배포 대상에서 추정).
• --tolerance: 어느 정도 차이까지 봐줄지 허용 오차 (픽셀·색 차이·전체 비율).
• --update-baseline=true: 디자인을 일부러 바꿨을 때, 새 화면을 정답(기준)으로 덮어씁니다.
• --keep-animations: 평소엔 애니메이션을 끄고 찍지만, 이 옵션을 주면 애니메이션을 유지합니다.

안에서 무슨 일이 벌어지나요#

페이지와 화면 크기 조합마다 다음을 반복합니다.

1. 해당 페이지 주소로 이동합니다.
2. 네트워크가 잠잠해질 때까지(networkidle) 기다립니다.
3. 페이지 전체를 한 장으로 촬영합니다.
4. 기준 화면이 있으면 픽셀 단위로 비교해 통과/허용 범위/틀어짐으로 판정합니다.
5. 기준 화면이 없으면 new(새 화면)로 표시합니다.

- route: /components/button
  viewport: 1280x800
  changed_regions:
    - { x: 240, y: 412, width: 96, height: 36, severity: major }
  diff_pct: 1.8%
  notes:  " Possible padding regression on Button (primary variant) "

/jaspr-web regression \
  --routes=/,/components/button,/components/input,/live-preview-poc \
  --base-url=https://coui.cocode.im \
  --tolerance=pixel=2,color_delta_e=3,percent=0.5