/setup-test

name: setup-test
description: 프론트엔드 프로젝트에 테스트 환경을 초기 세팅합니다. 프로젝트 구조를 자동 감지하여 jest/vitest 설정, customRender, MSW 등을 구성합니다.
category: setup
user-invocable: false

/setup-test

테스트 환경이 없는 프로젝트에 초기 세팅을 수행합니다.

실행 워크플로우

Step 1: 프로젝트 분석

다음을 자동 감지합니다:

1. **프레임워크 감지:**

• `next.config.*` -> Next.js
• `vite.config.*` -> Vite
• `react-scripts` in package.json -> CRA
• 기타 -> 일반 React

2. **기존 테스트 환경 확인:**

• `jest.config.*` / `vitest.config.*` 존재 여부
• package.json에 test 스크립트 존재 여부
• `@testing-library/react` 설치 여부
• MSW 설치 여부

3. **상태 관리 / Provider 구조 분석:**

• `_app.tsx` / `_app.js` 읽기 -> Provider 트리 파악
• `Provider/` 디렉토리 탐색
• package.json에서 jotai, recoil, zustand, react-query 등 확인

4. **사용자에게 분석 결과 보고 후 진행 여부 확인:**

   프로젝트 분석 결과:
   - 프레임워크: Next.js 13 (Pages Router)
   - 테스트 러너: 미설정 -> jest 권장
   - 상태 관리: jotai, react-query
   - Provider: QueryClientProvider, JotaiProvider

   다음 항목을 세팅하겠습니다:
   1. jest + @testing-library/react + MSW 패키지 설치
   2. jest.config.js 생성
   3. jest.setup.js 생성
   4. customRender 유틸리티 생성
   5. MSW 핸들러 구조 생성
   6. package.json test 스크립트 추가

   진행할까요?

Step 2: 패키지 설치

**jest 기반 (Next.js, CRA):**

yarn add -D jest @testing-library/react @testing-library/jest-dom @testing-library/user-event jest-environment-jsdom @types/jest msw identity-obj-proxy

Next.js 프로젝트 추가:

yarn add -D jest-next-dynamic

**vitest 기반 (Vite):**

yarn add -D vitest @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom @types/jest msw

Step 3: 설정 파일 생성

**jest.config.js** (Next.js 예시):

• moduleNameMapper: path alias (@/, @shared/ 등) 매핑
• testEnvironment: jsdom
• setupFilesAfterSetup: jest.setup.js
• transformIgnorePatterns: node_modules 중 ESM 모듈 처리
• moduleFileExtensions: js, jsx, ts, tsx

**jest.setup.js:**

• `@testing-library/jest-dom` import
• 전역 mock 설정 (next/router, next/dynamic, SVG, CSS 등)
• MSW server setup/teardown
• window.matchMedia mock

Step 4: customRender 생성

`__tests__/utils/customRender.tsx` (또는 `src/test/customRender.tsx`):

프로젝트의 Provider 구조를 분석하여 생성합니다:

• QueryClientProvider (react-query 사용 시)
• RecoilRoot (recoil 사용 시)
• JotaiProvider (jotai 사용 시, 필요한 경우)
• FormProvider (react-hook-form 사용 시)
• 기타 프로젝트 커스텀 Provider

Step 5: MSW 핸들러 구조 생성

src/mocks/
├── server.ts          # MSW setupServer
├── handlers/
│   └── index.ts       # 핸들러 모음
└── browser.ts         # (선택) 브라우저용 setupWorker

Step 6: package.json 스크립트 추가

{
  "scripts": {
    "test": "jest --watchAll",
    "test:ci": "jest --ci --coverage"
  }
}

Step 7: 검증

간단한 샘플 테스트를 실행하여 환경이 올바르게 구성되었는지 확인합니다:

yarn test --watchAll=false

주의사항

• 이미 테스트 환경이 구성된 프로젝트에서는 기존 설정을 덮어쓰지 않고, 누락된 부분만 보완합니다.
• path alias 매핑은 프로젝트의 tsconfig.json / jsconfig.json을 참고하여 생성합니다.
• 패키지 매니저는 프로젝트의 lock 파일을 확인하여 자동 결정합니다 (yarn.lock -> yarn, package-lock.json -> npm, pnpm-lock.yaml -> pnpm).