React Testing Library 및 Vitest 기반 테스팅 모범 관례. 다음 상황에서 사용: (1) .test.tsx, .test.ts, .spec.tsx, .spec.ts 파일 작업 시, (2) 컴포넌트 테스트 작성 또는 리팩토링 시, (3) 'test', 'testing', 'vitest', 'RTL', 'getByRole', 'userEvent', 'waitFor', 'expect' 키워드 포함 작업 시, (4) 비동기 로직 또는 사용자 상호작용 테스트 작성 시

Testing Library React Testing Library 기반 테스트 작성 모범 관례 및 안티패턴 회피 가이드. 핵심 원칙 Testing Library의 철학: 사용자가 사용하는 방식대로 테스트하라 1. 접근성 기반 쿼리 우선 실제 사용자가 요소를 찾는 방식 사용 2. 구현 세부사항 테스트 금지 컴포넌트 내부 상태/메서드 직접 접근 지양 3. 실제 사용자 행동 시뮬레이션 userEvent 사용, fireEvent 지양 4. 비동기 처리 명시적 대기 waitFor, findBy 활용 쿼리 우선순위 Testing Library는 다양한 쿼리를 제공하지만, 접근성과 사용자 경험을 반영하는 순서 로 사용해야 함. 권장 쿼리 순서 (높음 → 낮음) 1. getByRole (최우선) 스크린 리더가 인식하는 방식 2. getByLabelText 폼 요소 (label과 연결된 input) 3. getByPlaceholderText placeholder가 명확한 경우 4. getByText 텍스트 콘텐츠로 검색 5. getByDisplayValue 현재 입력된 값으로 검색 (폼 요소) 6. getByAltText 이미지 alt 속성 7. getByTitle title 속성 (tooltip 등) 8. getByTestId (최후 수단) 다른 방법이 불가능할 때만 사용 상세 가이드 : [references/query priority.md](references/query priority.md) 사용자 상호작용 테스트 userEvent 사용 (권장) 핵심 : userEvent.setup() 호출 후 사용 모든 user 메서드는 await 필수 실제 브라우저 이벤트 순서 재현 (focus, keydown, keyup 등) fireEvent 지양 상세 가이드 : [references/user events.md](references/user events.md) 비동기 처리 findBy 쿼리 (권장) findBy = getBy + waitFor 조합 (자동으로 요소 나타날 때까지 대기) waitFor 사용 안티패턴 상세 가이드 : [references/async patterns.md](references/async patterns.md) 자주 하는 실수 1. 구현 세부사항 테스트 2. container 쿼리 사용 3. 불필요한 waitFor 4. getBy + toBeInTheDocument() 제거 getBy 는 요소를 못 찾으면 throw하므로 toBeInTheDocument() 는 기술적으로 중복이다. 하지만 제거하지 마라 — 리팩토링 후 남은 쿼리가 아니라 의도적인 존재 검증임을 코드 독자에게 전달하는 역할을 한다. 단, 존재 검증이 아닌 다른 속성을 검증할 때는 toBeInTheDocument() 를 추가할 필요 없다: 전체 안티패턴 목록 : [references/common mistakes.md](references/common mistakes.md) Vitest + MSW 설정 테스트 환경 설정이 필요한 경우 다음 템플릿 참조: assets/vitest.config.ts Vitest 설정 (React 플러그인, 커버리지 포함) assets/test setup.ts Vitest 글로벌 설정 assets/msw setup.ts MSW 핸들러 및 서버 설정