forked from baron/baron-sso
누락된 go test 가이드 문서 추가
This commit is contained in:
147
docs/ hydra_backend_test_guide.md
Normal file
147
docs/ hydra_backend_test_guide.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# Backend Hydra Test Guide
|
||||
|
||||
이 문서는 Baron SSO 백엔드 내에서 **Ory Hydra Admin API**와 연동되는 기능(`HydraAdminService`)을 테스트하는 방법과 커버리지 측정 방법을 설명합니다.
|
||||
|
||||
## 1. 테스트 개요
|
||||
|
||||
백엔드는 OAuth2 클라이언트 관리, 인증/동의(Consent) 요청 승인 등을 위해 Ory Hydra의 Admin API를 호출합니다.
|
||||
본 테스트 가이드는 `httptest` 패키지와 Mocking을 활용하여 실제 Hydra 서버 없이 백엔드의 연동 로직을 빠르고 독립적으로 검증하는 방법을 다룹니다.
|
||||
(주의: 본 가이드는 관리자용 UI인 `adminfront` 테스트가 아닌, 백엔드 내부의 API 연동 코드 테스트를 다룹니다.)
|
||||
|
||||
## 2. 테스트 환경 준비
|
||||
|
||||
테스트는 Go 언어의 표준 테스팅 프레임워크를 사용하므로 별도의 설치가 필요 없으나, 커버리지 확인을 위해 `backend/` 디렉토리에서 작업을 수행해야 합니다.
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
```
|
||||
|
||||
## 3. 테스트 파일 목록 및 실행 방법
|
||||
|
||||
작성된 Hydra 관련 테스트 코드는 크게 3가지 파일로 나뉩니다.
|
||||
|
||||
### 3.1. HydraAdminService (백엔드 내부 서비스) 테스트
|
||||
백엔드 내부에서 Ory Hydra Admin API와 통신하는 최하단 로직(클라이언트 관리, OIDC 흐름, 세션 관리)을 검증합니다.
|
||||
|
||||
* **위치:** `backend/internal/service/hydra_admin_service_test.go`
|
||||
* **실행:**
|
||||
```bash
|
||||
go test -v ./internal/service -run TestHydraAdminService
|
||||
```
|
||||
|
||||
### 3.2. Relying Party Service 테스트
|
||||
`HydraAdminService`와 로컬 DB(RelyingParty) 간의 통합 및 롤백 로직을 검증합니다.
|
||||
|
||||
* **위치:** `backend/internal/service/relying_party_service_test.go`
|
||||
* **실행:**
|
||||
```bash
|
||||
go test -v ./internal/service -run TestRelyingPartyService
|
||||
```
|
||||
|
||||
### 3.3. Auth Handler 로그인 테스트
|
||||
로그인 요청 시 백엔드 핸들러 레벨에서 발생하는 OIDC/Hydra 흐름(Login Challenge 처리 등)을 검증합니다.
|
||||
|
||||
* **위치:** `backend/internal/handler/auth_handler_login_test.go`
|
||||
* **실행:**
|
||||
```bash
|
||||
go test -v ./internal/handler -run TestPasswordLogin
|
||||
```
|
||||
|
||||
### 3.4. 전체 테스트 실행 (권장)
|
||||
모든 Hydra 관련 연동 테스트를 한 번에 실행하려면 다음 명령어를 사용합니다.
|
||||
|
||||
```bash
|
||||
go test -v ./internal/service ./internal/handler -run "TestHydraAdminService|TestRelyingPartyService|TestPasswordLogin"
|
||||
```
|
||||
|
||||
## 4. 테스트 커버리지 측정
|
||||
|
||||
테스트가 코드의 어느 부분을 검증했는지 수치로 확인합니다.
|
||||
|
||||
### 4.1. 수치로 확인 (CLI)
|
||||
|
||||
```bash
|
||||
# 1. HydraAdminService (백엔드 서비스) 커버리지
|
||||
go test -v ./internal/service -run TestHydraAdminService -coverprofile=coverage_hydra.out
|
||||
go tool cover -func=coverage_hydra.out | grep hydra_admin_service.go
|
||||
|
||||
# 2. RelyingPartyService (통합 서비스) 커버리지
|
||||
go test -v ./internal/service -run TestRelyingPartyService -coverprofile=coverage_rp.out
|
||||
go tool cover -func=coverage_rp.out | grep relying_party_service.go
|
||||
```
|
||||
|
||||
**예시 출력:**
|
||||
```text
|
||||
baron-sso-backend/internal/service/hydra_admin_service.go:35: ListClients 100.0%
|
||||
baron-sso-backend/internal/service/hydra_admin_service.go:70: GetClient 85.7%
|
||||
...
|
||||
total: (statements) 78.5%
|
||||
```
|
||||
|
||||
### 4.2. 시각적으로 확인 (HTML)
|
||||
|
||||
어떤 코드가 테스트되지 않았는지(Missing Branch) 브라우저에서 색상으로 확인합니다.
|
||||
|
||||
```bash
|
||||
go tool cover -html=coverage_hydra.out
|
||||
```
|
||||
|
||||
* **초록색**: 테스트에 의해 실행된 코드
|
||||
* **빨간색**: 테스트되지 않은 코드 (추가 테스트 케이스 필요)
|
||||
* **회색**: 테스트 대상이 아닌 코드 (선언부 등)
|
||||
|
||||
## 5. 주요 테스트 항목 (Checklist)
|
||||
|
||||
| 분류 | 메서드 | 테스트 내용 | 파일 위치 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **클라이언트 관리** | `ListClients` | 클라이언트 목록 페이징 조회 | `hydra_admin_service_test.go` |
|
||||
| | `GetClient` | 특정 클라이언트 상세 조회 (성공/실패) | `hydra_admin_service_test.go` |
|
||||
| | `CreateClient` | 신규 클라이언트 생성 및 메타데이터 검증 | `hydra_admin_service_test.go` |
|
||||
| | `UpdateClient` | 클라이언트 정보 수정 (PUT) | `hydra_admin_service_test.go` |
|
||||
| | `PatchClientStatus` | 클라이언트 상태 변경 (JSON Patch) | `hydra_admin_service_test.go` |
|
||||
| | `DeleteClient` | 클라이언트 삭제 | `hydra_admin_service_test.go` |
|
||||
| **인증/동의** | `GetConsentRequest` | Consent Challenge 검증 및 요청 정보 조회 | `hydra_admin_service_test.go` |
|
||||
| | `AcceptConsentRequest` | 동의 승인 및 리다이렉트 URL 반환 | `hydra_admin_service_test.go` |
|
||||
| | `RejectConsentRequest` | 동의 거부 처리 | `hydra_admin_service_test.go` |
|
||||
| | `GetLoginRequest` | Login Challenge 검증 | `hydra_admin_service_test.go` |
|
||||
| | `AcceptLoginRequest` | 로그인 승인 및 리다이렉트 URL 반환 | `hydra_admin_service_test.go` |
|
||||
| | `RejectLoginRequest` | 로그인 거부 처리 | `hydra_admin_service_test.go` |
|
||||
| **세션 관리** | `ListConsentSessions` | 특정 사용자의 활성 세션 목록 조회 | `hydra_admin_service_test.go` |
|
||||
| | `RevokeConsentSessions` | 특정 사용자/클라이언트의 세션 만료 처리 | `hydra_admin_service_test.go` |
|
||||
| **서비스 통합** | `Create` (RP) | Hydra 생성 -> DB 생성 -> Keto 권한 부여 | `relying_party_service_test.go` |
|
||||
| | `Create` (Rollback) | DB 실패 시 Hydra 롤백(삭제) 검증 | `relying_party_service_test.go` |
|
||||
| **핸들러 연동** | `PasswordLogin` | OIDC 로그인 성공 및 Challenge 승인 | `auth_handler_login_test.go` |
|
||||
| | `PasswordLogin` | 비활성(Inactive) 클라이언트 로그인 차단 | `auth_handler_login_test.go` |
|
||||
|
||||
## 6. 테스트 코드 작성 가이드
|
||||
|
||||
새로운 기능을 추가하거나 커버리지를 높일 때 다음 패턴을 참고하세요.
|
||||
|
||||
```go
|
||||
func TestHydraAdminService_NewFeature(t *testing.T) {
|
||||
// 1. Mock 핸들러 정의 (예상되는 요청 검증 및 가짜 응답 반환)
|
||||
handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
// Assert: 요청 메서드, URL, 바디 검증
|
||||
if r.Method != http.MethodPost {
|
||||
t.Errorf("expected POST, got %s", r.Method)
|
||||
}
|
||||
|
||||
// Response: 가짜 응답 작성
|
||||
w.WriteHeader(http.StatusOK)
|
||||
json.NewEncoder(w).Encode(expectedResponse)
|
||||
})
|
||||
|
||||
// 2. 서비스 초기화 (Mock Client 주입)
|
||||
svc := &HydraAdminService{
|
||||
AdminURL: "http://hydra:4445",
|
||||
HTTPClient: mockHydraClient(handler), // ory_service_test.go의 헬퍼 사용
|
||||
}
|
||||
|
||||
// 3. 테스트 실행 및 검증
|
||||
result, err := svc.NewFeature(context.Background(), args)
|
||||
if err != nil {
|
||||
t.Fatalf("failed: %v", err)
|
||||
}
|
||||
// Assert: 결과값 검증
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user