2026년 Vitest와 MSW로 API 모킹 테스트 완벽 가이드

2026년 현재는 특히 MSW(Mock Service Worker)가 업계 표준으로 자리잡았어요. 기존의 axios-mock-adapter나 fetch-mock 같은 라이브러리 대신 MSW를 선택하는 팀들이 압도적으로 많아졌죠. 왜냐하면 MSW는 Service Worker를 활용해서 네트워크 레벨에서 요청을 가로채기 때문에, 실제 환경과 거의 동일한 테스트가 가능하거든요.

npm install -D vitest @vitest/ui msw@latest
npm install -D @testing-library/react @testing-library/jest-dom
npm install -D happy-dom

import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    environment: 'happy-dom',
    setupFiles: './src/test/setup.ts',
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html']
    }
  }
})

import '@testing-library/jest-dom'
import { cleanup } from '@testing-library/react'
import { afterEach } from 'vitest'

// 각 테스트 후 자동 정리
afterEach(() => {
  cleanup()
})

{
  "scripts": {
    "test": "vitest",
    "test:ui": "vitest --ui",
    "test:coverage": "vitest --coverage",
    "test:run": "vitest run"
  }
}

TypeScript를 쓰신다면요, tsconfig.json에 "types": ["vitest/globals"]를 추가해주셔야 해요. 안 그러면 describe, it 같은 전역 함수에서 타입 에러가 나거든요. 제가 처음에 이거 몰라서 한참 헤맸답니다.

• ✓ Vitest, MSW, 관련 패키지 설치 완료
• ✓ vitest.config.ts 파일 생성 및 설정
• ✓ src/test/setup.ts 파일 생성
• ✓ package.json 스크립트 추가
• ✓ TypeScript 설정 (해당되는 경우)

• Service Worker 기반 - 브라우저의 Service Worker API를 활용해서 실제 네트워크 요청을 가로채요
• 코드 수정 불필요 - 기존 API 호출 코드를 하나도 안 바꿔도 되거든요
• 브라우저와 Node.js 모두 지원 - 같은 mock 정의를 개발 환경과 테스트에서 다 쓸 수 있어요
• 타입 안정성 - TypeScript와 찰떡궁합이라 타입 에러를 사전에 잡아줘요
• 실제와 동일한 동작 - HTTP 헤더, 상태 코드, 에러 핸들링까지 실제 API와 똑같이 동작해요

import { http, HttpResponse } from 'msw'

export const handlers = [
  http.get('/api/users', () => {
    return HttpResponse.json({
      users: [
        { id: 1, name: '김개발' },
        { id: 2, name: '이테스트' }
      ]
    })
  })
]

이게 전부예요. 이렇게만 해두면 /api/users로 가는 GET 요청을 가로채서 mock 데이터를 돌려줘요.

1. fetch/axios 직접 모킹
장점: 빠르고 간단해요
단점: 실제 네트워크 레이어를 테스트 못하고, 코드 수정이 필요해요

2. JSON Server
장점: 실제 서버를 띄워서 완전히 동일한 환경이에요
단점: 설정이 복잡하고 테스트가 느려요

3. MSW (추천!)
장점: 실제 네트워크 동작 + 빠른 속도 + 간편한 설정
특징: 개발 환경과 테스트 환경 모두에서 사용 가능해요

import { setupServer } from 'msw/node'
import { handlers } from './handlers'

// 테스트용 MSW 서버 생성
export const server = setupServer(...handlers)

// 서버 시작 시 로깅 활성화 (디버깅용)
server.events.on('request:start', ({ request }) => {
  console.log('MSW intercepted:', request.method, request.url)
})

import { http, HttpResponse } from 'msw'

