Chromatic으로 시각적 회귀 테스트 구축하기

✅ 본 게시글은 스토리북 7.1.0 버전과 TypeScript를 기반으로 작성되었습니다.

 

잦고 반복되는 디자인 변경은 개발자를 힘들게 해요!

디자인 시스템을 개발하면서 가장 힘든 부분은

변경 사항이 발생했을 때 컴포넌트의 UI가 정상적으로 렌더링되는지 확인하는 것이었다.

특히나 가장 기본 요소인 색, 여백, 글씨 크기와 같은 요소가 변경될 경우

현재 컴포넌트 뿐만이 아닌 다른 모든 컴포넌트에 영향을 미치기 때문에

이를 일일이 확인해가며 이를 체크하는 것이 너무 힘들었고 시간도 많이 소비되었으며 미처 잡지 못하는 경우 역시 존재했다.

때문에 이를 해결할 수 있는 방법이 없을까 테스트 쪽으로 눈을 돌리게 되었고,

거기에서 스토리북의 Visual Test를 통해 이를 해결할 수 있다는 것을 알게 되어 적용해보게 되었다.

 

 

✅ Storybook Test

스토리북은 비지니스 로직과 UI를 분리하여 독립된 환경에서 UI를 렌더링하고 살펴보는 UI 사전의 역할을 한다.

그리고 각 UI에 스토리(맥락)를 부여하여 특정 상황에서 렌더링 되는 UI를 보여줄 수 있어 로직과 별개로 렌더링을 해볼 수 있다.

이 각각을 "스토리"라고 칭하는데 스토리북은 이 스토리를 통해서 Test를 진행할 수 있는 환경을 제공한다.

 

스토리북에서 할 수 있는 테스트를 간략하게 소개하면 아래와 같다.

 

• Visual Test : UI의 변경 검사
• Interaction Test : 유저 액션에 따른 컴포넌트 동작 검사
• Accessibility Test : 컴포넌트 UI의 접근성 만족 여부 검사
• Coverage Test : 실행되지 않는 코드 라인은 없는지 검사
• Snapshot Test : HTML 변경 검사
• Unit Test : 개별 함수 또는 기능 동작 검사
• E2E Test : 유저 플로우 검사

 

위의 테스트 중에서 아까 말했던 컴포넌트 UI의 변경사항을 포착하고 싶다면 비쥬얼 테스트를 적용하면 해결 될 것이다.

이제 적용해보자.

 

⚠️ 여기서 비쥬얼 테스트와 언뜻 비슷하게 보이는 것이 바로 스냅샷 테스트인데,
       스냅샷 테스트 역시 하나의 기준점을 잡고 이와 비교해 변경사항을 포착하는 테스트이지만,
       비쥬얼 테스트에서의 기준점은 브라우저에 렌더링 된 컴포넌트의 캡쳐 이미지라면,
       스냅샷 테스트는 HTML 코드라는 점이 다르다.

 

 

💿 Chromatic 적용하기

 

먼저, 크로마틱 사이트에 접속 후 Sign Up을 눌러 회원가입을 해준다.

 

 

그 후에 위와 같은 화면이 나오는데,

기존 프로젝트에 크로마틱을 사용할 생각이라면 Choose from Github를

새 프로젝트를 만들 생각이라면 Create a project를 눌러서 프로젝트를 만들어준다.

 

# 크로마틱 설치
yarn add --dev chromatic
# 크로마틱 설정
npx chromatic --project-token=[프로젝트 토큰]

 

프로젝트를 생성했다면 프로젝트 토큰이 화면에 나올텐데 이를 사용해 프로젝트 폴더에 크로마틱을 설치, 설정해준다

 

 

그러면 크로마틱이 알아서 빌드하고 배포까지 한 다음에 아래와 같은 스토리북 배포 링크를 줄 것이다.

 

@storybook/cli - Storybook

 

그리고 크로마틱에서는 아래와 같은 화면이 나온다.

(물론 이전에 튜토리얼이 나오는데 이를 진행해도 어짜피 deny로 되돌릴 수 있기 때문에 진행해도 상관없다.) 

 

 

크로마틱에서는 처음 배포된 스토리들의 UI를 기준점으로 삼고 이후에 변경사항이 발견될 경우 알려줄 것이다.

 

// .gitignore

# log file
*.log

 

log 파일을 생성하기 때문에 gitignore에 이를 추가해주면 좋다.

실제로 어떻게 작동하는지 테스트를 해보자.

 

 

ExpandTile 컴포넌트의 배경색을 빨간색으로 변경해보았다.

 

npx chromatic --project-token=[프로젝트 토큰]

# script에 chromatic 명령어를 추가한 경우
yarn chromatic

 

이후 위 명령어를 통해 다시 스토리북을 크로마틱으로 빌드해준다.

 

 

그러면 CLI에서 UI 변경사항이 발생했으니 리뷰가 필요하다며 에러를 낸다.

크로마틱에 들어가보면 아래와 같이 새로운 빌드가 나와있음을 알 수 있다.

 

 

그리고 각 빌드의 Unreviewed된 부분을 클릭해보면 초록색으로 변경된 부분을 표시해준다.

