Storybook 에서 컴포넌트 단위 테스트하기

 

📌 들어가며

스토리북은 component driven development 패러다임을 위한 유용한 개발 도구로

단순히 UI 를 확인하는 용도를 넘어서서 테스트를 위한 다양한 솔루션도 함께 제공해주고 있습니다.

이번 포스트에서는 이를 활용한 테스트 적용 사례에 대해 살펴보고자합니다.

우선 이번 포스트를 위한 프로젝트의 패키지 버전 정보는 다음과 같습니다.

📦 project dependency

- react/react-dom: 17.0.2
- next: 12.1.1
- storybook: 7.0.4
- typescript: 5.0.3

 

✨ Next.js + jest & storybook 설정하기

📌 Next.js + jest 설정

유닛테스트, 스냅샷테스트 작성하기 전에 jest 먼저 설치합니다.

Next.js v12 를 TypeScript 와 함께 사용하고 있기 때문에 이와 맞는 설정을 진행합니다.

Next.js v12 부터는 Babel 대신 swc 를 활용한 설정을 하면 됩니다.

 

Testing | Next.js

Optimizing: Testing | Next.js

 

필요한 패키지 설치

npm i -D jest @types/jest
npm i -D jest-environment-jsdom
npm i -D @testing-library/jest-dom
npm i -D @testing-library/react // ✅ NOTE: 프로젝트에서 사용하고 있는 react 버전에 호환되는 버전으로 설치

 

• @testing-library/jest-dom
  • DOM 테스트를 위한 유용한 custom matcher 들을 제공
• @testing-library/react
  • React DOM 및 hook 테스트를 위한 유용한 유틸리티 함수들 제공 (render, act, renderHook)

Jest 설정 추가

// jest.config.js

/** @type {import('ts-jest').JestConfigWithTsJest} */

const nextJest = require('next/jest.js')

const createJestConfig = nextJest({
  dir: './',
})

/** @type {import('jest').Config} */
const config = {
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  testEnvironment: 'jest-environment-jsdom',
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/src/$1',
  },
}

module.exports = createJestConfig(config)

 

Jest 실행시에 가장 먼저 실행된 task 를 등록할 설정파일을 추가합니다.

여기서 jest-dom 라이브러리를 불러옵니다.

 

// jest.setup.js

import '@testing-library/jest-dom'

// tsconfig.json

{
    "compilerOptions": {
        "types": ["jest"], // ✅ 
    }
}

 

📌 Next.js + Storybook 7 설정

먼저 프로젝트에 스토리북 설정을 해줍니다.

storybook cli 를 이용하면 현재 프로젝트에 가장 적합한 설정을 자동으로 해줍니다.

 

> npx storybook@latest init // 현재 최신버전 기준으로 storybook@7.0.4가 설치됩니다.ㄱ

 

그리고 CSF3 포맷으로 스토리 파일을 작성합니다.

 

import type { Meta, StoryObj } from '@storybook/react'

import MOCK_TRANSACTION from '@/__mock__/ready.transaction.json'

import OrderItem from './order-items'

const meta: Meta<typeof OrderItem> = {
  title: 'Element / Order Item',
  component: OrderItem,
}

export default meta

export const Basic: StoryObj<typeof OrderItem> = {
  render: (args) => <OrderItem {...args} />,
  args: {
    items: MOCK_TRANSACTION.cart.items,
  },
}

만약 Context Provider 가 필요하다면

일부 컴포넌트들에서 provider injection 이 필요한 경우가 있습니다.

전역적으로 설정이 필요한 것들은 preview.tsx 에 스토리별로 추가가 필요한 것은 개별 스토리파일에 decorator 로 추가해줍니다.

 

✨ storybook 를 활용한 컴포넌트 테스트

설정을 마쳤으니 이제 본격적으로 테스트 코드를 작성해봅니다.

📌 유닛 테스트

testing-library 와 함께 @storybook/react 에서 제공하고 있는 API들을 함께 활용하면

이미 작성해놓은 story 파일을 재사용한 테스트 코드 작성이 가능합니다.

 

