MSW 활용기 | (1) 소개 및 적용기
📌 이 글은 MSW 시리즈 중 1편입니다.
2편: Mock API Schema 자동 생성하기
3편: Plugin 방식으로 제공하기
도입 배경
대부분의 프로젝트는
UI 개발 → 대기(백엔드 API 준비) → API 연동 순으로 진행됩니다.
프런트엔드 입장에선 대기 시간이 길어질수록 전체 일정과 QA 일정이 밀려 개발 효율이 저하됩니다. 이를 개선하기 위해 MSW를 도입했습니다.
MSW 소개
MSW(Mock Service Worker) 는 Service Worker를 이용해 네트워크 요청을 가로채고 모의 응답을 반환하는 API 모킹 라이브러리입니다.
서버를 별도 구축할 필요 없이 브라우저·Node 환경 모두에서 동일한 핸들러를 재사용할 수 있습니다.
MSW의 특징
1. Service Worker란?
- 메인 스레드와 분리된 백그라운드 스레드
- 요청 가로채기, 캐싱, 오프라인 처리 등 가능
- IE 미지원, HTTPS(또는 localhost) 요구
2. MSW 동작 원리
- 브라우저에 Service Worker 설치
- 네트워크 요청 가로채기
- 일치하는 핸들러가 있으면 Mock 응답 반환
- 서버가 없어도 프론트 개발·테스트 가능
3. 개발 플로우 예시
- 기획서 확정 후 API 스펙 합의
- 프런트는 MSW로 Mocking 하며 UI 개발
- 백엔드 API 제공 시 스위치만 끄고 실서버 통신
- 동일 코드로 QA → 프로덕션 배포
다른 라이브러리와의 차이점
| 라이브러리 | 특징 | 한계 |
|---|---|---|
| axios-mock-adapter | axios 전용·코드 내부 모킹 | 네트워크 레이어 가로채기 불가 |
| nock | Node 환경 전용 | 브라우저 미지원 |
| MSW | Service Worker 기반 네트워크 모킹 | 초기 HTTPS 설정 필요 |
설치 및 구성
환경
- Node v16.20.1
- Vue v2.7.16 + Vite v4.5.3
- MSW v2.2.14
- vite-plugin-mkcert v1.17.5
1. 패키지 설치 및 초기화
1
2
3
4
5
# MSW 설치
npm i -D msw
# public 디렉터리에 Service Worker 스크립트 생성
npx msw init public/
2. 핸들러 및 워커 설정 API 요청을 가로채서 반환할 모의 응답을 정의하는 핸들러를 작성하고, 이를 서비스 워커에 등록합니다.
1
2
3
4
5
6
7
8
// @/mocks/sampleHandler.js
import { http, HttpResponse } from 'msw'
export const handlers = [
http.get('/api/user', () => {
return HttpResponse.json({ name: 'Ji-hun Seo' })
})
]
1
2
3
4
5
6
7
8
9
// @/mocks/mswSetupWorker.js
import { setupWorker } from 'msw/browser'
import { handlers } from '@/mocks/sampleHandler'
// 워커 설정 및 시작
export const initMSW = () => {
const worker = setupWorker(...handlers)
worker.start({ onUnhandledRequest: 'bypass' }) // 처리되지 않은 요청은 실제 서버로 전달
}
3. HTTPS 개발 서버 설정 (mkcert) Service Worker는 localhost 또는 HTTPS 환경에서만 동작하므로, mkcert를 사용해 로컬 HTTPS 환경을 구축합니다.
1
2
3
4
5
6
# mkcert 설치 및 로컬 인증서 생성
brew install mkcert
mkcert -install && mkcert localhost
# Vite 플러그인 설치
npm i -D vite-plugin-mkcert
vite.config.js에 플러그인을 추가합니다.
1
2
3
4
5
6
7
8
// vite.config.js
import { defineConfig } from 'vite'
import mkcert from 'vite-plugin-mkcert'
export default defineConfig({
server: { https: true },
plugins: [mkcert()]
})
SSL 설정이 되어있지 않다면 위와 같은 에러를 만나게 됩니다.
MSW에서 권장하는 방법은 시스템 레벨, 브라우저 레벨 2가지가 있습니다.
저는 전자를 선택했습니다.
4. 어플리케이션에 적용 main.js에서 initMSW()를 호출하여 MSW를 활성화합니다.
1
2
3
4
// main.js
import { initMSW } from '@/mocks/mswSetupWorker'
initMSW()
동작 확인
MSW가 정상 설치되면 브라우저 콘솔에
[MSW] Mocking enabled. 메시지가 출력되고 Network 탭에서 Service Worker 응답을 확인할 수 있습니다.
시행착오
- 브라우저 vs Node 혼용
Node 핸들러까지 설정하려다 불필요한 의존성을 추가해 빌드 오류 다발 → 브라우저 전용으로 정리 - Vite 3 → 4 업그레이드
GraphQL import 문법 오류(Unexpected string) 발생 → Vite 4로 올려 해결 - HTTPS 인증 문제
브라우저-레벨 인증만으로는 팀원 PC에서 미작동 → mkcert로 시스템 레벨 인증서 적용 - 버전·스키마 변경으로 핸들러 불일치 → 공식문서·커뮤니티 사례 참고 후 수정
기술 스택 (Tech Stack)
MSW Vue.js Vite mkcert Swagger UI faker json-schema-faker
추후 할 일
- API 스키마 자동 수집 → Mock 생성 파이프라인화
- Storybook + MSW 연동
- MSW 툴바 UI & Mock 데이터 관리 도구 개발
참고
🗓️ 업데이트 내역
- 2025-07-29:
- MSW Node환경 적용 및 Vitest 연동
- 개발 기간: 25.07.25 - 25.07.29
- 2024-12-10:
- 코드 리팩토링 및 Mixin 방식 추가
- 개발 기간: 24.11.28 - 24.12.10