(이는 diff를 클릭해 끌 수 있다.)

이를 통해 변경사항을 확인하고 Accept와 Deny를 선택해서 이 변경사항을 수용할 것인지, 아닌지를 결정할 수 있게 되었다.

 

 

🏹 CI 통합하기

이제 크로마틱을 통해 UI의 변경사항을 캡쳐하고 이를 Accept할지 Deny할지 결정할 수 있게 되었다.

그런데 필요할 때마다 크로마틱을 통해 스토리북을 수동으로 빌드해야하고, 또 CLI에서 제공해주는 링크를 일일이 들어가야하고...

좀 번거롭지 않은가?

 

이를 위해 스토리북에서는 다양한 CI 도구와 비쥬얼 테스트를 통합할 수 있는 방법을 제공한다.

그 중에서도 이 글에서는 깃허브 액션과 통합해보려한다.

 

 

먼저, 레포지토리의 Settings - Secrets and variables - Actions에 New repository secret 버튼을 눌러 

프로젝트 토큰을 `CHROMATIC_PROJECT_TOKEN`라는 이름으로 추가해준다.

 

//package.json

"scripts": {
  ....,
  "chromatic": "chromatic --exit-zero-on-changes"
},

 

그리고 package.json에 chromatic 명령어를 위와 같이 추가해준다.

(기존에 추가되어있다고 하더라고 명령어가 다르기 때문에 이로 변경해 추가해주어야한다.)

 

# .github/workflows/chromatic.yml

# Workflow name
name: 'Chromatic'

# Event for the workflow
on: push

# List of jobs
jobs:
  chromatic-deployment:
    # Operating System
    runs-on: ubuntu-latest
    # Job steps
    steps:
      - uses: actions/checkout@v1
      - name: Install dependencies
        # 👇 Install dependencies with the same package manager used in the project (replace it as needed), e.g. yarn, npm, pnpm
        run: yarn
        # 👇 Adds Chromatic as a step in the workflow
      - name: Publish to Chromatic
        uses: chromaui/action@v1
        # Chromatic GitHub Action options
        with:
          # 👇 Chromatic projectToken, refer to the manage page to obtain it.
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

 

그리고 프로젝트 최상단에 .github/workflows 폴더 내에 chromatic.yml 파일을 위와 같이 작성해준다.

(위는 yarn 기준)

 

 

그리고 이제 PR을 만들고 코드를 push하면, 위와 같이 CI에서 크로마틱이 동작하는 것을 볼 수 있다.

여기서 UI Tests의 Details를 누르면 크로마틱의 새 빌드 페이지로 이동하여 변경사항을 확인할 수 있다.

 

unreviewed

all accept

deny

그리고 변경사항의 상태에 따라 위와 같이 PR 상에 표시되는 것을 볼 수 있다.

 

 

🐞 버그 : 베이스라인이 업데이트 되지 않는 경우

Chromatic을 통해 시각적 회귀 테스트 파이프라인을 실컷 구축해놓았는데, 

막상 실제로 파이프라인을 실행해보니 기준점인 베이스라인이 최신 상태로 업데이트 되지 않는 문제가 있었다.

문서를 읽어보니 Squash Merge  혹은 Rebase Merge를 통해 기준 브랜치에 머지할 경우

베이스라인이 정상적으로 업데이트가 되지 않을 수 있다고 한다.

이를 해결하기 위해서는 아래와 같이 깃허브 액션 스크립트에 아래 항목을 추가해준다.

 

# .github/workflows/chromatic.yml

name: "Chromatic"

on: push

jobs:
  chromatic-deployment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - name: Install dependencies
        run: yarn
      - name: Publish to Chromatic
        uses: chromaui/action@v1
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          autoAcceptChanges: "master"  # 👈 이 항목에 기준으로 설정할 브랜치 이름 추가

 

이를 통해 Squash Merge나 Rebase Merge로 머지할 경우에도 베이스라인을 최신 상태로 업데이트할 수 있다.

 

🐞 버그 : PR에서 Storybook Publish, UI Test가 나오지 않는 경우

확실한 버그는 아니지만, chistock-ui 프로젝트로 라이브러리들을 이전한 후 chromatic을 다시 세팅했는데

UI 변경사항이 발생했음에도 불구하고 PR에서 이를 pass해주는 경우가 발생했다.

 

 

뭐가 원인인지 찾아보다가 PR에서 원래라면 등장해야하는 Storybook publish와 UI Test 부분이

현재 PR에서 나오지 않는 것을 확인했다.

이를 통해 현재 레포에 Chromatic의 보고가 이루어지지 않는 것이 문제라고 생각했다.

 

 

원인을 찾다가  chromatic 페이지의 Manage에 Collaborate의 Collaborators 부분에서 Github repository 설정이

이전 레포였던 chistock으로 설정되어있는 것을 확인했다.

혹시나 싶어서 chistock-ui로 변경해봤는데 정상적으로 다시 나오는 것을 확인했다....

이런 설정도 중요하구나.....싶었다.

 

 

Reference

Visual tests

Introduction • Chromatic docs