React Testing Library 실전 테스트 전략: 현업에서 써본 효과적인 컴포넌트 테스트 패턴

// 기존 Enzyme 방식 (구현에 의존적)
import { shallow } from 'enzyme';

describe('UserProfile', () => {
  it('should show user name', () => {
    const wrapper = shallow(<UserProfile user={mockUser} />);
    // ❌ 내부 구현에 의존적인 테스트
    expect(wrapper.find('.user-name').text()).toBe('John Doe');
    expect(wrapper.state('loading')).toBe(false); // ❌ state 테스트
  });
});

# React 18+ 환경에서 최신 버전 설치
npm install --save-dev @testing-library/react @testing-library/dom
npm install --save-dev @testing-library/jest-dom @testing-library/user-event
npm install --save-dev msw

# React 17 이하 버전용
npm install --save-dev @testing-library/react@12

// jest.config.js
module.exports = {
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['<rootDir>/src/setupTests.js'],
  moduleNameMapping: {
    '^@/(.*)$': '<rootDir>/src/$1',
    '\\.(css|less|scss|sass)$': 'identity-obj-proxy',
  },
  collectCoverageFrom: [
    'src/**/*.{js,jsx,ts,tsx}',
    '!src/**/*.d.ts',
    '!src/index.js',
  ],
  testMatch: [
    '<rootDir>/src/**/__tests__/**/*.{js,jsx,ts,tsx}',
    '<rootDir>/src/**/*.{spec,test}.{js,jsx,ts,tsx}',
  ],
  transform: {
    '^.+\\.(js|jsx|ts|tsx)$': 'babel-jest',
  },
};

// src/setupTests.js
import '@testing-library/jest-dom';
import { server } from './mocks/server';

// MSW 서버 설정
beforeAll(() => server.listen());
afterEach(() => {
  server.resetHandlers();
  // 각 테스트 후 DOM 정리
  document.body.innerHTML = '';
});
afterAll(() => server.close());

// 전역 설정
global.ResizeObserver = jest.fn().mockImplementation(() => ({
  observe: jest.fn(),
  unobserve: jest.fn(),
  disconnect: jest.fn(),
}));

// matchMedia mock (차트 라이브러리 등에서 필요)
Object.defineProperty(window, 'matchMedia', {
  writable: true,
  value: jest.fn().mockImplementation(query => ({
    matches: false,
    media: query,
    onchange: null,
    addListener: jest.fn(),
    removeListener: jest.fn(),
    addEventListener: jest.fn(),
    removeEventListener: jest.fn(),
    dispatchEvent: jest.fn(),
  })),
});

// ✅ 권장되는 쿼리 우선순위
import { render, screen } from '@testing-library/react';
import { UserProfile } from './UserProfile';

describe('UserProfile', () => {
  const mockUser = {
    name: 'John Doe',
    email: 'john@example.com',
    role: 'developer',
  };

  beforeEach(() => {
    render(<UserProfile user={mockUser} />);
  });

  it('사용자 정보를 올바르게 표시한다', () => {
    // ✅ 1순위: Accessible to everyone (role, label)
    expect(screen.getByRole('heading', { name: /user profile/i })).toBeInTheDocument();
    expect(screen.getByLabelText(/email address/i)).toHaveValue('john@example.com');

    // ✅ 2순위: Semantic queries (text content)
    expect(screen.getByText('John Doe')).toBeInTheDocument();
    expect(screen.getByText(/developer/i)).toBeInTheDocument();

    // ✅ 3순위: Test IDs (최후 수단)
    expect(screen.getByTestId('user-avatar')).toBeInTheDocument();
  });
});

// ✅ userEvent를 활용한 현실적인 사용자 상호작용
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { LoginForm } from './LoginForm';

describe('LoginForm', () => {
  it('사용자가 로그인 폼을 제출할 수 있다', async () => {
    const user = userEvent.setup();
    const mockOnSubmit = jest.fn();

    render(<LoginForm onSubmit={mockOnSubmit} />);

    // ✅ 실제 사용자처럼 폼 작성
    await user.type(screen.getByLabelText(/username/i), 'testuser');
    await user.type(screen.getByLabelText(/password/i), 'password123');

    // ✅ 실제 클릭과 동일한 방식
    await user.click(screen.getByRole('button', { name: /login/i }));

    expect(mockOnSubmit).toHaveBeenCalledWith({
      username: 'testuser',
      password: 'password123',
    });
  });

  it('필수 필드가 비어있으면 에러를 표시한다', async () => {
    const user = userEvent.setup();

    render(<LoginForm onSubmit={jest.fn()} />);

    // 빈 폼으로 제출 시도
    await user.click(screen.getByRole('button', { name: /login/i }));

    // 접근성을 고려한 에러 메시지 확인
    expect(screen.getByRole('alert')).toHaveTextContent(/username is required/i);
  });
});