export const handlers = [
  // 사용자 정보 조회
  http.get('/api/users/:id', ({ params }) => {
    const { id } = params
    return HttpResponse.json({
      id,
      name: '홍길동',
      email: 'hong@example.com'
    })
  }),

  // 게시글 목록 조회
  http.get('/api/posts', ({ request }) => {
    const url = new URL(request.url)
    const page = url.searchParams.get('page') || '1'
    
    return HttpResponse.json({
      posts: [
        { id: 1, title: '첫 번째 글', content: '내용입니다' },
        { id: 2, title: '두 번째 글', content: '내용입니다' }
      ],
      page: parseInt(page),
      totalPages: 10
    })
  }),

  // 게시글 작성
  http.post('/api/posts', async ({ request }) => {
    const body = await request.json()
    return HttpResponse.json({
      id: 3,
      ...body,
      createdAt: new Date().toISOString()
    }, { status: 201 })
  })
]

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom', // 브라우저 환경 시뮬레이션
    setupFiles: ['./src/test/setup.ts'], // 전역 설정 파일
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      exclude: [
        'node_modules/',
        'src/mocks/',
        '**/*.spec.ts'
      ]
    }
  }
})

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

// 모든 테스트 시작 전 MSW 서버 시작
beforeAll(() => {
  server.listen({ 
    onUnhandledRequest: 'warn' // 처리되지 않은 요청에 대해 경고
  })
})

// 각 테스트 후 핸들러 초기화
afterEach(() => {
  server.resetHandlers()
})

// 모든 테스트 종료 후 MSW 서버 종료
afterAll(() => {
  server.close()
})

export async function fetchUser(id: string) {
  const response = await fetch(`/api/users/${id}`)
  if (!response.ok) {
    throw new Error('사용자를 불러올 수 없습니다')
  }
  return response.json()
}

import { describe, it, expect } from 'vitest'
import { http, HttpResponse } from 'msw'
import { server } from '../mocks/server'
import { fetchUser } from './user'

describe('fetchUser', () => {
  it('사용자 정보를 성공적으로 가져온다', async () => {
    const user = await fetchUser('123')
    
    expect(user).toEqual({
      id: '123',
      name: '홍길동',
      email: 'hong@example.com'
    })
  })

  it('존재하지 않는 사용자일 때 에러를 던진다', async () => {
    // 이 테스트만을 위한 핸들러 오버라이드
    server.use(
      http.get('/api/users/:id', () => {
        return new HttpResponse(null, { status: 404 })
      })
    )

    await expect(fetchUser('999')).rejects.toThrow(
      '사용자를 불러올 수 없습니다'
    )
  })

  it('네트워크 에러 발생 시 에러를 던진다', async () => {
    server.use(
      http.get('/api/users/:id', () => {
        return HttpResponse.error()
      })
    )

    await expect(fetchUser('123')).rejects.toThrow()
  })
})

import { http, HttpResponse } from 'msw'
import { server } from '../mocks/server'

// 특정 응답 시뮬레이션 헬퍼
export function mockApiResponse(url: string, data: any, status = 200) {
  server.use(
    http.get(url, () => {
      return HttpResponse.json(data, { status })
    })
  )
}

// 에러 응답 시뮬레이션 헬퍼
export function mockApiError(url: string, status = 500, message = 'Server Error') {
  server.use(
    http.get(url, () => {
      return HttpResponse.json(
        { error: message },
        { status }
      )
    })
  )
}

// 네트워크 에러 시뮬레이션 헬퍼
export function mockNetworkError(url: string) {
  server.use(
    http.get(url, () => {
      return HttpResponse.error()
    })
  )
}

// 지연 응답 시뮬레이션 헬퍼
export async function mockDelayedResponse(
  url: string, 
  data: any, 
  delay = 1000
) {
  server.use(
    http.get(url, async () => {
      await new Promise(resolve => setTimeout(resolve, delay))
      return HttpResponse.json(data)
    })
  )
}

import { describe, it, expect } from 'vitest'
import { mockApiResponse, mockApiError } from '../test/helpers'
import { fetchUser } from './user'

describe('fetchUser with helpers', () => {
  it('성공 케이스', async () => {
    mockApiResponse('/api/users/123', {
      id: '123',
      name: '김철수'
    })

    const user = await fetchUser('123')
    expect(user.name).toBe('김철수')
  })

  it('404 에러 케이스', async () => {
    mockApiError('/api/users/999', 404, 'User not found')

    await expect(fetchUser('999')).rejects.toThrow()
  })
})

