스토리북 튜토리얼

🧸 서론

이전에 진행했던 프로젝트는(현재도 진행중...) CBD(Component Based Development)를 기준으로  진행하였다. 컴포넌트를 하나 하나 확인하기 위해서, layout이라는 폴더를 만들고 그 곳에 필요한 컴포넌트들을 하나 하나 그리다보니 컴포넌트 개발이나 그리는데 있어 UI와 컴포넌트의 분리가 필요하다는 생각이 들었다. 

Storybook is an open source tool for building UI components and pages in isolation. It streamlines UI development, testing, and documentation.

이를 개선하기 위해서 스토리북을 공부하고 적용하기로 했다.

 

🥄설치

스토리북 설치를 하기 위해서는 다음과 같은 커맨드를 사용해야한다.

npx sb init

이 커맨드가 끝나고 나면, package.json scripts에 다음과 같은 script가 추가된다.

  "scripts": {
	...
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build"
    ...
  },

우리는 스토리북을 실행하기 위해서 package manager 실행 명령어와 storybook을 사용해야한다(예시 yarn storybook). inquirer를 따라서 localhost:6006(storybook default 주소)로 이동하면 스토리북의 예제가 있는 파일들을 볼 수 있다.

 

⛳️ 추가 설정

지금 스토리북을 적용할 프로젝트는 Styled-components이기 때문에 추가적인 설정이 필요하다.  Styled-components를 적용하기 위해서는 preview.ts(혹은 preview.js)파일을 preview.tsx(preview.js 라면 jsx)로 수정해야한다.

npx sb init를 사용하여 설치하면 preview.ts로 파일이 세팅되어있었다.

파일 이름을 수정하였다면 preview.tsx에 ThemeProvider를 적용한다. 샘플 코드는 https://storybook.js.org/docs/react/writing-stories/decorators 이 주소에서 받을 수 있다.

import React from 'react';

import { Preview } from '@storybook/react';

import { ThemeProvider } from 'styled-components';

const preview: Preview = {
  decorators: [
    (Story) => (
      <ThemeProvider theme="default">
        {/* 👇 Decorators in Storybook also accept a function. Replace <Story/> with Story() to enable it  */}
        <Story />
      </ThemeProvider>
    ),
  ],
};

export default preview;

본인이 적용한 테마가 있다면 위으 코드에서 theme={theme} 과 같이 불러올 수 있다.

import React from 'react';

import { Preview } from '@storybook/react';

import { ThemeProvider } from 'styled-components';

import { theme} from "../src/constants";

const preview: Preview = {
  decorators: [
    (Story) => (
      <ThemeProvider theme={theme}>
        <Story />
      </ThemeProvider>
    ),
  ],
};

export default preview;

(지금은 alias를 적용하지 않았기 때문에 theme의 주소는 ..으로 작성되어있다)

 

🥊 컴포넌트 개발하기

🤹‍♀️ 파일 구조

위에 있는 인스타그램의 "생각을 공유해보세요" 말풍선을 스토리북을 이용하여 만들어 보자. 이 컴포넌트의 이름이 MyMemo라고 하면, 컴포넌트와 관련된 파일은

• MyMemo.tsx
• MyMemo.stories.tsx

두 가지 파일이 기본으로 필요하다. 하지만, styled-components 같은 경우 함수적인 기능의 semantic을 가지고 있지 않기 때문에 이를 MyMemo.styles.tsx파일과 타입이 필요한 경우를 고려하여 MyMemo.d.ts 파일을 추가하였다.

• MyMemo.tsx
• MyMemo.stories.tsx
• MyMemo.styles.tsx
• MyMemo.d.ts

🎮 스토리북 controls

우선 컴포넌트 개발에서는 상황에 따라 컴포넌트가 어떤 식으로 그려지는가를 보는 것이 중요하기 때문에 위의 컴포넌트를

• 로그인이 된 케이스
• 로그인이 안된 케이스

두 가지 케이스로 분리를 하여 진행을 할 예정이다.

리액트에서는

• state마다 다른 컴포넌트로 컴포넌트 그리기
• 다른 props를 내려서 같은 컴포넌트를 다른 방식으로 그리기