// ✅ 비동기 상태 변화를 올바르게 테스트
import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { ProductList } from './ProductList';

describe('ProductList', () => {
  it('제품 목록을 비동기로 로드한다', async () => {
    render(<ProductList />);

    // 로딩 상태 확인
    expect(screen.getByText(/loading/i)).toBeInTheDocument();

    // ✅ findBy는 자동으로 비동기 대기
    const firstProduct = await screen.findByText('iPhone 14');
    expect(firstProduct).toBeInTheDocument();

    // 로딩 상태가 사라졌는지 확인
    expect(screen.queryByText(/loading/i)).not.toBeInTheDocument();
  });

  it('검색 결과를 실시간으로 필터링한다', async () => {
    const user = userEvent.setup();
    render(<ProductList />);

    // 초기 데이터 로드 대기
    await screen.findByText('iPhone 14');

    const searchInput = screen.getByPlaceholderText(/search products/i);
    await user.type(searchInput, 'iPhone');

    // ✅ waitFor로 복잡한 비동기 조건 대기
    await waitFor(() => {
      expect(screen.queryByText('Samsung Galaxy')).not.toBeInTheDocument();
    });

    expect(screen.getByText('iPhone 14')).toBeInTheDocument();
  });
});

// tests/test-utils.js
import { render as rtlRender } from '@testing-library/react';
import { BrowserRouter } from 'react-router-dom';
import { QueryClient, QueryClientProvider } from 'react-query';
import { ThemeProvider } from 'styled-components';

// ✅ 실무에서 자주 사용되는 커스텀 렌더 함수
function render(
  ui,
  {
    preloadedState = {},
    store = createStore(preloadedState),
    theme = lightTheme,
    route = '/',
    ...renderOptions
  } = {}
) {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: { retry: false },
      mutations: { retry: false },
    },
  });

  function Wrapper({ children }) {
    return (
      <BrowserRouter>
        <QueryClientProvider client={queryClient}>
          <ThemeProvider theme={theme}>
            <Provider store={store}>
              {children}
            </Provider>
          </ThemeProvider>
        </QueryClientProvider>
      </BrowserRouter>
    );
  }

  // 초기 라우트 설정
  window.history.pushState({}, 'Test page', route);

  return rtlRender(ui, { wrapper: Wrapper, ...renderOptions });
}

// 자주 사용되는 쿼리들을 재사용 가능하게
export function renderWithProviders(ui, options = {}) {
  return render(ui, options);
}

export * from '@testing-library/react';
export { render };

// ✅ 복잡한 대시보드 컴포넌트 테스트
import { render, screen, waitFor } from './test-utils';
import { Dashboard } from './Dashboard';

describe('Dashboard 컴포넌트', () => {
  it('여러 데이터 소스를 동시에 로드하고 표시한다', async () => {
    render(<Dashboard userId="user123" />);

    // 각 섹션별로 로딩 상태 확인
    expect(screen.getByTestId('stats-loading')).toBeInTheDocument();
    expect(screen.getByTestId('chart-loading')).toBeInTheDocument();
    expect(screen.getByTestId('activities-loading')).toBeInTheDocument();

    // ✅ Promise.all로 여러 비동기 요소 동시 대기
    await waitFor(() => {
      expect(screen.queryByTestId('stats-loading')).not.toBeInTheDocument();
      expect(screen.queryByTestId('chart-loading')).not.toBeInTheDocument();
      expect(screen.queryByTestId('activities-loading')).not.toBeInTheDocument();
    });

    // 실제 데이터 표시 확인
    expect(screen.getByText(/total revenue/i)).toBeInTheDocument();
    expect(screen.getByRole('img', { name: /revenue chart/i })).toBeInTheDocument();
    expect(screen.getByText(/recent activities/i)).toBeInTheDocument();
  });

  it('필터 변경 시 차트가 업데이트된다', async () => {
    const user = userEvent.setup();
    render(<Dashboard userId="user123" />);

    // 초기 로드 대기
    await screen.findByRole('img', { name: /revenue chart/i });

    // 필터 변경
    const filterSelect = screen.getByLabelText(/time period/i);
    await user.selectOptions(filterSelect, 'last-month');

    // 차트 재로딩 확인
    expect(screen.getByTestId('chart-loading')).toBeInTheDocument();

    // 업데이트된 차트 표시 대기
    await waitFor(() => {
      expect(screen.queryByTestId('chart-loading')).not.toBeInTheDocument();
    });

    // 필터가 적용된 결과 확인
    expect(screen.getByText(/last month data/i)).toBeInTheDocument();
  });
});