// src/mocks/config.ts
export const mswConfig = {
  test: {
    baseUrl: '',
    delay: 0, // 테스트는 빠르게
    logging: false
  },
  development: {
    baseUrl: '',
    delay: 100, // 실제 API와 유사한 지연
    logging: true
  },
  staging: {
    baseUrl: 'https://staging-api.example.com',
    delay: 200,
    logging: true
  }
}

export function getMswConfig() {
  const env = process.env.NODE_ENV || 'development'
  return mswConfig[env] || mswConfig.development
}

• ✓ MSW 서버가 전역 setup에서 자동 시작되나요?
• ✓ afterEach에서 핸들러를 리셋하나요?
• ✓ 테스트 종료 시 서버가 제대로 닫히나요?
• ✓ 환경 변수에 따라 설정이 달라지나요?
• ✓ 디버깅을 위한 로깅이 적절히 설정되었나요?

// src/types/api.ts
export interface User {
  id: string
  name: string
  email: string
}

export interface ApiResponse {
  data: T
  message?: string
}

// src/mocks/handlers.ts
import { http, HttpResponse } from 'msw'
import type { User, ApiResponse } from '../types/api'

export const handlers = [
  http.get(
    '/api/users/:id', 
    ({ params }) => {
      const user: User = {
        id: params.id as string,
        name: '홍길동',
        email: 'hong@example.com'
      }
      
      return HttpResponse.json({
        data: user,
        message: '성공'
      })
    }
  )
]

// auth.test.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { http, HttpResponse } from 'msw';
import { setupServer } from 'msw/node';
import { login, refreshToken } from './auth';

