MSW는 프로덕션 빌드에도 포함해야 하나요?

일반적으로 아닙니다. MSW는 개발·테스트·스토리북에서 사용하고, 실제 서비스 배포 시에는 핸들러를 등록하지 않거나 worker.stop()·조건부 부트스트랩으로 제외해 네트워크가 실서버로 가도록 합니다. 번들에 남기면 Service Worker·모킹 오버헤드가 섞이므로 환경 변수로 끄는 패턴이 흔합니다.

브라우저(setupWorker)와 Node(setupServer) 중 어떤 것을 써야 하나요?

같은 핸들러로 브라우저 개발(실제 fetch·Network 탭)은 setupWorker, Jest·Vitest·Node 스크립트는 setupServer를 씁니다. 통합·E2E는 실행 환경에 맞게 하나를 선택하고, 핸들러는 공유해 중복을 줄이면 됩니다.

npx msw init public/으로 만든 mockServiceWorker.js는 무엇인가요?

MSW 런타임이 스크립트 URL로 Service Worker를 등록하도록 두는 정적 자산입니다. public에 넣어 개발 서버·정적 호스트에서 그대로 서빙되게 하고, MSW 버전 업 시 재생성해 스크립트와 런타임 버전을 맞춥니다.

핸들러는 어디까지 정의하는 것이 좋나요?

필요한 API와 시나리오(성공·에러·지연)만 정의하는 것이 좋습니다. 전역으로 모든 경로를 막지 말고, http.get/http.post 등으로 엔드포인트를 나누고 공통 resolver·팩토리로 응답을 재사용하면 유지보수가 쉬워집니다.

MSW 완벽 가이드 | API Mocking·Service Worker·테스트·실전 활용

2026년 4월 7일 · 4분 읽기 · 수정 2026년 4월 18일 중급

이 글의 핵심

MSW로 API Mocking을 구현하는 완벽 가이드. Request Handlers, Response Resolver, Browser/Node 통합, Testing까지 실전 예제로 정리. Start now.

이 글의 핵심

MSW로 API Mocking을 구현하는 완벽 가이드입니다. Request Handlers, Response Resolver, Browser/Node 통합, Testing까지 실전 예제로 정리했습니다.

실무 경험 공유: 백엔드 API 없이 프론트엔드 개발을 진행하면서, MSW로 개발 속도가 2배 향상된 경험을 공유합니다.

들어가며: “백엔드 API를 기다려야 해요”

실무 문제 시나리오

시나리오 1: 백엔드 개발이 늦어요

API를 기다려야 합니다. MSW로 Mock API를 만듭니다. 시나리오 2: 테스트에서 실제 API를 호출해요

느리고 불안정합니다. MSW로 Mock 응답을 반환합니다. 시나리오 3: 에러 상황 테스트가 어려워요

실제로 에러를 만들기 어렵습니다. MSW로 쉽게 시뮬레이션합니다.

1. MSW란?

API Mocking의 진화: Stub → Interceptor → Service Worker

전통적인 API Mocking 방식은 두 가지였습니다:

라이브러리 Stub (axios-mock-adapter, nock)
- axios·fetch를 직접 가로채서 Mock 응답 반환
- 문제: 실제 네트워크 요청이 발생하지 않음 → 개발자 도구 Network 탭에 안 보임
Mock Server (json-server, mirage)
- 별도 포트(:3001)에서 Mock API 서버 실행
- 문제: 프로덕션 코드(/api/users)와 다른 URL(localhost:3001/users) 사용

MSW(Mock Service Worker, 2019)는 Service Worker API로 이 문제를 해결했습니다:

네트워크 레벨에서 intercept → 실제 HTTP 요청이 발생
개발자 도구에 보임 → Network 탭에서 200 OK 확인 가능
프로덕션 URL 그대로 → /api/users 그대로 사용

Service Worker API: 브라우저의 네트워크 프록시

Service Worker는 원래 PWA(Progressive Web App)를 위해 만들어진 W3C 표준입니다. 브라우저와 서버 사이에서 프록시 역할을 합니다.

브라우저 (fetch('/api/users'))
    ↓
Service Worker (MSW가 여기서 intercept)
    ↓ (Mock이면 여기서 응답 반환)
    ↓ (Mock 없으면 실제 네트워크로 통과)
실제 서버

MSW의 동작:

npx msw init public/ → mockServiceWorker.js 생성
브라우저가 이 Worker 등록
모든 fetch() 요청이 Worker를 거침
MSW가 핸들러에 매칭되는지 확인
매칭되면 Mock 응답, 아니면 실제 네트워크로 통과

MSW vs 기존 Mocking 방식

측면	MSW	axios-mock-adapter	json-server
동작 위치	Service Worker (네트워크)	라이브러리 내부	별도 서버
Network 탭	✅ 보임	❌ 안 보임	✅ 보임
URL	프로덕션과 동일	프로덕션과 동일	다른 포트
브라우저	✅	✅	✅
Node(테스트)	✅	✅	❌ (별도 실행 필요)
코드 수정	불필요	불필요	URL 변경 필요

핵심 특징