// ✅ 에러 처리 시나리오 완벽 테스트
import { render, screen } from './test-utils';
import { server } from '../mocks/server';
import { rest } from 'msw';

describe('ProductList 에러 처리', () => {
  it('API 에러 시 사용자에게 적절한 메시지를 표시한다', async () => {
    // API 에러 응답 모킹
    server.use(
      rest.get('/api/products', (req, res, ctx) => {
        return res(
          ctx.status(500),
          ctx.json({ message: 'Internal server error' })
        );
      })
    );

    render(<ProductList />);

    // 에러 메시지 표시 확인
    const errorMessage = await screen.findByRole('alert');
    expect(errorMessage).toHaveTextContent(/something went wrong/i);

    // 재시도 버튼 존재 확인
    expect(screen.getByRole('button', { name: /try again/i })).toBeInTheDocument();
  });

  it('네트워크 에러 시 오프라인 상태를 알린다', async () => {
    // 네트워크 에러 시뮬레이션
    server.use(
      rest.get('/api/products', (req, res, ctx) => {
        return res.networkError('Network error');
      })
    );

    render(<ProductList />);

    const offlineMessage = await screen.findByText(/check your internet connection/i);
    expect(offlineMessage).toBeInTheDocument();
  });

  it('재시도 버튼 클릭 시 데이터를 다시 로드한다', async () => {
    const user = userEvent.setup();

    // 처음에는 에러 발생
    server.use(
      rest.get('/api/products', (req, res, ctx) => {
        return res(ctx.status(500));
      })
    );

    render(<ProductList />);

    // 에러 상태 확인
    await screen.findByRole('alert');

    // 정상 응답으로 변경
    server.use(
      rest.get('/api/products', (req, res, ctx) => {
        return res(ctx.json([{ id: 1, name: 'Test Product' }]));
      })
    );

    // 재시도 버튼 클릭
    const retryButton = screen.getByRole('button', { name: /try again/i });
    await user.click(retryButton);

    // 성공적으로 데이터 로드 확인
    expect(await screen.findByText('Test Product')).toBeInTheDocument();
    expect(screen.queryByRole('alert')).not.toBeInTheDocument();
  });
});

// src/mocks/handlers.js
import { rest } from 'msw';

export const handlers = [
  // ✅ RESTful API 엔드포인트 모킹
  rest.get('/api/products', (req, res, ctx) => {
    const page = req.url.searchParams.get('page') || '1';
    const limit = req.url.searchParams.get('limit') || '10';

    return res(
      ctx.status(200),
      ctx.json({
        data: [
          {
            id: 1,
            name: 'iPhone 14',
            price: 999,
            category: 'electronics',
          },
          {
            id: 2,
            name: 'MacBook Pro',
            price: 1999,
            category: 'computers',
          },
        ],
        pagination: {
          page: parseInt(page),
          limit: parseInt(limit),
          total: 50,
        },
      })
    );
  }),

  // 사용자 인증 API
  rest.post('/api/login', (req, res, ctx) => {
    const { username, password } = req.body;

    if (username === 'testuser' && password === 'password123') {
      return res(
        ctx.status(200),
        ctx.json({
          user: {
            id: 1,
            username: 'testuser',
            email: 'test@example.com',
          },
          token: 'fake-jwt-token',
        })
      );
    }

    return res(
      ctx.status(401),
      ctx.json({ message: 'Invalid credentials' })
    );
  }),

  // 파일 업로드 API
  rest.post('/api/upload', (req, res, ctx) => {
    return res(
      ctx.status(200),
      ctx.json({
        url: 'https://example.com/uploaded-image.jpg',
        id: 'upload-123',
      })
    );
  }),
];

// ✅ 복잡한 API 시나리오를 테스트하는 고급 패턴
import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { server } from '../mocks/server';
import { rest } from 'msw';
import { ShoppingCart } from './ShoppingCart';

