---

name: server-test-guard description: | 백엔드 코드(Controller, Service, DTO, Entity, Repository) 및 통합 테스트 코드(tests/integration) 변경 시 반드시 사용. 테스트 코드 점검, 수정, 검증까지 완료해야 작업이 끝난 것으로 간주. app/backend/ 또는 tests/integration/ 하위 파일 수정 후 이 skill을 자동 적용.

백엔드/테스트 변경 시 검증 워크플로우

백엔드 코드 또는 통합 테스트 코드가 변경되었습니다. 다음 단계를 반드시 수행해야 합니다.

1. 변경 영향 분석

• 변경된 파일 목록 확인
• 변경 유형 파악:
  • DTO 필드 추가/삭제/변경
  • API 응답 구조 변경
  • 비즈니스 로직 변경
  • Entity 구조 변경
  • 테스트 시나리오 또는 검증 로직 변경

2. 관련 테스트 파일 식별

테스트 레벨

테스트 파일 매핑

Integration 테스트 매핑 (tests/integration/)

3. 테스트 코드 점검

핵심 원칙:

• Unit/Component: 비즈니스 로직, 엣지 케이스, 예외 처리 검증
• Integration: 도메인은 Happy Path, infra/는 Cross-Cutting Concerns (보안, 인증 전파)
• 엄격성 준수: pytest.skip 사용 금지, 느슨한 상태 코드 검증 금지

각 테스트 파일에서 확인:

• DTO 필드 변경 → 테스트의 assertion이 새 구조에 맞는지
• API 응답 변경 → jsonPath() 또는 response 검증이 올바른지
• 새 필드 추가 → 테스트에서 해당 필드를 검증하는지
• 필드 제거 → 제거된 필드를 참조하는 코드가 없는지

4. 테스트 수정 (필요시)

변경된 구조에 맞게 테스트 코드 업데이트.

엄격한 검증 규칙 (필수 준수)

1. 단일 상태 코드 검증

Copy# ❌ 금지 - 느슨한 검증
assert response.status_code in (200, 400, 409)

# ✅ 필수 - 정확한 상태 코드
assert response.status_code == 201
assert response.status_code == 409, "중복 리소스는 409 Conflict"

2. RESTful 상태 코드 규칙

3. Test Skip 금지

Copy# ❌ 금지 - 데이터 없음으로 인한 Skip
if not items:
    pytest.skip("데이터 없음")

# ✅ 필수 - 데이터 부재는 곧 테스트 실패
assert items, "테스트를 위한 필수 데이터가 없습니다"

4. DTO 필드 완전 검증

Copy# 필수 필드 존재 확인
assert "id" in data
assert "name" in data
assert "createdAt" in data

# 타입 검증
assert isinstance(data["id"], int)
assert isinstance(data["items"], list)

# 값 검증
assert data["name"] == expected_name

5. 에러 응답도 검증

Copy# 에러 구조 확인 (프론트엔드가 메시지를 표시할 수 있도록)
error = response.json()
assert "message" in error or "error" in error

5. 테스트 실행 및 검증

Unit/Component 테스트 (필수)

Copycd app/backend
./gradlew test

Integration 테스트 (주요 API 변경 시)

Copy# 1. 개발 컨테이너가 떠있다면 중지
docker compose down

# 2. 테스트용 컨테이너 실행 (tmpfs로 매번 깨끗한 DB)
docker compose -f docker-compose.test.yml up -d --build

# 3. 서비스 준비 대기 (약 30초)
sleep 30

# 4. Integration 테스트 실행
cd tests/integration
uv sync
uv run pytest -v

# 5. 테스트 완료 후 정리
docker compose -f docker-compose.test.yml down

Integration 테스트 실행 조건:

• API 엔드포인트 추가/삭제/변경
• 요청/응답 구조 변경
• 인증 흐름 변경

실패 시 대응

1. 실패 원인 분석
2. 테스트 코드 또는 프로덕션 코드 수정
3. 재실행하여 통과 확인

완료 조건

• 모든 관련 Unit/Component 테스트 파일 점검 완료
• 필요한 테스트 수정 완료
• ./gradlew test 전체 통과
• (주요 변경 시) Integration 테스트 통과
• 이 조건 충족 전까지 백엔드 작업 미완료로 간주