@jjades/msw-auto-mock
Advanced tools
OpenAPI 스펙을 기반으로 MSW(Mock Service Worker) 핸들러를 자동으로 생성해주는 라이브러리입니다.
npm registry에 배포 전이므로, portal 방식으로 link합니다.
먼저 my-project와 msw-auto-mock을 같은 최상위 디렉토리에 위치시킵니다:
/workspace
├── my-project/ # 구현 프로젝트
└── msw-auto-mock/ # 라이브러리
msw-auto-mock 설정msw-auto-mock 디렉토리에서:
cd msw-auto-mock
pnpm install
pnpm build
my-project 설정my-project 디렉토리에서:
package.json에 다음 설정을 추가:{
"scripts": {
"generate-msw-mock": "tsx src/app/mocks/mock-generator.ts"
},
"devDependencies": {
"@dhlab/msw-auto-mock": "^0.31.0"
},
"resolutions": {
"@dhlab/msw-auto-mock": "portal:../msw-auto-mock"
}
}
cd my-project
yarn
my-project에 mock-generator 스크립트 추가my-project/src/app/mocks/mock-generator.ts 파일을 생성:
import { type TOptions, generateMocks } from '@dhlab/msw-auto-mock';
import type { TControllers } from './__types__/index';
import { controllers } from './controllers/index';
async function autoGenerateMocks() {
try {
console.log('[MSW] 목 파일 생성 시작...');
const options: TOptions<TControllers> = {
controllers,
input: './swagger/openapi.yml',
outputDir: './src/app/mocks',
environment: 'react',
baseUrl: 'https://api.example.com/api/v1',
};
const result = await generateMocks(options);
console.log('[MSW] 목 파일 생성 완료!');
console.log('[MSW] 생성된 파일 경로:', result.targetFolder);
return result;
} catch (error) {
console.error('[MSW] 목 파일 생성 중 오류 발생:', error);
throw error;
}
}
autoGenerateMocks();
my-project 디렉토리에서:
yarn generate-msw-mock
const options: ProgrammaticOptions = {
/**
* OpenAPI 스펙 파일 경로
* YAML 또는 JSON 형식 지원
* @required
*/
input: './swagger/openapi.yml',
/**
* 생성된 핸들러 파일이 저장될 디렉토리
* @optional
* @default 'src/app/mocks'
*/
outputDir: './src/app/mocks',
/**
* API 기본 URL
* @optional
* - string: 지정된 URL을 기본 URL로 사용
* - true: OpenAPI 스펙의 servers[0].url을 기본 URL로 사용
*/
baseUrl: 'https://api.example.com',
/**
* 생성할 mock 파일의 환경 설정
* @optional
* @default 'react'
* - next: Node.js와 브라우저 환경을 위한 mock 파일 생성
* - react: 브라우저 환경을 위한 mock 파일 생성
* - react-native: React Native 환경을 위한 mock 파일 생성
*/
environment: 'react',
/**
* 배열 응답의 최대 길이
* @optional
* @default 3
* faker.js로 생성되는 배열 응답의 최대 아이템 개수를 제한합니다.
* 예: users 배열이 100개의 아이템을 가질 수 있더라도, maxArrayLength: 3으로 설정하면
* 최대 3개의 사용자 데이터만 생성됩니다.
*/
maxArrayLength: 3,
/**
* 포함할 API 경로 패턴
* @optional
* 예: '/api/v1/*' - /api/v1/로 시작하는 경로만 포함
*/
includes: '/api/v1/*',
/**
* 제외할 API 경로 패턴
* @optional
* 예: '/api/v1/health' - /api/v1/health 경로 제외
*/
excludes: '/api/v1/health',
/**
* HTTP 상태 코드
* @optional
* 예: '200,201' - 200과 201 상태 코드만 사용
*/
codes: '200,201',
/**
* 정적 응답 사용 여부
* @optional
* @default false
* true: faker.js를 사용하지 않고 정적 응답 생성
*/
static: false,
/**
* 사용자 정의 응답 컨트롤러
* @optional
* faker.js를 사용하지 않고 API 엔드포인트별 커스텀 응답 생성
*/
controllers: {
getGetUsersUsersGet200Response: () => userList,
...
},
/**
* 컨트롤러 import 경로
* @optional
* @default '@/app/mocks/controllers'
*/
controllerPath: '@/app/mocks/controllers',
/**
* DTO 타입 import 경로
* @optional
* @default '@/shared/api/dto'
* FSD(Feature-Sliced Design) 패러다임에 따라 기본값이 @/shared/api/dto로 설정됩니다.
*/
dtoImportPath: '@/shared/api/dto',
};
src/app/mocks/
├── __types__/
│ ├── users.type.ts
│ ├── chats.type.ts
│ ├── ...
│ ├── index.ts
├── __handlers__/
│ ├── users.handlers.ts
│ ├── chats.handlers.ts
│ └── ...
│ └── index.ts
└── browser.ts
generateMocks 함수는 다음과 같은 이유로 CommonJS로만 빌드됩니다:
@apidevtools/swagger-parser, swagger2openapi 등의 핵심 의존성이 ESM을 지원하지 않음fs, path 모듈을 직접 사용하여 파일 생성 작업 수행React 프로젝트에서는 다음과 같은 방식으로 ESM을 완전히 지원합니다:
// ✅ React 환경에서 ESM 사용 가능
import { selectResponseByScenario, transformJSONSchemaToFakerCode } from '@dhlab/msw-auto-mock';
// ✅ Node.js 빌드 스크립트에서 CommonJS 사용
// (예: React 프로젝트의 scripts/mock-generator.ts)
import { generateMocks } from '@dhlab/msw-auto-mock/node';
@dhlab/msw-auto-mock
├── dist/
│ ├── index.js # ESM (브라우저, React 등)
│ ├── index.cjs # CommonJS (Node.js 호환)
│ └── node/
│ └── node.cjs # Node.js 전용 CommonJS
이 구조를 통해:
npm install @dhlab/msw-auto-mock
# 또는
yarn add @dhlab/msw-auto-mock
# 또는
pnpm add @dhlab/msw-auto-mock
환경에 상관없이 사용할 수 있는 기능들입니다.
// 타입 정의, 시나리오 선택, 가짜 데이터 생성 등
import {
selectResponseByScenario,
transformJSONSchemaToFakerCode,
type TOptions,
type TScenarioConfig,
type ResponseObject
} from '@dhlab/msw-auto-mock';
Node.js 환경에서는 OpenAPI 스키마를 기반으로 MSW 핸들러 파일을 생성할 수 있습니다.
// Node.js 전용 기능
import { generateMocks } from '@dhlab/msw-auto-mock/node';
// 환경 상관없이 사용 가능한 기능들 (필요시 별도 import)
import {
selectResponseByScenario,
transformJSONSchemaToFakerCode,
type TOptions
} from '@dhlab/msw-auto-mock';
await generateMocks({
input: 'path/to/openapi.json',
outputDir: 'src/mocks',
environment: 'react' // 'react', 'next', 'react-native'
});
import React, { useState, useEffect } from 'react';
import { http, HttpResponse } from 'msw';
import { selectResponseByScenario, transformJSONSchemaToFakerCode } from '@dhlab/msw-auto-mock';
const MyComponent: React.FC = () => {
const [mockData, setMockData] = useState(null);
useEffect(() => {
// 시나리오 설정
const scenarios = {
'user-error': {
description: '사용자 오류 시나리오',
api: {
'/api/users': {
'GET': { status: 400 }
}
}
},
'success': {
description: '성공 시나리오',
api: {
'/api/users': {
'GET': { status: 200 }
}
}
},
'custom-error': {
description: '커스텀 에러 시나리오',
api: {
'/api/users': {
'GET': { status: 418, allowCustomStatus: true }
}
}
}
};
// MSW 핸들러 설정
const handler = http.get('/api/users', (info) => {
const responses = [
{ status: 200, responseType: 'application/json', body: JSON.stringify({ users: [] }) },
{ status: 400, responseType: 'application/json', body: JSON.stringify({ error: 'Bad Request' }) },
{ status: 500, responseType: 'application/json', body: JSON.stringify({ error: 'Server Error' }) }
];
const selectedResponse = selectResponseByScenario('GET', '/api/users', responses, info, scenarios);
return HttpResponse.json(
JSON.parse(selectedResponse.body || '{}'),
{ status: selectedResponse.status }
);
});
// 가짜 데이터 생성 예제
const userSchema = {
type: 'object',
properties: {
id: { type: 'string', format: 'uuid' },
name: { type: 'string' },
email: { type: 'string', format: 'email' },
age: { type: 'integer', minimum: 18, maximum: 100 }
}
};
const fakerCode = transformJSONSchemaToFakerCode(userSchema);
console.log('Generated faker code:', fakerCode);
}, []);
return (
<div>
<h1>MSW Auto Mock React Example</h1>
{/* 컴포넌트 내용 */}
</div>
);
};
// pages/api/mocks/setup.ts 또는 app/api/mocks/setup/route.ts
import { generateMocks } from '@dhlab/msw-auto-mock/node';
import type { TOptions } from '@dhlab/msw-auto-mock';
export default async function handler(req: any, res: any) {
if (process.env.NODE_ENV === 'development') {
const options: TOptions = {
input: './public/openapi.json',
outputDir: './src/mocks',
environment: 'next'
};
await generateMocks(options);
res.status(200).json({ message: 'Mocks generated successfully' });
} else {
res.status(404).json({ message: 'Not found' });
}
}
// components/MockProvider.tsx
import React from 'react';
import { selectResponseByScenario } from '@dhlab/msw-auto-mock';
export const MockProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
// 브라우저 환경에서 MSW 설정
React.useEffect(() => {
if (typeof window !== 'undefined') {
import('../mocks/browser').then(({ worker }) => {
worker.start();
});
}
}, []);
return <>{children}</>;
};
selectResponseByScenario시나리오 기반으로 응답을 선택하는 함수입니다. 헤더 x-scenario를 통해 특정 시나리오를 활성화할 수 있습니다.
function selectResponseByScenario(
verb: string,
path: string,
resultArray: ResponseObject[],
info: Parameters<HttpResponseResolver<Record<string, never>, null>>[0],
scenarios?: TScenarioConfig
): ResponseObject
allowCustomStatus 기능기본적으로 시나리오에서는 OpenAPI 명세에 정의된 status 코드만 사용할 수 있습니다. 하지만 allowCustomStatus: true를 설정하면 명세에 없는 임의의 status 코드도 사용할 수 있습니다.
사용 예시:
// 시나리오 설정
const scenarios = {
'success': {
description: '성공 시나리오',
api: {
'/api/users': { 'GET': { status: 200 } }
}
},
'error': {
description: '에러 시나리오',
api: {
'/api/users': { 'GET': { status: 500 } }
}
},
'custom-error': {
description: '커스텀 에러 시나리오',
api: {
'/api/users': {
'GET': {
status: 418, // "I'm a teapot" - OpenAPI 명세에 없는 status
allowCustomStatus: true
}
}
}
}
};
// MSW 핸들러에서 사용
const handler = http.get('/api/users', (info) => {
const responses = [
{ status: 200, responseType: 'application/json', body: '{"users": []}' },
{ status: 500, responseType: 'application/json', body: '{"error": "Server Error"}' }
];
// 헤더 기반 시나리오 선택 - 이제 ResponseObject를 직접 반환
const selectedResponse = selectResponseByScenario('GET', '/api/users', responses, info, scenarios);
return HttpResponse.json(JSON.parse(selectedResponse.body || '{}'), {
status: selectedResponse.status
});
});
테스트 시나리오 제어:
# 성공 시나리오 테스트
curl -H "x-scenario: success" http://localhost:3000/api/users
# 에러 시나리오 테스트
curl -H "x-scenario: error" http://localhost:3000/api/users
# 커스텀 에러 시나리오 테스트 (OpenAPI 명세에 없는 418 status)
curl -H "x-scenario: custom-error" http://localhost:3000/api/users
# 기본 시나리오 (헤더 없음 - 성공 응답 우선)
curl http://localhost:3000/api/users
transformJSONSchemaToFakerCodeOpenAPI 스키마를 Faker.js 코드로 변환하는 함수입니다.
function transformJSONSchemaToFakerCode(
jsonSchema?: OpenAPIV3.SchemaObject,
key?: string
): string
allowCustomStatus: true 기능은 다음과 같은 상황에서 유용합니다:
// OpenAPI 명세에 200, 400, 500만 정의되어 있다고 가정
const scenarios = {
'teapot-error': {
description: '티팟 에러 테스트',
api: {
'/api/users': {
'GET': {
status: 418, // 명세에 없는 status
allowCustomStatus: true // 허용 플래그
}
}
}
}
};
allowCustomStatus: true로 설정된 시나리오가 활성화되면:
{
"error": "Client Error", // 400-499는 "Client Error"
"status": 418
}
또는
{
"error": "Internal Server Error", // 500+는 "Internal Server Error"
"status": 503
}
TypeScript를 사용하는 경우:
// ❌ 컴파일 에러 - 명세에 없는 status
const badScenario = {
api: {
'/api/users': {
'GET': { status: 418 } // allowCustomStatus 없이는 사용 불가
}
}
};
// ✅ 정상 - allowCustomStatus로 명시적 허용
const goodScenario = {
api: {
'/api/users': {
'GET': { status: 418, allowCustomStatus: true }
}
}
};
allowCustomStatus는 명세와 목업 간의 일치성을 일부 포기하는 트레이드오프입니다export type TScenarioConfig = {
[scenarioId: string]: {
description: string;
api: Record<string, Record<string, {
status: number;
allowCustomStatus?: boolean;
}>>;
};
};
export type ResponseObject = {
status: number;
responseType: string | undefined;
body: string | undefined;
};
이 라이브러리는 기능별로 분리된 패키지로 제공됩니다:
@dhlab/msw-auto-mock
├── dist/
│ ├── index.js # 기본 ESM (환경 상관없이)
│ ├── index.cjs # 기본 CommonJS (환경 상관없이)
│ └── node/
│ ├── node.js # Node.js 전용 ESM
│ └── node.cjs # Node.js 전용 CommonJS
import { ... } from '@dhlab/msw-auto-mock'import { generateMocks } from '@dhlab/msw-auto-mock/node'// React/Vue/Angular 등 모든 환경에서
import { selectResponseByScenario, transformJSONSchemaToFakerCode } from '@dhlab/msw-auto-mock';
// Node.js에서 파일 생성 기능이 필요한 경우
import { generateMocks } from '@dhlab/msw-auto-mock/node';
// 둘 다 필요하면 각각 import
import { selectResponseByScenario } from '@dhlab/msw-auto-mock';
import { generateMocks } from '@dhlab/msw-auto-mock/node';
MIT
FAQs
Generate random mock data from OpenAPI descriptions for msw.
We found that @jjades/msw-auto-mock demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A large-scale campaign abused GitHub Actions in compromised repositories to exploit CVE-2026-41940 in cPanel and WHM and steal server credentials.
Security News
Five frontier LLMs generated the same nonexistent package names, leaving 53 available for potential slopsquatting across PyPI and npm.
Security News
The White House’s Gold Eagle Initiative aims to coordinate AI-discovered vulnerabilities, validate findings, and accelerate patching across critical software.