describe('ShoppingCart 복합 시나리오', () => {
  it('장바구니 -> 결제 -> 완료 플로우를 테스트한다', async () => {
    const user = userEvent.setup();

    // 결제 성공 시나리오 설정
    server.use(
      rest.post('/api/checkout', (req, res, ctx) => {
        const { items, paymentMethod } = req.body;

        return res(
          ctx.status(200),
          ctx.json({
            orderId: 'ORDER-12345',
            total: items.reduce((sum, item) => sum + item.price, 0),
            status: 'completed',
          })
        );
      })
    );

    render(<ShoppingCart />);

    // 상품 추가
    const addButton = screen.getByRole('button', { name: /add to cart/i });
    await user.click(addButton);

    // 장바구니 확인
    expect(screen.getByText(/1 item in cart/i)).toBeInTheDocument();

    // 결제 진행
    const checkoutButton = screen.getByRole('button', { name: /checkout/i });
    await user.click(checkoutButton);

    // 결제 정보 입력
    await user.selectOptions(screen.getByLabelText(/payment method/i), 'credit-card');

    const confirmButton = screen.getByRole('button', { name: /confirm payment/i });
    await user.click(confirmButton);

    // 결제 완료 확인
    const successMessage = await screen.findByText(/order completed/i);
    expect(successMessage).toBeInTheDocument();
    expect(screen.getByText(/ORDER-12345/i)).toBeInTheDocument();
  });

  it('결제 실패 시 적절한 에러 처리를 한다', async () => {
    const user = userEvent.setup();

    // 결제 실패 시나리오
    server.use(
      rest.post('/api/checkout', (req, res, ctx) => {
        return res(
          ctx.status(402),
          ctx.json({ message: 'Payment declined' })
        );
      })
    );

    render(<ShoppingCart />);

    // 장바구니에 상품 추가 및 결제 시도
    await user.click(screen.getByRole('button', { name: /add to cart/i }));
    await user.click(screen.getByRole('button', { name: /checkout/i }));
    await user.selectOptions(screen.getByLabelText(/payment method/i), 'credit-card');
    await user.click(screen.getByRole('button', { name: /confirm payment/i }));

    // 에러 메시지 확인
    const errorMessage = await screen.findByRole('alert');
    expect(errorMessage).toHaveTextContent(/payment declined/i);

    // 재시도 가능한 상태 확인
    expect(screen.getByRole('button', { name: /try again/i })).toBeInTheDocument();
  });
});

// src/mocks/graphql-handlers.js
import { graphql } from 'msw';

export const graphqlHandlers = [
  // ✅ GraphQL 쿼리 모킹
  graphql.query('GetUsers', (req, res, ctx) => {
    return res(
      ctx.data({
        users: [
          {
            id: '1',
            name: 'John Doe',
            email: 'john@example.com',
            avatar: 'https://example.com/avatar1.jpg',
          },
          {
            id: '2',
            name: 'Jane Smith',
            email: 'jane@example.com',
            avatar: 'https://example.com/avatar2.jpg',
          },
        ],
      })
    );
  }),

  // GraphQL Mutation 모킹
  graphql.mutation('CreateUser', (req, res, ctx) => {
    const { input } = req.variables;

    return res(
      ctx.data({
        createUser: {
          id: '3',
          ...input,
          createdAt: new Date().toISOString(),
        },
      })
    );
  }),

  // 에러 시나리오 모킹
  graphql.query('GetUser', (req, res, ctx) => {
    const { id } = req.variables;

    if (id === 'not-found') {
      return res(
        ctx.errors([
          {
            message: 'User not found',
            extensions: {
              code: 'USER_NOT_FOUND',
            },
          },
        ])
      );
    }

    return res(
      ctx.data({
        user: {
          id,
          name: 'Found User',
          email: 'found@example.com',
        },
      })
    );
  }),
];

// ✅ 테스트 속도 향상을 위한 최적화 기법
describe('성능 최적화된 테스트 스위트', () => {
  // 전역 설정으로 공통 데이터 준비
  let mockUsers;

  beforeAll(() => {
    // 무거운 데이터는 한 번만 생성
    mockUsers = Array.from({ length: 1000 }, (_, i) => ({
      id: i + 1,
      name: `User ${i + 1}`,
      email: `user${i + 1}@example.com`,
    }));
  });

  it('대량 데이터 렌더링 성능을 측정한다', async () => {
    const startTime = performance.now();

    render(<UserList users={mockUsers.slice(0, 100)} />);

    // 첫 번째 사용자가 나타날 때까지의 시간 측정
    await screen.findByText('User 1');

    const endTime = performance.now();
    const renderTime = endTime - startTime;

    // 성능 임계값 검증 (1초 이내)
    expect(renderTime).toBeLessThan(1000);
  });

  // ✅ 테스트 격리로 메모리 누수 방지
  afterEach(() => {
    // DOM과 이벤트 리스너 정리
    document.body.innerHTML = '';

    // 타이머 정리
    jest.clearAllTimers();

    // 모든 모킹 초기화
    jest.clearAllMocks();
  });
});

