MSW, API 모킹, 브라우저 핸들러, Vitest | 컴포넌트 테스트 전에 어떻게 붙이나?

MSW 설치 (npm / pnpm)
# npm
npm install -D msw

# pnpm
pnpm add -D msw

# 브라우저 워커 스크립트를 public에 복사 (프로젝트 루트에서)
npx msw init public/ --save

src/mocks/handlers.ts — REST 핸들러 예시
import { http, HttpResponse, delay } from 'msw'

const products = [
  { id: 'p1', name: '무선 키보드', price: 89000 },
  { id: 'p2', name: 'USB-C 허브', price: 42000 },
]

export const handlers = [
  http.get('/api/products', async () => {
    await delay(120)
    return HttpResponse.json({ items: products, total: products.length })
  }),

  http.get('/api/products/:id', ({ params }) => {
    const item = products.find((p) => p.id === params.id)
    if (!item) {
      return HttpResponse.json(
        { message: 'Not found' },
        { status: 404 }
      )
    }
    return HttpResponse.json(item)
  }),

  http.post('/api/products', async ({ request }) => {
    const body = await request.json()
    if (!body?.name) {
      return HttpResponse.json(
        { message: 'name required' },
        { status: 400 }
      )
    }
    const created = {
      id: 'p' + String(Date.now()),
      name: String(body.name),
      price: Number(body.price) || 0,
    }
    products.push(created)
    return HttpResponse.json(created, { status: 201 })
  }),
]

src/mocks/browser.ts + 앱 진입점 연결
// src/mocks/browser.ts
import { setupWorker } from 'msw/browser'
import { handlers } from './handlers'

export const worker = setupWorker(...handlers)

// 예: src/main.tsx (Vite) 또는 클라이언트 전용 bootstrap
async function enableMocking() {
  if (import.meta.env.MODE !== 'development') return
  if (import.meta.env.VITE_ENABLE_MSW !== 'true') return

  const { worker } = await import('./mocks/browser')
  await worker.start({
    onUnhandledRequest: 'warn', // 또는 'error' / 'bypass'
  })
}

enableMocking().then(() => {
  // createRoot(...).render(<App />)
})

src/mocks/server.ts + vitest.setup.ts
// src/mocks/server.ts
import { setupServer } from 'msw/node'
import { handlers } from './handlers'

export const server = setupServer(...handlers)

// vitest.setup.ts
import { beforeAll, afterEach, afterAll } from 'vitest'
import { server } from './src/mocks/server'

beforeAll(() => {
  server.listen({ onUnhandledRequest: 'error' })
})

afterEach(() => {
  server.resetHandlers()
})

afterAll(() => {
  server.close()
})

상품 목록 컴포넌트 테스트 예시
import { render, screen, waitFor } from '@testing-library/react'
import { describe, it, expect } from 'vitest'
import { ProductList } from './ProductList'

describe('ProductList', () => {
  it('목록 API 응답을 카드로 렌더한다', async () => {
    render(<ProductList />)

    await waitFor(() => {
      expect(screen.getByText('무선 키보드')).toBeInTheDocument()
    })
    expect(screen.getByText('USB-C 허브')).toBeInTheDocument()
  })
})

server.use로 에러·빈 목록 오버라이드
import { http, HttpResponse } from 'msw'
import { server } from '../mocks/server'
import { render, screen, waitFor } from '@testing-library/react'
import { ProductList } from './ProductList'

it('500이면 에러 배너를 보여 준다', async () => {
  server.use(
    http.get('/api/products', () => {
      return HttpResponse.json(
        { message: 'upstream failed' },
        { status: 500 }
      )
    })
  )

  render(<ProductList />)

  await waitFor(() => {
    expect(screen.getByRole('alert')).toHaveTextContent(
      /일시적인 오류|다시 시도/
    )
  })
})

it('빈 목록이면 안내 문구를 보여 준다', async () => {
  server.use(
    http.get('/api/products', () => {
      return HttpResponse.json({ items: [], total: 0 })
    })
  )

  render(<ProductList />)

  expect(await screen.findByText(/등록된 상품이 없습니다/)).toBeInTheDocument()
})

it('401이면 로그인 유도 문구를 보여 준다', async () => {
  server.use(
    http.get('/api/products', () => {
      return new HttpResponse(null, { status: 401 })
    })
  )

  render(<ProductList />)

  expect(await screen.findByText(/로그인이 필요/)).toBeInTheDocument()
})

쿼리·Authorization·인위 지연 핸들러
import { http, HttpResponse, delay } from 'msw'

http.get('/api/products', async ({ request }) => {
  const url = new URL(request.url)
  const q = url.searchParams.get('q') || ''
  const auth = request.headers.get('authorization')

  if (!auth) {
    return HttpResponse.json({ message: 'unauthorized' }, { status: 401 })
  }

  // 느린 네트워크 재현 (로딩 스피너 테스트)
  await delay(800)

  const items = [
    { id: 'p1', name: '무선 키보드', price: 89000 },
    { id: 'p2', name: 'USB-C 허브', price: 42000 },
  ].filter((p) => p.name.includes(q))

  return HttpResponse.json({ items, total: items.length })
})