MSW (Mock Service Worker)는 Service Worker 기반 API Mocking 라이브러리입니다. 주요 장점:

Service Worker: 네트워크 레벨 Mocking (실제 HTTP 요청 발생)
브라우저 + Node: 개발(Service Worker) + 테스트(Node.js Interceptor)
타입 안전: TypeScript 지원 (Request·Response 타입)
실제와 동일: 개발자 도구 Network 탭에서 확인 가능
Zero Config: 프로덕션 코드 수정 불필요

사용 시나리오:

백엔드 API 개발 전 프론트엔드 개발
E2E 테스트에서 외부 API 의존성 제거
에러·타임아웃·로딩 상태 시뮬레이션
다양한 응답 케이스 빠르게 테스트

2. 설치 및 설정

설치

npm install -D msw

Service Worker 생성

npx msw init public/ --save

3. Handlers 정의

// src/mocks/handlers.ts
import { http, HttpResponse } from 'msw';
export const handlers = [
  http.get('/api/users', () => {
    return HttpResponse.json([
      { id: 1, name: 'John', email: '[email protected]' },
      { id: 2, name: 'Jane', email: '[email protected]' },
    ]);
  }),
  http.post('/api/users', async ({ request }) => {
    const newUser = await request.json();
    return HttpResponse.json(
      { id: 3, ...newUser },
      { status: 201 }
    );
  }),
  http.delete('/api/users/:id', ({ params }) => {
    return HttpResponse.json(
      { success: true },
      { status: 200 }
    );
  }),
];

4. 브라우저 통합

// src/mocks/browser.ts
import { setupWorker } from 'msw/browser';
import { handlers } from './handlers';
export const worker = setupWorker(...handlers);
// src/main.tsx
import { worker } from './mocks/browser';
if (process.env.NODE_ENV === 'development') {
  worker.start();
}

5. Node 통합 (테스트)

// src/mocks/server.ts
import { setupServer } from 'msw/node';
import { handlers } from './handlers';
export const server = setupServer(...handlers);
// src/setupTests.ts
import { server } from './mocks/server';
beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

6. Response Resolver

동적 응답

http.get('/api/users/:id', ({ params }) => {
  const { id } = params;
  if (id === '1') {
    return HttpResponse.json({ id: 1, name: 'John' });
  }
  return HttpResponse.json(
    { error: 'User not found' },
    { status: 404 }
  );
});

지연

import { delay } from 'msw';
http.get('/api/users', async () => {
  await delay(2000);
  return HttpResponse.json([]);
});

7. 에러 시뮬레이션

http.get('/api/users', () => {
  return HttpResponse.json(
    { error: 'Internal Server Error' },
    { status: 500 }
  );
});
http.get('/api/users', () => {
  return HttpResponse.error();
});

8. 테스트에서 사용

// src/components/UserList.test.tsx
import { render, screen } from '@testing-library/react';
import { server } from '../mocks/server';
import { http, HttpResponse } from 'msw';
import UserList from './UserList';
test('loads and displays users', async () => {
  render(<UserList />);
  expect(await screen.findByText('John')).toBeInTheDocument();
  expect(screen.getByText('Jane')).toBeInTheDocument();
});
test('handles error', async () => {
  server.use(
    http.get('/api/users', () => {
      return HttpResponse.json(
        { error: 'Failed to fetch' },
        { status: 500 }
      );
    })
  );
  render(<UserList />);
  expect(await screen.findByText('Failed to fetch')).toBeInTheDocument();
});

9. GraphQL Mocking

import { graphql, HttpResponse } from 'msw';
const handlers = [
  graphql.query('GetUser', ({ variables }) => {
    return HttpResponse.json({
      data: {
        user: {
          id: variables.id,
          name: 'John',
        },
      },
    });
  }),
  graphql.mutation('CreateUser', async ({ variables }) => {
    return HttpResponse.json({
      data: {
        createUser: {
          id: 3,
          ...variables.input,
        },
      },
    });
  }),
];

정리 및 체크리스트

핵심 요약

MSW: Service Worker 기반 API Mocking
브라우저 + Node: 개발 + 테스트
타입 안전: TypeScript 지원
실제와 동일: 실제 HTTP 요청
에러 시뮬레이션: 쉬운 에러 테스트
GraphQL: GraphQL Mocking

구현 체크리스트

같이 보면 좋은 글

이 글에서 다루는 키워드

MSW, Mock Service Worker, API Mocking, Testing, Service Worker, Frontend

내부 동작과 핵심 메커니즘

이 글의 주제는 「MSW 완벽 가이드 | API Mocking·Service Worker·테스트·실전 활용」입니다. 여기서는 앞선 설명을 구현·런타임 관점에서 한 번 더 압축합니다. 요청 경로와 상태 전이를 기준으로 생각하면, “입력이 어디서 검증되고, 핵심 연산이 어디서 일어나며, 부작용(I/O·네트워크·디스크)이 어디서 터지는가”가 한눈에 드러납니다.

처리 파이프라인(개념도)