const server = setupServer(
  http.post('/api/auth/login', async ({ request }) => {
    const { email, password } = await request.json();
    
    if (email === 'test@example.com' && password === 'password123') {
      return HttpResponse.json({
        accessToken: 'mock-access-token',
        refreshToken: 'mock-refresh-token',
        expiresIn: 3600
      });
    }
    
    return HttpResponse.json(
      { error: '인증 정보가 올바르지 않습니다' },
      { status: 401 }
    );
  }),
  
  http.post('/api/auth/refresh', async ({ request }) => {
    const { refreshToken } = await request.json();
    
    if (refreshToken === 'mock-refresh-token') {
      return HttpResponse.json({
        accessToken: 'new-access-token',
        expiresIn: 3600
      });
    }
    
    return HttpResponse.json(
      { error: '토큰이 만료되었습니다' },
      { status: 401 }
    );
  })
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

describe('사용자 인증 플로우', () => {
  it('올바른 정보로 로그인하면 토큰을 받아요', async () => {
    const result = await login('test@example.com', 'password123');
    
    expect(result.accessToken).toBe('mock-access-token');
    expect(result.refreshToken).toBe('mock-refresh-token');
  });
  
  it('잘못된 비밀번호는 401 에러를 반환해요', async () => {
    await expect(
      login('test@example.com', 'wrong-password')
    ).rejects.toThrow('인증 정보가 올바르지 않습니다');
  });
  
  it('리프레시 토큰으로 새 액세스 토큰을 받을 수 있어요', async () => {
    const result = await refreshToken('mock-refresh-token');
    
    expect(result.accessToken).toBe('new-access-token');
  });
});

// cart.test.ts
import { http, HttpResponse } from 'msw';
import { setupServer } from 'msw/node';

let cartItems = [];

const server = setupServer(
  http.post('/api/cart/items', async ({ request }) => {
    const { productId, quantity } = await request.json();
    
    // 재고 확인 시뮬레이션
    if (productId === 'out-of-stock-item') {
      return HttpResponse.json(
        { error: '재고가 부족합니다', availableStock: 0 },
        { status: 400 }
      );
    }
    
    const newItem = {
      id: Date.now(),
      productId,
      quantity,
      price: 29900
    };
    
    cartItems.push(newItem);
    
    return HttpResponse.json({
      item: newItem,
      totalItems: cartItems.length,
      totalPrice: cartItems.reduce((sum, item) => sum + (item.price * item.quantity), 0)
    }, { status: 201 });
  }),
  
  http.patch('/api/cart/items/:id', async ({ params, request }) => {
    const { id } = params;
    const { quantity } = await request.json();
    
    const itemIndex = cartItems.findIndex(item => item.id === Number(id));
    
    if (itemIndex === -1) {
      return HttpResponse.json(
        { error: '상품을 찾을 수 없습니다' },
        { status: 404 }
      );
    }
    
    if (quantity === 0) {
      cartItems.splice(itemIndex, 1);
      return HttpResponse.json({ message: '상품이 삭제되었습니다' });
    }
    
    cartItems[itemIndex].quantity = quantity;
    
    return HttpResponse.json({
      item: cartItems[itemIndex],
      totalItems: cartItems.length,
      totalPrice: cartItems.reduce((sum, item) => sum + (item.price * item.quantity), 0)
    });
  }),
  
  http.get('/api/cart', () => {
    return HttpResponse.json({
      items: cartItems,
      totalItems: cartItems.length,
      totalPrice: cartItems.reduce((sum, item) => sum + (item.price * item.quantity), 0)
    });
  })
);

describe('장바구니 관리', () => {
  beforeEach(() => {
    cartItems = []; // 각 테스트마다 초기화
  });
  
  it('상품을 장바구니에 추가할 수 있어요', async () => {
    const result = await addToCart('product-123', 2);
    
    expect(result.item.productId).toBe('product-123');
    expect(result.item.quantity).toBe(2);
    expect(result.totalItems).toBe(1);
  });
  
  it('재고 부족 상품은 추가할 수 없어요', async () => {
    await expect(
      addToCart('out-of-stock-item', 1)
    ).rejects.toThrow('재고가 부족합니다');
  });
  
  it('상품 수량을 변경하면 총 금액이 업데이트돼요', async () => {
    await addToCart('product-123', 1);
    const result = await updateCartItem(cartItems[0].id, 3);
    
    expect(result.item.quantity).toBe(3);
    expect(result.totalPrice).toBe(89700); // 29900 * 3
  });
});

// pagination.test.ts
const mockPosts = Array.from({ length: 50 }, (_, i) => ({
  id: i + 1,
  title: `게시글 ${i + 1}`,
  content: `내용 ${i + 1}`,
  createdAt: new Date(2026, 5, 25 - i).toISOString()
}));

const server = setupServer(
  http.get('/api/posts', ({ request }) => {
    const url = new URL(request.url);
    const page = parseInt(url.searchParams.get('page') || '1');
    const limit = parseInt(url.searchParams.get('limit') || '10');
    
    const startIndex = (page - 1) * limit;
    const endIndex = startIndex + limit;
    const posts = mockPosts.slice(startIndex, endIndex);
    
    return HttpResponse.json({
      data: posts,
      pagination: {
        currentPage: page,
        totalPages: Math.ceil(mockPosts.length / limit),
        totalItems: mockPosts.length,
        hasNext: endIndex < mockPosts.length,
        hasPrev: page > 1
      }
    });
  })
);

describe('페이지네이션', () => {
  it('첫 페이지를 정확하게 불러와요', async () => {
    const result = await fetchPosts({ page: 1, limit: 10 });
    
    expect(result.data).toHaveLength(10);
    expect(result.data[0].id).toBe(1);
    expect(result.pagination.currentPage).toBe(1);
    expect(result.pagination.hasNext).toBe(true);
    expect(result.pagination.hasPrev).toBe(false);
  });
  
  it('중간 페이지는 이전/다음이 모두 있어요', async () => {
    const result = await fetchPosts({ page: 3, limit: 10 });
    
    expect(result.pagination.hasNext).toBe(true);
    expect(result.pagination.hasPrev).toBe(true);
  });
  
  it('마지막 페이지는 다음 페이지가 없어요', async () => {
    const result = await fetchPosts({ page: 5, limit: 10 });
    
    expect(result.pagination.hasNext).toBe(false);
    expect(result.pagination.hasPrev).toBe(true);
  });
});

// sync.test.ts
let documentVersion = 1;
let documentContent = '초기 내용';

const server = setupServer(
  http.get('/api/document/:id', ({ params }) => {
    return HttpResponse.json({
      id: params.id,
      content: documentContent,
      version: documentVersion,
      lastModified: new Date().toISOString()
    });
  }),
  
  http.patch('/api/document/:id', async ({ request }) => {
    const { content, version } = await request.json();
    
    // 버전 충돌 시뮬레이션
    if (version < documentVersion) {
      return HttpResponse.json(
        {
          error: '문서가 다른 사용자에 의해 수정되었습니다',
          currentVersion: documentVersion,
          currentContent: documentContent
        },
        { status: 409 }
      );
    }
    
    documentContent = content;
    documentVersion++;
    
    return HttpResponse.json({
      content: documentContent,
      version: documentVersion,
      lastModified: new Date().toISOString()
    });
  })
);

describe('실시간 문서 동기화', () => {
  beforeEach(() => {
    documentVersion = 1;
    documentContent = '초기 내용';
  });
  
  it('문서를 성공적으로 업데이트해요', async () => {
    const result = await updateDocument('doc-1', {
      content: '수정된 내용',
      version: 1
    });
    
    expect(result.content).toBe('수정된 내용');
    expect(result.version).toBe(2);
  });
  
  it('오래된 버전으로 업데이트하면 충돌이 발생해요', async () => {
    // 먼저 한 번 업데이트
    await updateDocument('doc-1', {
      content: '첫 번째 수정',
      version: 1
    });
    
    // 오래된 버전으로 업데이트 시도
    await expect(
      updateDocument('doc-1', {
        content: '두 번째 수정',
        version: 1
      })
    ).rejects.toThrow('문서가 다른 사용자에 의해 수정되었습니다');
  });
});

// payment.test.ts
const server = setupServer(
  http.post('/api/payments', async ({ request }) => {
    const { amount, cardNumber, cvv } = await request.json();
    
    // 카드 유효성 검사 시뮬레이션
    if (cardNumber === '0000-0000-0000-0000') {
      return HttpResponse.json(
        { error: '유효하지 않은 카드입니다' },
        { status: 400 }
      );
    }
    
    // 잔액 부족 시뮬레이션
    if (amount > 1000000) {
      return HttpResponse.json(
        { error: '결제 한도를 초과했습니다' },
        { status: 402 }
      );
    }
    
    // CVV 오류 시뮬레이션
    if (cvv === '000') {
      return HttpResponse.json(
        { error: 'CVV 번호가 올바르지 않습니다' },
        { status: 400 }
      );
    }
    
    return HttpResponse.json({
      paymentId: `PAY-${Date.now()}`,
      status: 'completed',
      amount,
      paidAt: new Date().toISOString(),
      receiptUrl: 'https://example.com/receipt/123'
    }, { status: 201 });
  }),
  
  http.post('/api/payments/:id/refund', async ({ params, request }) => {
    const { amount, reason } = await request.json();
    
    return HttpResponse.json({
      refundId: `REF-${Date.now()}`,
      originalPaymentId: params.id,
      amount,
      reason,
      status: 'refunded',
      refundedAt: new Date().toISOString()
    });
  })
);

describe('결제 프로세스', () => {
  it('정상적인 결제가 성공해요', async () => {
    const result = await processPayment({
      amount: 50000,
      cardNumber: '1234-5678-9012-3456',
      cvv: '123'
    });
    
    expect(result.status).toBe('completed');
    expect(result.amount).toBe(50000);
    expect(result.paymentId).toMatch(/^PAY-/);
  });
  
  it('유효하지 않은 카드는 거부돼요', async () => {
    await expect(
      processPayment({
        amount: 50000,
        cardNumber: '0000-0000-0000-0000',
        cvv: '123'
      })
    ).rejects.toThrow('유효하지 않은 카드입니다');
  });
  
  it('결제 한도를 초과하면 실패해요', async () => {
    await expect(
      processPayment({
        amount: 2000000,
        cardNumber: '1234-5678-9012-3456',
        cvv: '123'
      })
    ).rejects.toThrow('결제 한도를 초과했습니다');
  });
  
  it('환불 요청이 정상적으로 처리돼요', async () => {
    const payment = await processPayment({
      amount: 50000,
      cardNumber: '1234-5678-9012-3456',
      cvv: '123'
    });
    
    const refund = await requestRefund(payment.paymentId, {
      amount: 50000,
      reason: '단순 변심'
    });
    
    expect(refund.status).toBe('refunded');
    expect(refund.originalPaymentId).toBe(payment.paymentId);
  });
});

실전 예제를 그대로 복붙해서 쓰실 거면요, 반드시 실제 API 응답 구조와 일치하는지 확인하세요. 제가 보여드린 예제는 일반적인 패턴이지만, 실제 프로젝트마다 필드명이나 구조가 다를 수 있거든요. 특히 에러 응답 형식은 백엔드 팀이랑 미리 협의하는 게 좋아요!

// mocks/handlers/user.handlers.ts
export const userHandlers = [
  http.get('/api/users/:id', ({ params }) => {
    return HttpResponse.json({
      id: params.id,
      name: '테스트 유저',
      email: 'test@example.com'
    })
  }),
  
  http.post('/api/users', async ({ request }) => {
    const body = await request.json()
    return HttpResponse.json({ id: '123', ...body }, { status: 201 })
  })
]

// mocks/handlers/product.handlers.ts
export const productHandlers = [
  http.get('/api/products', () => {
    return HttpResponse.json({
      products: [
        { id: '1', name: '상품1', price: 10000 },
        { id: '2', name: '상품2', price: 20000 }
      ]
    })
  })
]

// mocks/handlers/index.ts
export const handlers = [
  ...userHandlers,
  ...productHandlers
]

팩토리 패턴 활용하기

핸들러를 함수로 만들어서 필요한 데이터를 주입하는 방식이에요. 이렇게 하면 같은 엔드포인트인데 테스트마다 다른 응답을 쉽게 만들 수 있거든요. 저는 이 방법 쓰고 나서 테스트 코드가 엄청 깔끔해졌어요.

// mocks/factories/user.factory.ts
export const createUserHandler = (userData = {}) => {
  return http.get('/api/users/me', () => {
    return HttpResponse.json({
      id: '123',
      name: '기본 유저',
      email: 'default@test.com',
      ...userData
    })
  })
}

// 테스트에서 사용
describe('유저 프로필', () => {
  it('일반 유저 정보를 표시해요', async () => {
    server.use(createUserHandler({
      name: '홍길동',
      role: 'user'
    }))
    // 테스트 코드...
  })
  
  it('관리자 유저는 관리 메뉴가 보여요', async () => {
    server.use(createUserHandler({
      name: '관리자',
      role: 'admin'
    }))
    // 테스트 코드...
  })
})

// mocks/handlers/error.handlers.ts
export const errorHandlers = {
  networkError: http.get('/api/*', () => {
    return HttpResponse.error()
  }),
  
  timeout: http.get('/api/*', async () => {
    await delay(30000) // 30초 지연
    return HttpResponse.json({ data: 'too late' })
  }),
  
  unauthorized: http.get('/api/*', () => {
    return new HttpResponse(null, {
      status: 401,
      statusText: 'Unauthorized'
    })
  }),
  
  serverError: http.get('/api/*', () => {
    return HttpResponse.json(
      { error: '서버 에러가 발생했습니다' },
      { status: 500 }
    )
  }),
  
  validationError: http.post('/api/*', () => {
    return HttpResponse.json(
      {
        errors: {
          email: '이메일 형식이 올바르지 않아요',
          password: '비밀번호는 8자 이상이어야 해요'
        }
      },
      { status: 422 }
    )
  })
}

// mocks/handlers/stateful.handlers.ts
const posts = []
let postIdCounter = 1

export const statefulHandlers = [
  // 게시글 목록 조회
  http.get('/api/posts', () => {
    return HttpResponse.json({ posts })
  }),
  
  // 게시글 생성
  http.post('/api/posts', async ({ request }) => {
    const body = await request.json()
    const newPost = {
      id: String(postIdCounter++),
      ...body,
      createdAt: new Date().toISOString()
    }
    posts.push(newPost)
    return HttpResponse.json(newPost, { status: 201 })
  }),
  
  // 게시글 삭제
  http.delete('/api/posts/:id', ({ params }) => {
    const index = posts.findIndex(p => p.id === params.id)
    if (index > -1) {
      posts.splice(index, 1)
      return new HttpResponse(null, { status: 204 })
    }
    return new HttpResponse(null, { status: 404 })
  })
]

// 테스트 전에 상태 초기화
beforeEach(() => {
  posts.length = 0
  postIdCounter = 1
})

describe('API 요청 검증', () => {
  it('올바른 헤더를 포함해서 요청해요', async () => {
    let capturedHeaders
    
    server.use(
      http.post('/api/data', async ({ request }) => {
        capturedHeaders = {
          contentType: request.headers.get('content-type'),
          authorization: request.headers.get('authorization')
        }
        return HttpResponse.json({ success: true })
      })
    )
    
    await submitData({ title: '테스트' })
    
    expect(capturedHeaders.contentType).toBe('application/json')
    expect(capturedHeaders.authorization).toContain('Bearer')
  })
  
  it('요청 본문이 올바른 형식이에요', async () => {
    let capturedBody
    
    server.use(
      http.post('/api/users', async ({ request }) => {
        capturedBody = await request.json()
        return HttpResponse.json({ id: '123' })
      })
    )
    
    await createUser({ name: '홍길동', age: 30 })
    
    expect(capturedBody).toMatchObject({
      name: expect.any(String),
      age: expect.any(Number)
    })
    expect(capturedBody.name).not.toBe('')
  })
})

저는 보통 개발 환경에서는 300~500ms 정도 지연을 주고, 테스트 환경에서는 50~100ms 정도만 줘요. 이 정도면 로딩 상태도 확인할 수 있고, 테스트도 빠르게 돌아가거든요. 환경 변수로 관리하면 편해요!

// mocks/config.ts
const DELAYS = {
  test: 50,
  development: 300,
  none: 0
}

export const getDelay = () => {
  return DELAYS[import.meta.env.MODE] || DELAYS.development
}

// 핸들러에서 사용
export const handlers = [
  http.get('/api/users', async () => {
    await delay(getDelay())
    return HttpResponse.json({ users: [...] })
  })
]

// 특정 테스트에서만 지연 조정
it('로딩 스피너가 표시돼요', async () => {
  server.use(
    http.get('/api/data', async () => {
      await delay(200) // 충분한 시간 확보
      return HttpResponse.json({ data: 'test' })
    })
  )
  
  render()
  
  expect(screen.getByText('로딩중...')).toBeInTheDocument()
  
  await waitFor(() => {
    expect(screen.queryByText('로딩중...')).not.toBeInTheDocument()
  })
})

// fixtures/user.fixture.ts
export const userFixtures = {
  normalUser: {
    id: '1',
    name: '홍길동',
    email: 'hong@test.com',
    role: 'user',
    createdAt: '2026-01-01T00:00:00Z'
  },
  
  adminUser: {
    id: '2',
    name: '관리자',
    email: 'admin@test.com',
    role: 'admin',
    createdAt: '2025-12-01T00:00:00Z'
  },
  
  premiumUser: {
    id: '3',
    name: '프리미엄',
    email: 'premium@test.com',
    role: 'user',
    subscription: 'premium',
    createdAt: '2026-03-01T00:00:00Z'
  }
}

// 동적 픽스처 생성
export const createUserFixture = (overrides = {}) => ({
  id: faker.string.uuid(),
  name: faker.person.fullName(),
  email: faker.internet.email(),
  role: 'user',
  createdAt: new Date().toISOString(),
  ...overrides
})

// 테스트에서 사용
it('일반 유저는 제한된 기능만 사용해요', async () => {
  server.use(
    http.get('/api/users/me', () => {
      return HttpResponse.json(userFixtures.normalUser)
    })
  )
  
  render()
  
  expect(screen.queryByText('관리자 메뉴')).not.toBeInTheDocument()
})

// test-utils/scenario-builder.ts
class ApiScenarioBuilder {
  private handlers = []
  
  withUser(userData = {}) {
    this.handlers.push(
      http.get('/api/users/me', () => {
        return HttpResponse.json({
          id: '1',
          name: '테스트 유저',
          ...userData
        })
      })
    )
    return this
  }
  
  withProducts(count = 5) {
    const products = Array.from({ length: count }, (_, i) => ({
      id: String(i + 1),
      name: `상품 ${i + 1}`,
      price: (i + 1) * 10000
    }))
    
    this.handlers.push(
      http.get('/api/products', () => {
        return HttpResponse.json({ products })
      })
    )
    return this
  }
  
  withError(endpoint, status = 500) {
    this.handlers.push(
      http.get(endpoint, () => {
        return new HttpResponse(null, { status })
      })
    )
    return this
  }
  
  withDelay(ms) {
    const originalHandlers = [...this.handlers]
    this.handlers = originalHandlers.map(handler => {
      return async (info) => {
        await delay(ms)
        return handler(info)
      }
    })
    return this
  }
  
  apply() {
    server.use(...this.handlers)
  }
}

export const scenario = () => new ApiScenarioBuilder()

// 테스트에서 사용
it('로그인한 유저가 상품 목록을 봐요', async () => {
  scenario()
    .withUser({ name: '홍길동', role: 'user' })
    .withProducts(10)
    .apply()
  
  render()
  
  await waitFor(() => {
    expect(screen.getByText('홍길동님 환영합니다')).toBeInTheDocument()
    expect(screen.getAllByRole('article')).toHaveLength(10)
  })
})

it('에러 발생 시 fallback UI를 보여줘요', async () => {
  scenario()
    .withUser()
    .withError('/api/products', 500)
    .apply()
  
  render()
  
  await waitFor(() => {
    expect(screen.getByText('상품을 불러올 수 없어요')).toBeInTheDocument()
  })
})

server.use()로 추가한 핸들러는 테스트가 끝나도 남아있어요! 반드시 afterEach에서 server.resetHandlers()를 호출해야 해요. 안 그러면 다른 테스트에 영향을 줄 수 있거든요.

// test/setup.ts
beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))