💡 ⚠️ 주의!
Storybook 7 부터는 @storybook/react 패키지에 @storybook/testing-react(https://storybook.js.org/addons/@storybook/testing-react) 가 내장되어서 이제는 별도 설치가 필요없습니다.

다음은 스토리파일을 이용해서 작성한 Jest 테스트코드 예시입니다.

스토리 컴포넌트에서 사용한 mock 데이터를 그대로 재활용 가능합니다.

import { render } from '@testing-library/react'
import { composeStories } from '@storybook/react'

import * as stories from './radio-box.stories'

const { Basic } = composeStories(stories)

describe('<RadioBox />', () => {
  it('should render 4 payment option', () => {
    const { getAllByTestId } = render(<Basic />)

    const options = getAllByTestId('radio-option')

    expect(options).toHaveLength(4)
  })

  it('should highlight selected option', () => {
    const { getAllByTestId } = render(<Basic />)

    const creditOption = getAllByTestId('radio-option')[0]

    expect(creditOption).toHaveStyle('border: solid 1.2px #368fff;')
  })
})

 

📌 스냅샷 테스트

시각 테스트(visual test) 혹은 시각적 회귀 테스트(visual regression test) 는 코드 수정에 따른 UI 버그를 관리하는 좋은 테스트 방법입니다.

이 테스트 방식에서는 스토리 파일의 스크린샷을 비교하여 UI 의 변경사항을 추적합니다.

스토리북은 클라우드 호스팅 방식의 chromatic 과 self-managed 방식의 StoryShots 를 활용하는 두 가지 옵션을 제공하는데,

저는 사이드 프로젝트에서 ci workflow 에서 chromatic 자동화 테스트 단계를 추가해서 사용하고 있습니다.

개인적인 의견으로 chromatic 이 스냅샷 비교 및 빌드 히스토리를 관리하는데 용이하다고 느꼈습니다. 😄

Storybook Tutorials

Storybook Tutorials

 

📌 interaction 테스트

스토리북 6.4 부터 공식적으로 interaction stories 라는 기능을 활용할 수 있게 되었습니다.

interaction test vs jest dom testing

이쯤에서 interaction test 가 Jest DOM 테스트를 대체하는 것일까? 하는 의문이 드는데요.

이와 관련해서 메인테이너의 의견이 있습니다.

Use the test runner in most cases
Use Jest/JSDOM (or the tool of your choice)
    * If you prefer another testing mechanism
    * If there are certain kinds of setup/teardown that you can't achieve with the test runner

Storybook Interactions - a replacement for Jest DOM testing? · storybookjs/storybook · Discussion #16861

Storybook Interactions - a replacement for Jest DOM testing? · storybookjs/storybook · Discussion #16861

유저 인터렉션이 포함되어 테스트를 작성하기 까다롭거나, Jest DOM 의 구현 한계점으로 인해

실제 브라우저환경에서 컴포넌트 단위로 테스트를 수행해야하는 경우에는 interaction test 를 활용하고

그 외에는 선호방식에 따라 Jest DOM 을 활용하여 테스트를 수행하면 될 것 같습니다.

 

interaction test 를 직접 사용해보니, 실제 브라우저에서 시각적인 디버깅이 가능한 것이 좀 더 편리한 것 같습니다.

다만 interaction test 가 실제 브라우저를 활용하여 테스트를 실행하기 때문에

테스트 실행에 필요한 시간이 조금 더 걸린다는 것도 유의할 필요가 있을 것 같습니다.

 

모든 유닛 테스트 로직을 전부 대체하기보다는 두 테스트 방식의 지원범위에 근거해

상황에 맞게 두 테스트 도구를 적절히 활용하면 좋을 것 같네요 😀

 

패키지 설치

npm i -D @storybook/testing-library
npm i -D @storybook/jest
npm i -D @storybook/addon-interactions 

 

• @storybook/testing-library
  • interaction addon 과 함께 사용하기 위한 testing-library instrument 버전
• @storybook/jest
  • storybook interaction 을 위한 jest integration 패키지

 

main.ts 설정 추가하기

// .storybook/main.ts

const config: StorybookConfig = {
  // ...
  addons: [
    // .. Other Storybook addons
    '@storybook/addon-interactions', // 👈 Register the addon
  ],
};

 

그럼 위에서 작성한 unit test 를 interaction test 로 바꿔봅시다.

 

import { within } from '@storybook/testing-library';
import { expect } from '@storybook/jest';

export const Basic: StoryObj<typeof RadioBox> = {
  // ...
  play: async ({ canvasElement, step }) => {
    const canvas = within(canvasElement)

    await step('should render 4 payment option', () => {
      const options = canvas.getAllByTestId('radio-option')
      expect(options).toHaveLength(4)
    })
  },
}

 

play function 은 렌더링된 컴포넌트의 동작(interaction) 을 테스트해볼 수 있는 기능을 제공합니다.

userEvent 로 event trigger 도 가능합니다.

 

DemoStory.play = async ({ canvasElement }) => {
  const canvas = within(canvasElement)
  const inputElement = canvas.getByRole<HTMLInputElement>('textbox')
  const deleteButton = canvas.getByRole('button')

  await userEvent.type(inputElement, 'test', { delay: 100 })
  expect(inputElement.value).toBe('test')
  await userEvent.click(deleteButton)
}

 

이를 활용하면 다음과 같은 인터렉션 테스트도 가능합니다.

 

 

📌 Storybook test runner

Storybook test runner 는 우리가 작성한 스토리들을 실행 가능한 테스트로 변환해줍니다.

스토리가 잘 노출되는지, 그리고 스토리의 interaction test 가 올바르게 수행되는지 확인할 수 있습니다.

test runner 패키지를 설치해줍니다.

 

> npm i -D @storybook/test-runner

 

그리고 테스트 실행을 위한 script 를 추가해줍니다.

 

// package.json

{
  "scripts": {
    "storybook:test": "test-storybook"
  }
}

 

test runner 는 항상 스토리북이 실행중인 상태에서 실행되어야합니다.

따라서 먼저 스토리북을 실행시킨 다음, 위 task 를 실행해주세요!

 

배포되지 않은 스토리북을 CI 환경에서 test runner 와 함께 실행하기

기본적으로 Storybook test runner 는 storybook 서버가 실행된 상태에서 사용이 가능합니다.

때문에 CI 환경에서는 별도의 프로세스에서 스토리북을 빌드하고, 이를 이용해 정적 파일을 서빙하는 서버를 실행시킨 뒤에 테스트를 수행해야합니다.

이 과정을 도와줄 패키지(concurrently)를 설치합니다.

 

npm i -D concurrently

 

CI 를 위한 run script 를 추가한 뒤에 로컬에서 실행해봅니다.

 

// package.json

scripts: {
    "storybook:test": "test-storybook",
  "storybook:build": "storybook build",
  "storybook:ci": "concurrently -k -s first -n \"SB,TEST\" -c \"magenta,blue\" \"npm run storybook:build --quiet && npx http-server storybook-static --port 6006 --silent\" \"wait-on tcp:6006 && npm run storybook:test --maxWorkers=2\"",
}

> npm run storybook:ci

 

잘 되는군요 😄

 

이제 각자 사용하는 CI 환경에 맞게 파이프라인을 추가해줍니다.

저는 Github Action 을 사용하고 있기 때문에 다음과 같이 추가해줬습니다.

 

steps:
    - name: storybook test
    run: npm run storybook:ci

 

📌 storybook msw addon

스토리에서 테스트가 필요한 컴포넌트가 외부 API 의 데이터에 의존하고 있다면 어떻게 할까요?

모킹된 데이터를 반환하도록 fetch 를 감싸는 방법도 있겠지만, 모든 fetch 마다 이 과정이 필요합니다.

대신에 msw 를 이용해서 API 모킹이 필요한 endpoint 를 추가해주는 방향이 유지관리에 좀 더 용이합니다.

1️⃣ msw 와 storybook msw addon 설치

먼저 필요한 패키지를 설치합니다.

 

> npm i msw msw-storybook-addon -D

 

msw 는 초기 설정을 위한 script 를 제공해주고 있습니다.

public/ 하위에 msw 사용을 위한 초기 설정을 진행해줍니다.

 

> npx msw init public/

2️⃣ addon 설정

이제 스토리북에서 msw 를 사용하기 위한 설정을 추가해줍니다.

 

// ./storybook/preview.(ts|tsx)

import type { Preview } from '@storybook/react'
import { initialize, mswDecorator } from 'msw-storybook-addon';

initialize() // ✅ Initialize MSW

const preview: Preview = {
  decorators: [mswDecorator, ...] // ✅ serve msw decorator globally
    // ... and other config options
}

export default preview

// ./storybook/main.ts

const config: StorybookConfig = {
  staticDirs: ['../public'], // 👈 Configures the static asset folder in Storybook
    // ... and other config options
};

3️⃣ global msw handler 작성하기

모든 스토리에서 호출이 필요한 API 의 경우 global handler 로 등록해두면 편리합니다.

만약 데이터를 조회하는 /api/get/some/data 라는 API 핸들러가 있다면,

 

// src/mocks/handlers.js

import { rest } from 'msw'

export const handlers = {
  GET_SOME_DATA: rest.get(
    '/api/get/some/data',
    (req, res, ctx) => {
      return res(ctx.status(200), ctx.json({ data: 'some' }))
    },
  ),
}

 

.storybook/preview.js 에서 해당 핸들러를 다음과 같이 global decorator 로 추가하면됩니다.

 

import { handlers } from '../src/mocks/handlers'

const preview: Preview = {
  parameters: {
        msw: {
            handlers: {
                plcc: [handlers.GET_SOME_DATA]    
            }
        }
    }
    // ... and other config options
}

export default preview

4️⃣ 개별 story 마다 msw handler 추가하기

개별 스토리에서 handler 를 정의할 수도 있습니다.

스토리북은 global handler 와 story handler 를 병합해서 API 요청을 처리합니다.

다음은 개별 스토리에서 benefitPromotion 이라는 모킹된 API 를 추가하는 예시입니다.

 

import { handlers } from '@/__mocks__/handlers'

export const Basic: StoryObj<typeof PaymentGateway> = {
    parameters: {
    msw: {
      handlers: {
        benefitPromotion: [handlers.GET_BENEFIT_PROMOTION],
      },
    },
  },
    // ... and other config options
}

5️⃣ API whitelist 추가하기

경우에따라 특정 API 요청을 무시해야하는 경우도 있습니다.

저의 경우 이미지 요청은 별도의 미들웨어에서 처리하고 있었기 때문에,

이미지 URL 형식으로 오는 요청을 무시해주도록 다음 설정을 추가해줬습니다.

 

// .storybook/preview.(ts|tsx)

// ✅ Initialize MSW
initialize({
  onUnhandledRequest: ({ url }) => {
    if (url.pathname.startsWith('/payment/static/images')) {
      return // storybook middleware 에서 처리하고 있기 때문에 무시합니다.
    }
  },
})

 

📌 참고자료

Mock Service Worker Addon | Storybook: Frontend workshop for UI development

Import stories in tests

Visual tests