flowchart TD
  A[입력·요청·이벤트] --> B[파싱·검증·디코딩]
  B --> C[핵심 연산·상태 전이]
  C --> D[부작용: I/O·네트워크·동시성]
  D --> E[결과·관측·저장]

알고리즘·프로토콜 관점에서의 체크포인트

불변 조건(Invariant): 각 단계가 만족해야 하는 조건(예: 버퍼 경계, 프로토콜 상태, 트랜잭션 격리)을 문장으로 적어 두면 디버깅 비용이 줄어듭니다.
결정성: 동일 입력에 동일 출력이 보장되는 순수한 층과, 시간·네트워크에 의해 달라질 수 있는 층을 분리해야 테스트와 장애 분석이 쉬워집니다.
경계 비용: 직렬화/역직렬화, 문자 인코딩, syscall 횟수, 락 경합처럼 “한 번의 호출이 아니라 누적되는 비용”을 의심 목록에 넣습니다.

프로덕션 운영 패턴

실서비스에서는 기능 구현과 함께 관측·배포·보안·비용이 동시에 요구됩니다. 아래는 팀에서 자주 쓰는 최소 체크리스트입니다.

영역	운영 관점에서의 질문
관측성	요청 단위 상관 ID, 에러율/지연 분위수, 주요 의존성 타임아웃이 보이는가
안전성	입력 검증·권한·비밀 관리가 코드 경로마다 일관적인가
신뢰성	재시도는 멱등한 연산에만 적용되는가, 서킷 브레이커·백오프가 있는가
성능	캐시 계층·배치 크기·풀링·백프레셔가 데이터 규모에 맞는가
배포	롤백 룬북, 카나리, 마이그레이션 호환성이 문서화되어 있는가

운영 환경에서는 “개발자 PC에서는 재현되지 않던 문제”가 시간·부하·데이터 크기 때문에 드러납니다. 따라서 스테이징의 데이터 양·네트워크 지연을 가능한 한 현실에 가깝게 맞추는 것이 중요합니다.

문제 해결(Troubleshooting)

증상	가능 원인	조치
간헐적 실패	레이스 컨디션, 타임아웃, 외부 의존성 불안정	최소 재현 스크립트 작성, 분산 트레이스·로그 상관관계 확인
성능 저하	N+1 쿼리, 동기 I/O, 잠금 경합, 과도한 직렬화	프로파일러·APM으로 핫스팟 확인 후 한 가지씩 제거
메모리 증가	캐시 무제한, 클로저/이벤트 구독 누수, 대용량 객체의 불필요한 복사	상한·TTL·스냅샷 비교(힙 덤프/트레이스)
빌드·배포만 실패	환경 변수·권한·플랫폼 차이	CI 로그와 로컬 `diff`, 컨테이너/런타임 버전 핀(pin)

권장 디버깅 순서: (1) 최소 재현 만들기 (2) 최근 변경 범위 좁히기 (3) 의존성·환경 변수 차이 확인 (4) 관측 데이터로 가설 검증 (5) 수정 후 회귀·부하 테스트.

자주 묻는 질문 (FAQ)

Q. 프로덕션에 포함되나요?

A. 아니요, 개발/테스트 환경에서만 사용됩니다.

Q. 실제 API 호출을 가로채나요?

A. 네, Service Worker를 통해 네트워크 레벨에서 가로챕니다.

Q. GraphQL도 지원하나요?

A. 네, GraphQL Query/Mutation을 모두 지원합니다.

Q. 프로덕션에서 사용해도 되나요?

A. 네, 많은 기업에서 개발/테스트 도구로 사용하고 있습니다.

이 글이 도움이 되셨나요?

여러분의 피드백은 더 나은 콘텐츠를 만드는 데 도움이 됩니다

문제가 있거나 개선 제안이 있으시면 연락처로 알려주세요.

Keyboard Shortcuts

이 글의 핵심

이 글의 핵심

들어가며: “백엔드 API를 기다려야 해요”

실무 문제 시나리오

실제로 에러를 만들기 어렵습니다. MSW로 쉽게 시뮬레이션합니다.

1. MSW란?

API Mocking의 진화: Stub → Interceptor → Service Worker

Service Worker API: 브라우저의 네트워크 프록시

MSW vs 기존 Mocking 방식

핵심 특징

2. 설치 및 설정

설치

Service Worker 생성

3. Handlers 정의

4. 브라우저 통합

5. Node 통합 (테스트)

6. Response Resolver

동적 응답

지연

7. 에러 시뮬레이션

8. 테스트에서 사용

9. GraphQL Mocking

정리 및 체크리스트

핵심 요약

구현 체크리스트

같이 보면 좋은 글

이 글에서 다루는 키워드

내부 동작과 핵심 메커니즘

처리 파이프라인(개념도)

알고리즘·프로토콜 관점에서의 체크포인트

프로덕션 운영 패턴

문제 해결(Troubleshooting)

자주 묻는 질문 (FAQ)

Q. 프로덕션에 포함되나요?

Q. 실제 API 호출을 가로채나요?

Q. GraphQL도 지원하나요?

Q. 프로덕션에서 사용해도 되나요?

이 글이 도움이 되셨나요?