docs: 테스트 작성 원칙 문서 보완

- pytest 자동 테스트 기준 섹션 추가 (섹션 6)
- pytest 없이 직접 실행하는 스크립트 금지 명시
- 중복 e2e 테스트 통합 규칙 추가
- 실제 정리 사례 추가 (섹션 9)
- 체크리스트에 pytest 검증 항목 추가
This commit is contained in:
Claude-51124 2026-01-03 12:59:57 +09:00
parent 764bccc4cb
commit 5547b280ce

View File

@ -102,7 +102,34 @@ def test_intent_classification(mock_llm_service):
---
## 6. 테스트 네이밍 및 구조
## 6. pytest 자동 테스트 기준
### 필수 요구사항
**pytest 자동 테스트 확인 방법**:
- `import pytest` 또는 `@pytest.mark.*` 데코레이터 사용
- `pytest tests/test_*.py` 명령으로 실행 가능
- `if __name__ == "__main__"` 직접 실행 코드 없어야 함
**금지 사항**:
- `python3 tests/test_*.py` 방식의 수동 실행 스크립트
- "pytest 없이 직접 실행" 주석이 있는 파일
- pytest import 없이 `def test_*()` 함수만 있는 파일 (pytest 미적용)
### 테스트 파일 검증
**추가 전 확인**:
```bash
# pytest로 실행 가능한지 확인
pytest tests/test_*.py -v
# pytest import 여부 확인
grep -l "import pytest\|@pytest" tests/test_*.py
```
---
## 7. 테스트 네이밍 및 구조
### 파일명 규칙
@ -117,32 +144,50 @@ def test_intent_classification(mock_llm_service):
- `test_*_refactoring.py` (작업 완료 후 삭제)
- `test_*_vs_*.py` (비교 실험, 결과 기록 후 삭제)
- `e2e_*.py` (tests 루트에, e2e/ 폴더로 이동)
- 중복된 e2e 테스트: `test_e2e_*.py``test_*_e2e.py` (하나로 통합)
---
## 7. 체크리스트
## 8. 체크리스트
### 테스트 작성 전
- [ ] 동일한 테스트 로직이 이미 존재하는가? (재사용 가능한지 확인)
- [ ] 공통 모킹/데이터가 있다면 `conftest.py`에 추가할 수 있는가?
- [ ] pytest 자동 테스트인가? (수동 스크립트면 `scripts/` 사용)
- [ ] `import pytest` 또는 `@pytest` 데코레이터 포함? (섹션 6 기준)
### 테스트 파일 추가 전
- [ ] 중복 테스트 파일이 있는가? (통합 가능한지 확인)
- [ ] 임시 실험 파일인가? (작업 완료 시 삭제 계획 수립)
- [ ] 네이밍 규칙 준수 (`test_{기능}.py`)
- [ ] `pytest tests/test_*.py` 명령으로 실행 가능한가?
### 정리 시점
- [ ] 리팩토링/비교 테스트 → troubleshooting 기록 후 삭제
- [ ] 실험 스크립트 → 작업 완료 즉시 삭제
- [ ] 중복 테스트 → 통합 또는 삭제
- [ ] pytest 없이 직접 실행하는 파일 → 삭제 또는 pytest로 변환
---
## 8. 참고
## 9. 정리 프로세스 예시
### 실제 정리 사례 (2025-01-03)
**삭제된 파일**:
1. `test_calendar_intent_overlap_cases.py` - "서비스 코드 수정 없이 관찰" 목적, 수동 실행
2. `test_calendar_query_vs_create.py` - `python3` 직접 실행, pytest 미적용
3. `test_all_day_event_simple.py` - 수동 실행 스크립트
4. `e2e/test_e2e_message_flow.py` - "pytest 없이 직접 실행" 주석, 중복 (`test_message_flow_e2e.py` 존재)
**결과**: 68개 → 64개 (pytest 자동 테스트만 유지)
---
## 10. 참고
- FastAPI 구조 원칙: `311_FastAPI_구조_원칙.md` 섹션 18 (테스트 원칙)
- 문서 작성 원칙: `312_문서_작성_원칙.md` (troubleshooting 기록 방법)