두 가지 방식이 존재한다. state 마다 다른 컴포넌트로 그려지는 방식은 다른 props로 다르게 그려지는 방식의 케이스를 한 개로 그리면 똑같기 때문에 "다른 props를 내려서 같은 컴포넌트를 다른 방식으로 그리는 방식"으로 진행하겠다.

 

Step1. 컴포넌트 Props 정하기

컴포넌트를 만들기 위해서 컴포넌트에 들어오는 타입을 만들어야한다. 지금 만들 컴포넌트는 user가 undefined이거나 object를 만들도록 구현을 하려고 한다.

//MyMemo.d.ts
interface MyMemoProps {
  user: { name: string } | undefined;
}

 

Step2. 컴포넌트 내부에 들어갈 컴포넌트 만들기

컴포넌트를 만들기전에 컴포넌트의 child안에 들어갈 컴포넌트를 만들어야한다. 지금은 우선 간단하게 로그인의 유무에 따라 쉽게 구분을 하기 위하여 배경색을 빨강과 파랑으로 가지는 span을 만들었다.

//MyMemo.styles.tsx
const ProfileIcon = styled.span`
  background-color: blue;
`;
const DefaultIcon = styled.span`
  background-color: red;
`;

 

Step3. props에 따른 컴포넌트 만들기

스토리북 파일을 만들기 전에 user의 값에 따라서 다른 방식으로 그려지도록 컴포넌트를 만든다.(케이스마다 나뉘어지게 먼저 만들고 컴포넌트에 대해서 딥하게 작성하도록한다)

export function MyMemo(props: MyMemoProps) {
  const { user } = props;
  return <>{user ? <ProfileIcon>아이콘</ProfileIcon> : <DefaultIcon >아이콘</DefaultIcon >}</>;
}

 

Step4. Storybook 파일 만들기

4.1  기본 컴포넌트 설정하기

스토리북에서 만든 컴포넌트를 보기 위하여 [컴포넌트이름].stories.tsx에 다음과 같이 컴포넌트와, 스토리북에서 사용할 옵션들을 넣는다.

추가설명 :

• title: 스토리북에서 컴포넌트를 구분하는 이름
• component: title로 분류한 스토리북 페이지에서 사용할 컴포넌트 이름
• tags: ["autodocs"] 스토리북에서 여러 케이스와 사용방법을 설명해주는 문서를 자동으로 만들어 줄지에 관한 옵션
• parameters: { layout: "fullscreen" | "centered"}: 스토리북 페이지의 화면에 관련된 설정 

const meta: Meta<typeof MyMemo> = {
  title: "MyMemo component",
  component: MyMemo,
  // This component will have an automatically generated Autodocs entry: https://storybook.js.org/docs/react/writing-docs/autodocs
  tags: ["autodocs"],
  parameters: {
    // More on how to position stories at: https://storybook.js.org/docs/react/configure/story-layout
    layout: "fullscreen",
  },
};
export default meta;

 

4.2 스토리북 케이스 만들기

export const LoggedIn: UserData = {
  args: {
    user: {
      name: "Mesher",
    },
  },
};

export const LoggedOut: UserData = { args: { user: undefined } };

 

전체 코드

import type { Meta, StoryObj } from "@storybook/react";
import { MyMemo } from "./MyMemo";

type UserData = StoryObj<typeof MyMemo>;

const meta: Meta<typeof MyMemo> = {
  title: "MyMemo component",
  component: MyMemo,
  // This component will have an automatically generated Autodocs entry: https://storybook.js.org/docs/react/writing-docs/autodocs
  tags: ["autodocs"],
  parameters: {
    // More on how to position stories at: https://storybook.js.org/docs/react/configure/story-layout
    layout: "fullscreen",
  },
};
export default meta;
export const LoggedIn: UserData = {
  args: {
    user: {
      name: "Mesher",
    },
  },
};

export const LoggedOut: UserData = { args: { user: undefined } };

 

🤾‍♂️ 스토리북 Play Function

Step1. 플러그인 설치

스토리북 Play Function을 사용하기 위해서는 스토리북에서 제공하는 interaction 플러그인을 설치해야한다.