// ✅ 테스트 디버깅을 위한 유용한 패턴
import { render, screen, logRoles, prettyDOM } from '@testing-library/react';
import { debug } from '@testing-library/react';

describe('디버깅 도구 활용', () => {
  it('복잡한 DOM 구조를 분석한다', () => {
    const { container } = render(<ComplexComponent />);

    // ✅ DOM 구조 전체 출력
    screen.debug();

    // 특정 요소만 출력
    screen.debug(screen.getByTestId('complex-section'));

    // ✅ 모든 접근 가능한 역할(role) 출력
    logRoles(container);

    // 특정 노드의 HTML 출력
    console.log(prettyDOM(container.firstChild));
  });

  it('쿼리가 실패할 때 도움이 되는 정보를 제공한다', () => {
    render(<UserProfile user={mockUser} />);

    try {
      // 존재하지 않는 요소 찾기 시도
      screen.getByRole('button', { name: /non-existent/i });
    } catch (error) {
      // ✅ 사용 가능한 모든 role 출력
      logRoles(screen.container);
      throw error;
    }
  });

  it('비동기 작업의 타이밍 문제를 해결한다', async () => {
    render(<AsyncComponent />);

    // ✅ waitFor 옵션으로 타이밍 조절
    await waitFor(
      () => {
        expect(screen.getByText(/loaded/i)).toBeInTheDocument();
      },
      {
        timeout: 5000, // 최대 5초 대기
        interval: 100,  // 100ms마다 체크
      }
    );
  });
});

// jest.config.js - 커버리지 설정 최적화
module.exports = {
  collectCoverageFrom: [
    'src/**/*.{js,jsx,ts,tsx}',
    '!src/index.js',
    '!src/reportWebVitals.js',
    '!src/**/*.stories.{js,jsx,ts,tsx}',
    '!src/**/*.d.ts',
  ],
  coverageReporters: ['text', 'lcov', 'html'],
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80,
    },
    // 핵심 비즈니스 로직은 더 높은 커버리지 요구
    './src/components/core/': {
      branches: 90,
      functions: 90,
      lines: 90,
      statements: 90,
    },
  },
};

# .github/workflows/test.yml
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [16.x, 18.x, 20.x]

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests with coverage
        run: npm run test:coverage
        env:
          CI: true

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage/lcov.info

// tests/guidelines.md에 포함될 규칙들

/**
 * ✅ 좋은 테스트 작성 규칙
 *
 * 1. 테스트 이름은 한국어로 명확하게 작성
 * 2. AAA 패턴 준수: Arrange → Act → Assert
 * 3. 각 테스트는 하나의 기능만 검증
 * 4. 모킹은 최소한으로, 실제 동작에 가깝게
 * 5. 비동기 작업은 반드시 대기 처리
 */

// ✅ 표준 테스트 템플릿
describe('ComponentName', () => {
  // 공통 설정
  const defaultProps = {
    // 기본 props 정의
  };

  const renderComponent = (props = {}) => {
    return render(<ComponentName {...defaultProps} {...props} />);
  };

  describe('렌더링', () => {
    it('기본 props로 올바르게 렌더링된다', () => {
      // 테스트 구현
    });
  });

  describe('사용자 상호작용', () => {
    it('버튼 클릭 시 예상된 동작을 수행한다', async () => {
      // 테스트 구현
    });
  });

  describe('에러 처리', () => {
    it('잘못된 props 전달 시 적절히 처리한다', () => {
      // 테스트 구현
    });
  });
});

// ✅ 레거시 컴포넌트의 단계적 테스트 적용
describe('LegacyComponent 점진적 테스트', () => {
  // 1단계: 기본 렌더링부터 시작
  it('컴포넌트가 에러 없이 렌더링된다', () => {
    expect(() => {
      render(<LegacyComponent />);
    }).not.toThrow();
  });

  // 2단계: 핵심 기능 테스트
  it('주요 UI 요소들이 표시된다', () => {
    render(<LegacyComponent />);

    expect(screen.getByRole('heading')).toBeInTheDocument();
    expect(screen.getByRole('main')).toBeInTheDocument();
  });

  // 3단계: 사용자 시나리오 테스트로 확장
  it('사용자가 기본 플로우를 완료할 수 있다', async () => {
    // 점진적으로 더 복잡한 시나리오 추가
  });
});