디자인시스템: StoryBook, Chromatic과 Git Action설정하기 : Visual Regression Test

김규회·2024년 12월 13일
Git botVisualize Regression Testchromaticgitgit actionpreview urlstorybook
0

summit-up!

목록 보기
2/2

Main: https://github.com/zagdang/design-system/pull/7

디자인 시스템 배포 자동화: Storybook, Chromatic, GitHub Actions 활용기

도입 배경

디자인 시스템을 운영하면서 가장 중요하게 생각한 부분은 '팀 간 원활한 소통'과 'UI 일관성 유지'였다. 특히 여러 팀원들과 디자인 토큰을 공유하고 피드백을 주고받는 과정에서, 지속적인 배포와 시각적 테스트의 필요성을 느꼈다.

Storybook & Chromatic 설정

1. Chromatic 설정

name: 'Chromatic Deploy'

on:
  push:
    branches: [main, develop]

jobs:
  deploy:
    name: 'Deploy Storybook'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Enable Corepack
        run: |
          corepack enable
          corepack prepare yarn@4.5.3 --activate

      - name: Install dependencies
        run: |
          yarn install --immutable
          yarn dlx @yarnpkg/sdks vscode

      - name: Build Storybook
        run: yarn workspace @zagdang/ui build-storybook

      - name: Deploy to Chromatic
        uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          workingDir: packages/ui
          storybookBuildDir: storybook-static
          autoAcceptChanges: true

이렇게 설정하면:

  • 모든 push 이벤트에서 Chromatic 배포가 자동으로 실행된다
  • UI 변경사항을 시각적으로 확인할 수 있다
  • 브랜치/커밋 간의 차이를 쉽게 비교할 수 있다

2. PR 체크 자동화

# .github/workflows/pr-check.yml
name: 'Chromatic PR Check'

permissions:
  pull-requests: write
  contents: read

on:
  pull_request:
    types: [opened, synchronize, reopened]
    branches: [main, develop]

jobs:
  review:
    name: 'Review Changes'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Enable Corepack
        run: |
          corepack enable
          corepack prepare yarn@4.5.3 --activate

      - name: Install dependencies
        run: |
          yarn install --immutable
          yarn dlx @yarnpkg/sdks vscode

      - name: Build Storybook
        run: yarn workspace @zagdang/ui build-storybook --webpack-stats-json

      - name: Create Preview
        id: chromatic
        uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          workingDir: packages/ui
          storybookBuildDir: storybook-static
          onlyChanged: true
          exitZeroOnChanges: true

      - name: Set URL
        if: success()
        run: echo "STORYBOOK_URL=${{ steps.chromatic.outputs.storybookUrl }}" >> $GITHUB_ENV

      - name: Comment PR
        uses: thollander/actions-comment-pull-request@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          message: |
            📚 Storybook Preview Ready!
            🔍 Review URL: ${{ env.STORYBOOK_URL }}

PR 체크 워크플로우는:

  • main 또는 develop 브랜치로 PR 생성
  • GitHub Actions가 자동으로 Chromatic PR Check 워크플로우 시작
  • PR이 업데이트되거나 재오픈될 때도 동일한 프로세스 실행
  • 개발 환경 준비 (Yarn Berry, Node.js, code 체크아웃 설정)
  • 의존성 설치 및 빌드(Storybook 빌드, 패키지 설치)
  • Chromatic 테스트
    • 빌드된 Storybook을 Chromatic에 업로드
    • 각 스토리별 스크린샷 생성
    • 이전 버전과 비교
  • PR 업데이트
    • 프리뷰 URL 생성
    • 환경변수에 URL 저장
    • 자동으로 PR에 코멘트 추가
    • Storybook 프리뷰 링크 포함
  • 리뷰 프로세스

Visual Regression Test의 이점

실제로 얻은 장점들:

  1. 디자인 일관성 유지

    • 의도치 않은 UI 변경을 즉시 감지할 수 있었다
    • 변경사항을 시각적으로 확인하고 승인할 수 있었다
    • 실수로 인한 디자인 깨짐을 방지할 수 있었다

  2. 팀 커뮤니케이션 개선

    • UI 변경사항을 링크로 공유할 수 있어 피드백이 수월했다
    • 브랜치별로 독립된 Storybook 환경을 제공받을 수 있었다
    • 리뷰 프로세스가 더 효율적으로 변했다

  3. 배포 자동화

    • GitHub Actions를 통한 자동 배포로 시간을 절약했다
    • PR마다 자동으로 시각적 테스트가 실행됐다
    • 수동 작업이 크게 줄었다

구체적인 워크플로우

  1. 개발 과정

    # 새로운 기능 브랜치 생성
git checkout -b feature/new-component

# 컴포넌트 개발 및 스토리 작성
yarn storybook

