컴포넌트 테스트

컴포넌트 테스트(Component Testing)는 UI 컴포넌트가 독립적으로 올바르게 렌더링되는지, 상호작용에 따라 예상대로 동작하는지, props에 맞는 화면을 표시하는지를 검증하는 데 집중합니다.

단위 테스트와 비슷하지만, 내부 로직뿐 아니라 시각적 출력과 사용자 경험까지 함께 본다는 점에서 더 넓은 범위의 테스트입니다.

Next.js에서는 React 컴포넌트가 핵심 빌딩 블록이므로 컴포넌트 테스트가 애플리케이션 안정성과 UI 품질을 좌우합니다.

이 절에서는 @testing-library/react + Jest 조합과 Cypress 컴포넌트 테스트 활용 방법을 비교하고, 효과적인 테스트 작성 전략을 정리합니다.

컴포넌트 테스트의 중요성

컴포넌트 테스트는 props, 사용자 이벤트, 렌더링 결과를 한 단위로 묶어 검증합니다.

• 독립적인 UI 검증: 컴포넌트가 다른 컴포넌트나 백엔드 의존성 없이 독립적으로 올바르게 동작하는지 확인합니다. 이는 복잡한 애플리케이션에서 특정 UI 문제가 발생했을 때 문제의 원인을 신속하게 파악하는 데 도움을 줍니다.
• 렌더링 회귀 방지: 컴포넌트의 props나 상태가 변경될 때 텍스트, 역할, 상호작용 결과가 의도와 달라지는 회귀를 잡습니다. 픽셀·레이아웃 차이를 비교하는 시각적 회귀 검사는 별도의 스크린샷 도구가 필요합니다.
• 재사용성 향상: 테스트 가능한 컴포넌트는 일반적으로 잘 정의된 인터페이스를 가지며, 이는 컴포넌트의 재사용성을 높이는 데 기여합니다.
• 개발 속도 향상: 컴포넌트를 변경할 때마다 전체 애플리케이션을 실행하거나 브라우저에서 수동으로 확인하는 대신, 빠르고 자동화된 테스트를 통해 변경 사항의 영향을 즉시 확인할 수 있습니다.
• 동작 문서화: 컴포넌트 테스트는 해당 컴포넌트가 어떤 props를 받고, 어떤 상태에서 어떤 결과를 렌더링해야 하는지 실행 가능한 예시로 남깁니다.

컴포넌트 테스트 도구 선택

Next.js에서 컴포넌트 테스트를 수행하는 데는 주로 두 가지 접근 방식이 있습니다.

대부분의 경우 Jest와 RTL 조합이 컴포넌트 테스트에 가장 널리 사용되며 효율적입니다.

Cypress 컴포넌트 테스트는 특정 시각적 또는 브라우저 관련 문제가 중요할 때 보완적으로 사용될 수 있습니다.

여기서는 Jest와 RTL을 중심으로 설명합니다.

Jest + @testing-library/react

14장 1절 단위 테스트 설정 (Jest)에서 Jest와 @testing-library/react의 설치 및 기본 설정(jest.config.js, jest.setup.ts)은 이미 다루었습니다.

이 절에서는 실제 컴포넌트 테스트 예시를 통해 활용 방법을 심화합니다.

테스트할 컴포넌트 예시

버튼을 클릭하면 숫자가 증가/감소하는 간단한 카운터 컴포넌트를 테스트합니다.

"use client"; // 클라이언트 컴포넌트

import React, { useState } from 'react';

export default function Counter() {
  const [count, setCount] = useState(0);

  const increment = () => setCount(prev => prev + 1);
  const decrement = () => setCount(prev => prev - 1);

  return (
    <div style={{ padding: '20px', border: '1px solid #00BCD4', borderRadius: '8px', textAlign: 'center' }}>
      <h2 style={{ color: '#00BCD4' }}>카운터</h2>
      <p style={{ fontSize: '2.5em', margin: '20px 0' }} data-testid="count-value">
        {count}
      </p>
      <div style={{ display: 'flex', justifyContent: 'center', gap: '15px' }}>
        <button
          onClick={decrement}
          style={{ padding: '10px 20px', fontSize: '1.2em', backgroundColor: '#FF5722', color: 'white', border: 'none', borderRadius: '5px', cursor: 'pointer' }}
        >
          감소
        </button>
        <button
          onClick={increment}
          style={{ padding: '10px 20px', fontSize: '1.2em', backgroundColor: '#4CAF50', color: 'white', border: 'none', borderRadius: '5px', cursor: 'pointer' }}
        >
          증가
        </button>
      </div>
    </div>
  );
}