afterEach(() => {
  // 런타임에 추가된 핸들러 제거
  server.resetHandlers()
  
  // 캐시나 전역 상태 정리
  queryClient.clear()
  localStorage.clear()
  sessionStorage.clear()
})

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

// 특정 describe 블록 내 상태 관리
describe('장바구니 기능', () => {
  let cartItems = []
  
  beforeEach(() => {
    cartItems = []
    
    server.use(
      http.get('/api/cart', () => {
        return HttpResponse.json({ items: cartItems })
      }),
      
      http.post('/api/cart', async ({ request }) => {
        const body = await request.json()
        cartItems.push(body)
        return HttpResponse.json({ items: cartItems })
      })
    )
  })
  
  // 각 테스트는 깨끗한 상태로 시작
  it('상품을 추가할 수 있어요', async () => {
    // cartItems는 비어있음
  })
  
  it('여러 상품을 추가할 수 있어요', async () => {
    // 이전 테스트의 영향을 받지 않음
  })
})

// vitest.config.ts
export default defineConfig({
  test: {
    // 병렬 실행으로 속도 향상
    pool: 'threads',
    poolOptions: {
      threads: {
        singleThread: false
      }
    },
    
    // 타임아웃 설정
    testTimeout: 10000, // 10초
    hookTimeout: 10000,
    
    // 격리 수준
    isolate: true,
    
    // watch 모드 최적화
    watch: false,
    
    // 커버리지 최적화
    coverage: {
      provider: 'v8', // c8보다 빠름
      reporter: ['text', 'json', 'html'],
      exclude: [
        'node_modules/',
        'test/',
        '**/*.test.ts'
      ]
    }
  }
})