# 변경사항 커밋
git commit -m "feat: Add new component"

# PR 생성
git push origin feature/new-component

  2. 자동화된 검증

    • PR 생성 시 자동으로 pr-check.yml 실행
    • Chromatic에서 시각적 테스트 수행
    • 리뷰어에게 변경사항 링크 자동 공유

  3. 배포 프로세스

    • main 브랜치 머지 시 chromatic-deploy.yml 실행
    • 자동으로 최신 버전 Storybook 배포
    • GitHub Pages를 통해 문서 공개

실제 사용해본 Chromatic의 장점

1. 상세한 UI 리뷰 기능

픽셀 단위의 변경사항 감지
실제 경험했던 사례를 보면:

  • Button 컴포넌트의 패딩값이 1px만 바뀌어도 바로 캐치할 수 있었다
  • 폰트 사이즈나 line-height 변경도 즉시 감지됐다
  • 심지어 그라데이션 각도가 살짝 틀어진 것도 발견할 수 있었다

예를 들어 이런 작은 변경사항도 감지했다 ( shadcn이라 다른예시를 가져와봤습니다. 예시로만 봐주세요!):

.button {
  padding: 8px 16px;  /* 이전 */
  padding: 8px 15px;  /* 변경 후 - 1px 차이 감지 */
}

이게 진짜 유용했던 게, UI 깨짐을 사전에 발견할 수 있었다. 특히 UI가 어떻게 변하는지 한눈에 볼 수 있어서 좋았다.

변경사항 승인/거부 워크플로우

실제 워크플로우는 이렇게 진행됐다:
1. 변경사항 발견 시 시각적으로 하이라이트 표시
2. 변경 부분을 클릭하면 before/after 비교 가능
3. 승인 또는 거부를 통해 변경사항 관리
4. 거부된 변경사항은 자동으로 PR에 코멘트로 달림

2. 협업 기능

변경사항 코멘트
정말 직관적이었다:

  • 변경된 부분에 직접 코멘트를 달 수 있었다
  • 특정 영역을 드래그해서 그 부분에 대한 피드백을 남길 수 있었다
  • 코멘트에 @멘션으로 특정 팀원 호출 가능

실제로 이런 대화가 가능했다:

팀원1: "@프론트엔드 버튼의 그림자가 디자인 가이드와 좀 다른 것 같아요"
본인: "네, box-shadow 값을 수정할께요."

팀 공유 기능
링크 하나로 모든 정보 공유가 가능했다:

  • 브랜치별 스토리북 주소 자동 생성
  • 변경사항 비교 페이지 직접 공유
  • 리뷰 히스토리도 함께 공유

특히 디자이너와 협업할 때 정말 편했다. 디자이너가 "이 버튼 좀 이상한데요?"라고 하면, 바로 해당 컴포넌트의 변경사항 페이지를 공유할 수 있었다.

버전 히스토리
커밋 단위로 모든 변경사항을 추적할 수 있었다:

  • 언제, 누가, 어떤 변경을 했는지 모두 기록
  • 특정 시점으로 돌아가서 확인 가능
  • 각 변경사항의 승인자도 기록

3. CI/CD 통합

자동화된 테스트
매 PR마다 자동으로:

  • 스토리북 빌드 체크
  • 비주얼 리그레션 테스트 실행
  • 테스트 결과 PR에 코멘트로 추가

예를 들어 Button 컴포넌트 변경 후 PR을 올리면:
1. Chromatic이 자동으로 테스트 실행
2. 변경된 스토리들 감지
3. 시각적 차이점 하이라이트
4. 결과를 PR에 코멘트로 추가

PR 상태 관리
GitHub와 긴밀하게 연동되어:

  • PR 체크 항목으로 자동 추가
  • 리뷰 승인 시 자동으로 체크 통과
  • PR 머지 가능 여부 자동 제어

이런 자동화 덕분에 실수로 버그가 있는 코드가 머지되는 것을 여러 번 방지할 수 있었다.

이렇게 세밀한 관리 기능들이 있어서, 디자인 시스템의 품질을 훨씬 더 높은 수준으로 유지할 수 있었다. 특히 여러 팀원들이 동시에 작업할 때 발생할 수 있는 실수들을 사전에 잡아낼 수 있어서 좋았다.

앞으로의 계획

현재 구축한 시스템을 기반으로:

  • jest 세팅
  • 테스트 커버리지 확대
  • 성능 메트릭 모니터링 추가
  • 문서화 자동화 강화

이런 자동화 시스템 덕분에 디자인 시스템 관리가 한결 수월해졌고, 특히 팀 간 협업 과정이 많이 개선됐다.

profile
김규회
프론트엔드 Developer
이전 포스트

디자인 시스템 배포에 관한 고찰 : Yarn Berry와 Turborepo 도입기

0개의 댓글