Counter 컴포넌트 테스트 작성

import React from 'react';
import { render, screen, fireEvent } from '@testing-library/react'; // RTL 유틸리티 임포트
import Counter from '../components/Counter'; // 테스트할 컴포넌트 임포트

describe('Counter 컴포넌트', () => {
  test('초기 카운트 값은 0이어야 합니다.', () => {
    render(<Counter />); // Counter 컴포넌트를 렌더링합니다.

    // data-testid로 요소를 찾고 텍스트 내용이 '0'인지 확인합니다.
    expect(screen.getByTestId('count-value')).toHaveTextContent(/^0$/);
  });

  test('증가 버튼 클릭 시 카운트 값이 1 증가해야 합니다.', () => {
    render(<Counter />);

    const incrementButton = screen.getByRole('button', { name: '증가' }); // '증가' 텍스트를 가진 버튼을 찾습니다.
    fireEvent.click(incrementButton); // 버튼 클릭 이벤트를 발생시킵니다.

    // 카운트 값이 '1'로 변경되었는지 확인합니다.
    expect(screen.getByTestId('count-value')).toHaveTextContent(/^1$/);
  });

  test('감소 버튼 클릭 시 카운트 값이 1 감소해야 합니다.', () => {
    render(<Counter />);

    const decrementButton = screen.getByRole('button', { name: '감소' }); // '감소' 텍스트를 가진 버튼을 찾습니다.
    fireEvent.click(decrementButton); // 버튼 클릭 이벤트를 발생시킵니다.

    // 카운트 값이 '-1'로 변경되었는지 확인합니다.
    expect(screen.getByTestId('count-value')).toHaveTextContent(/^-1$/);
  });

  test('증가 후 감소 버튼을 클릭하면 초기값으로 돌아와야 합니다.', () => {
    render(<Counter />);

    const incrementButton = screen.getByRole('button', { name: '증가' });
    const decrementButton = screen.getByRole('button', { name: '감소' });

    fireEvent.click(incrementButton); // 0 -> 1
    expect(screen.getByTestId('count-value')).toHaveTextContent(/^1$/);

    fireEvent.click(decrementButton); // 1 -> 0
    expect(screen.getByTestId('count-value')).toHaveTextContent(/^0$/);
  });
});

각 테스트는 새 Counter를 0에서 시작합니다. 숫자는 전체 문자열을 비교해야 1을 기대하는 검사가 10이나 -1을 통과시키지 않습니다. toHaveTextContent 부분 일치 규칙

새 순서를 직접 확인하기 새 Counter에서 증가 두 번과 감소 한 번을 실행하면 어떤 문자열을 기대해야 할까요? 이어서 별도 테스트가 Counter를 새로 렌더링하면 시작값은 무엇인가요? 기대값을 /1/로 쓰면 10과 -1도 일치하는지 확인해 보세요.

• render(<Component />): 컴포넌트를 JSDOM 환경에 렌더링하고, 렌더링된 컴포넌트와 상호작용할 수 있는 쿼리 함수들을 반환합니다.
• screen: @testing-library/react에서 별도로 import하는 문서 전체 쿼리 객체입니다. render가 DOM을 준비한 뒤 screen.getByRole()처럼 사용합니다. 특정 렌더 컨테이너에만 질의하려면 render의 반환값이나 within을 사용합니다.
• 쿼리 함수: @testing-library/react는 컴포넌트의 내부 구현(state, props)이 아닌, 사용자가 화면에서 실제로 보고 상호작용하는 방식으로 요소를 찾는 다양한 쿼리 함수를 제공합니다.
  • getByRole(): 접근성 트리를 기반으로 요소를 찾습니다. 가장 권장되는 방법입니다 (예: button, heading, textbox).
  • getByText(): 텍스트 내용으로 요소를 찾습니다.
  • getByTestId(): data-testid 속성을 사용하여 요소를 찾습니다. DOM에 테스트 전용 식별자를 추가하는 방식이므로 역할·이름으로 구분하기 어려운 요소에 사용합니다.
