Feat: [main] hufs-notice-crawler CI/CD까지 구현 완료

README.test.md

@@ -0,0 +1,137 @@
+# 테스트 문서
+
+이 문서는 `HUFS 컴퓨터공학부 공지 크롤러`의 테스트 방법과 검증 범위를 설명합니다.
+
+관련 문서:
+
+- 서비스 개요: [`README.md`](/C:/Users/USER/Desktop/notice_crawler/README.md)
+- 운영/배포: [`README.operation.md`](/C:/Users/USER/Desktop/notice_crawler/README.operation.md)
+- n8n 연동: [`README.n8n.md`](/C:/Users/USER/Desktop/notice_crawler/README.n8n.md)
+
+## 자동 테스트 실행
+
+가상환경 예시:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python -m pytest
+```
+
+## 현재 자동 테스트 범위
+
+- `GET /health` 응답 확인
+- `POST /api/v1/crawl` 응답 구조 확인
+- 신규 글만 DB에 저장되는지 확인
+- 신규 글이 0개일 때 응답이 올바른지 확인
+- 최초 bootstrap 실행 시 저장만 하고 반환하지 않는지 확인
+
+## 테스트 파일
+
+- [`tests/test_api.py`](/C:/Users/USER/Desktop/notice_crawler/tests/test_api.py)
+  - FastAPI 응답 구조 검증
+- [`tests/test_service.py`](/C:/Users/USER/Desktop/notice_crawler/tests/test_service.py)
+  - 신규 감지, bootstrap, latest_posts_by_board 동작 검증
+- [`tests/conftest.py`](/C:/Users/USER/Desktop/notice_crawler/tests/conftest.py)
+  - SQLite 인메모리 DB fixture
+
+## 최신 자동 테스트 결과
+
+기준 실행:
+
+```bash
+python -m pytest
+```
+
+결과:
+
+```text
+5 passed
+```
+
+의미:
+
+- API 테스트 통과
+- 서비스 로직 테스트 통과
+- bootstrap 관련 테스트 통과
+
+## 실제 사이트 수동 검증 결과
+
+`PostgreSQL` 연결 없이 실제 `HUFS 컴퓨터공학부` 사이트에 요청을 보내 크롤링 동작 여부를 확인했습니다.
+
+검증 일시:
+
+- `2026-03-17`
+
+검증 범위:
+
+- 공지사항 목록 페이지 접근
+- 자료실 목록 페이지 접근
+- 취업정보 목록 페이지 접근
+- 목록에서 `article_id`와 링크 추출
+- 상세 페이지에서 제목, 작성자, 게시일, 본문, 첨부파일 추출
+- 사용자용 `subview.do?enc=...` 링크 생성 확인
+
+확인 결과:
+
+- 공지사항 `1926` 접근 성공
+- 자료실 `1927` 접근 성공
+- 취업정보 `1929` 접근 성공
+- 크롤러가 목록 파싱 성공
+- 상세 페이지 파싱 성공
+- 자료실 샘플 게시글에서 첨부파일 링크 추출 성공
+- 반환 링크가 `subview.do?enc=...` 형식으로 생성되는 것 확인
+
+실제 확인 예시:
+
+- 공지사항
+  - 수집 수: 20개
+  - 샘플 글: `249714`
+- 자료실
+  - 수집 수: 8개
+  - 샘플 글: `239712`
+  - 첨부파일 1개 추출 확인
+- 취업정보
+  - 수집 수: 10개
+  - 샘플 글: `247506`
+
+## 문법 검증
+
+```bash
+python -m compileall app tests
+```
+
+## 경고 해석
+
+테스트 결과에 `warnings summary`가 나올 수 있습니다.
+
+- `passed`
+  - 테스트 자체는 성공
+- `warning`
+  - 추후 라이브러리 버전 업이나 파이썬 버전 변화 시 수정이 필요할 수 있는 항목
+
+현재 기준으로 보이는 경고는 대체로 다음입니다.
+
+- `fastapi.routing` 내부 `DeprecationWarning`
+  - 현재 사용 중인 FastAPI/하위 의존성과 Python 3.14 조합에서 발생 가능
+- `pytest cache` 관련 경고
+  - 캐시 디렉토리 상태 문제
+  - 테스트 실패와는 별개
+
+## 수동 확인 권장 항목
+
+운영 전에는 아래를 직접 확인하는 것이 좋습니다.
+
+1. `GET /health` 호출 시 `{"status":"ok"}` 반환
+2. `POST /api/v1/crawl` 호출 시 JSON 응답 정상
+3. 첫 실행 시 bootstrap 동작 확인
+4. 두 번째 실행부터 신규 글만 반환되는지 확인
+5. `n8n`에서 HTTP Request 노드 연동 확인
+6. PostgreSQL 연결 정보가 맞을 때 컨테이너가 정상 기동하는지 확인
+
+## 아직 직접 하지 못한 검증
+
+- 실제 PostgreSQL 연동 end-to-end 테스트
+- 실제 Docker 컨테이너 빌드/기동 테스트
+- 실제 n8n 워크플로우 전송 테스트