//yarn
yarn add --dev @storybook/testing-library @storybook/jest @storybook/addon-interactions

//npm
npm install @storybook/testing-library @storybook/jest @storybook/addon-interactions --save-dev

//pnpm
pnpm add --save-dev @storybook/testing-library @storybook/jest @storybook/addon-interactions

 

Step2. addon 추가

.storybook/main.ts 파일의 addon props에 @storybook/addon-interactions가 있는지 확인해야한다.

// .storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    // Other Storybook addons
    '@storybook/addon-interactions', // 이 부분이 필수로 필요하다.
  ],
};

export default config;

 

Step3. 컴포넌트 작성

Play Function을 사용하기 위해서 컴포넌트를 작성하자. 우선 이 글은 튜토리얼이기 때문에 어려운 컴포넌트를 만들고 그 컴포넌트에 대한 Interaction을 만드는 것보다는 count button을 이용하여 간단한 Interaction을 알아보자.

//CountButton.tsx
import { useState } from "react";

export function CountButton() {
  const [count, setCount] = useState(0);
  const onClickHandler = () => setCount((count) => count + 1);
  return (
    <>
      <button onClick={onClickHandler}>{count}</button>
    </>
  );
}

 

Step4. 스토리북 케이스 작성

//CountButton.stories.tsx

import type { Meta, StoryObj } from "@storybook/react";
import { CountButton } from "./CountButton";
import { fireEvent, userEvent, within } from "@storybook/testing-library";
type Story = StoryObj<typeof CountButton>;

const meta: Meta<typeof CountButton> = {
  title: "CountButton component",
  component: CountButton,
  tags: ["autodocs"],
  parameters: {
    layout: "fullscreen",
  },
};
export default meta;

export const CountButtonExample = { args: {} };
export const ClickOnceExample: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    await userEvent.click(canvas.getByRole("button"));
  },
};

다음과 같은 예제에서는 CountButtonExample을 이용하여 컴포넌트를 체험해 볼 수 있고, ClickOnceExample을 이용하여 한번 클릭이 되었을 때를 확인할 수 있다. 위의 예제를 이용하면

export const ClickExample: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    function sleep(ms: number) {
      return new Promise((resolve) => setTimeout(resolve, ms));
    }
    async function clicked() {
      await fireEvent.click(canvas.getByRole("button"));
      await sleep(50);
    }
    await Array(1000).fill(0).reduce(async (prev, current) => {
      const previousPromise = await prev.then();
      await func(current);
      return Promise.resolve(previousPromise)
      await clicked();
    }, Promise.resolve());   
  },
};

클릭을 100번을 하기 힘든 경우 이를 대신해줄 수 있는 UI테스트의 결과를 보여줄 수있는 스토리북페이지를 만들 수 있다.

여기서 한 가지 주의 할 것이 있다면, async와 await는 forEach, map와 사용해도 아무런 효과가 없다는 것을 기억하자. 만일 같은 이벤트를 혹은 순환하면서 함수를 사용하고 싶다면 reduce와 reduce 내부에 있는 누적된 값을 await시켜서 함수가 하나가 끝날 때마다 다음 함수를 적용하는 것이 좋다.

 

🔚 마무리

이 글에서는 스토리북을 이용하여 두가지를 알아보았다.

1. 스토리북을 이용하여 Props에 따라 어떤 방식으로 그려지는지

2. 스토리북을 이용하여 이벤트의 UI테스트 결과를 보기

한 번 정해진 이벤트와 에러케이스에 대해서는 결과를 바로 보거나 어떤 식으로 그려지는지 알 수 있기 때문에 스토리북을 이용하면 QA시간을 단축시켜줄 수 있을 것 같다. 오늘은 클릭 이벤트만 올려두었지만 시간이 되는대로 다른 이벤트에 관련된 글을 추가로 작성하거나 이 글에 수정해서 넣어야겠다.

 

나중에는 스토리북의 이벤트를 잘다룰 수 있다면 다음과 같이 작업할 수 있지 않을까...?

출처(https://storybook.js.org/docs/react/writing-tests/interaction-testing)