• fireEvent.click(): 특정 요소에 클릭 이벤트를 발생시킵니다. fireEvent 외에도 user-event 라이브러리가 사용자 행동을 실제와 더 가깝게 모방합니다 (예: user.type, user.click). npm install --save-dev @testing-library/user-event로 설치하여 사용할 수 있습니다.
• expect().toHaveTextContent(), expect().toBeInTheDocument(): Jest의 매처와 @testing-library/jest-dom의 확장 매처를 사용하여 렌더링된 DOM 요소의 속성을 검증합니다.

컴포넌트 테스트 시 고려사항 및 팁

• 테스트의 격리: 각 컴포넌트 테스트는 독립적이어야 합니다. 한 테스트의 결과가 다른 테스트에 영향을 주지 않도록 beforeEach나 afterEach 훅을 사용하여 상태를 초기화하거나 정리합니다.
• 모킹 활용: 컴포넌트가 외부 API 호출, 전역 상태 관리(Redux, Zustand), Context API 등 외부 의존성을 가진다면, Jest의 모킹 기능을 사용하여 이러한 의존성을 격리합니다.
  • Context 모킹: 테스트 렌더링 시 컴포넌트를 MyContext.Provider로 감싸서 모킹된 값을 제공합니다.
  • 훅 모킹: jest.mock()을 사용하여 특정 훅(예: useRouter)을 모킹하여 제어된 값을 반환하도록 합니다.
• Server Components의 제한: Jest는 async Server Component를 직접 지원하지 않습니다. 동기 Server Component까지 모두 지원하지 않는다는 뜻은 아닙니다. Next.js의 Jest 지원 범위 Server Components가 데이터를 가져와 클라이언트 컴포넌트에 props로 전달하는 패턴이라면, 클라이언트 컴포넌트를 테스트하면서 props로 전달되는 데이터를 모킹하는 방식으로 접근합니다.
• CSS Modules/Tailwind CSS: 앞에서 사용한 next/jest가 CSS·Sass와 CSS Module을 자동으로 모킹하므로 별도의 identity-obj-proxy 설정이 필요하지 않습니다. 직접 module.exports를 새 객체로 덮어쓰면 Next.js의 SWC 변환과 이미지·폰트 모킹 설정을 잃을 수 있으므로, 추가 옵션이 필요할 때만 기존 customJestConfig에 병합합니다.
• 스냅샷 테스트 (Snapshot Testing): React 19에서 deprecated된 react-test-renderer 대신 React Testing Library의 asFragment()를 사용할 수 있습니다. 하지만 스냅샷은 의도를 명확히 드러내기 어려우므로 작은 안정적 출력에만 보조적으로 사용합니다.

  import { render } from '@testing-library/react';
  import MyComponent from '../components/MyComponent';
  
  test('MyComponent matches snapshot', () => {
    const { asFragment } = render(<MyComponent prop1="value" />);
    expect(asFragment()).toMatchSnapshot();
  });

• 테스트 커버리지: Jest는 테스트 커버리지 보고서를 생성하는 기능을 제공합니다. 이를 통해 테스트되지 않은 코드 부분을 파악하고 테스트를 보강할 수 있습니다. (jest.config.js의 collectCoverage 옵션)

텍스트·상태·이벤트는 Jest/RTL로 확인하고 실제 레이아웃이나 브라우저 API는 Cypress CT 같은 브라우저 실행에서 확인합니다. CT는 전체 Next 서버 실행과 같지 않으므로 서버 데이터 로딩까지 연결한 페이지는 별도 E2E 범위로 둡니다. 실패한 테스트에는 입력 prop, 사용자 동작, 기대 DOM과 대역 의존성을 남깁니다.