From 68459151c3f8f6406603c744b514fb54a9deeefd Mon Sep 17 00:00:00 2001 From: kyy Date: Mon, 9 Feb 2026 16:28:00 +0900 Subject: [PATCH] =?UTF-8?q?=EB=B0=B1=EC=97=94=EB=93=9C=20Hydra=20=ED=85=8C?= =?UTF-8?q?=EC=8A=A4=ED=8A=B8=20=EA=B0=80=EC=9D=B4=EB=93=9C=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/hydra_be_test_guide.md | 144 ++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 docs/hydra_be_test_guide.md diff --git a/docs/hydra_be_test_guide.md b/docs/hydra_be_test_guide.md new file mode 100644 index 00000000..963dec1e --- /dev/null +++ b/docs/hydra_be_test_guide.md @@ -0,0 +1,144 @@ +# Backend Hydra Test Guide + +이 문서는 Baron SSO 백엔드 내에서 **Ory Hydra Admin API**와 연동되는 기능(`HydraAdminService`)을 테스트하는 방법과 커버리지 측정 방법을 설명합니다. + +## 1. 테스트 개요 + +백엔드는 OAuth2 클라이언트 관리, 인증/동의(Consent) 요청 승인 등을 위해 Ory Hydra의 Admin API를 호출합니다. +본 테스트 가이드는 `httptest` 패키지와 Mocking을 활용하여 실제 Hydra 서버 없이 백엔드의 연동 로직을 빠르고 독립적으로 검증하는 방법을 다룹니다. + +## 2. 테스트 환경 준비 + +테스트는 Go 언어의 표준 테스팅 프레임워크를 사용하므로 별도의 설치가 필요 없으나, 커버리지 확인을 위해 `backend/` 디렉토리에서 작업을 수행해야 합니다. + +```bash +cd backend +``` + +## 3. 테스트 파일 목록 및 실행 방법 + +Hydra와 직접적으로 연관된 백엔드 로직 테스트는 `internal/handler`와 `internal/service` 패키지에 집중되어 있습니다. + +### 3.1. 핸들러 레벨 통합 테스트 (Handler Level) +사용자 요청(HTTP)부터 Hydra 연동까지의 전체 흐름을 검증합니다. + +* **주요 파일:** + * `backend/internal/handler/auth_handler_consent_test.go` + * `backend/internal/handler/auth_handler_link_test.go` + * `backend/internal/handler/auth_handler_login_test.go` + * `backend/internal/handler/auth_handler_qr_test.go` + * `backend/internal/handler/auth_handler_client_test.go` +* **실행 (패키지 전체):** + ```bash + cd backend + go test -v ./internal/handler/... + ``` + +### 3.2. 서비스 레벨 단위 테스트 (Service Level) +백엔드 내부에서 Ory Hydra Admin API와 직접 통신하는 서비스의 단위 기능을 검증합니다. + +* **주요 파일:** `backend/internal/service/hydra_admin_service_test.go` +* **실행:** + ```bash + cd backend + go test -v ./internal/service -run TestHydraAdminService + ``` + +### 3.3. Relying Party Service 테스트 +`HydraAdminService`와 로컬 DB(RelyingParty) 간의 통합 및 롤백 로직을 검증합니다. + +* **위치:** `backend/internal/service/relying_party_service_test.go` +* **실행:** + ```bash + go test -v ./internal/service -run TestRelyingPartyService + ``` + +### 3.4. 전체 테스트 실행 (권장) +모든 Hydra 관련 연동 테스트를 한 번에 실행하려면 다음 명령어를 사용합니다. + +```bash +go test -v ./internal/service ./internal/handler +``` + +## 4. 테스트 커버리지 측정 + +`internal/handler` 패키지에 대한 커버리지를 측정하고 90% 임계값을 확인합니다. + +```bash +# 1. 커버리지 측정 및 coverage.out 파일 생성 +cd backend +go test -coverprofile=coverage.out ./internal/handler + +# 2. 함수별 커버리지 확인 (CLI) +go tool cover -func=coverage.out + +# 3. 상세 리포트 확인 (HTML) +go tool cover -html=coverage.out +``` + +## 5. 주요 테스트 항목 (Checklist) + +| 분류 | 핸들러/메서드 | 테스트 내용 | 파일 위치 | +| :--- | :--- | :--- | :--- | +| **핸들러: 인증 흐름** | `GetConsentRequest` | Consent Challenge 검증 및 자동 승인(`skip=true`) 처리 | `auth_handler_consent_test.go` | +| | `AcceptConsentRequest` | 사용자가 동의한 Scope 기반으로 Consent 승인 | `auth_handler_consent_test.go` | +| | `PasswordLogin` | OIDC 로그인 성공 및 비활성 클라이언트 차단 검증 | `auth_handler_login_test.go` | +| | `AcceptOidcLoginRequest` | 쿠키/토큰 기반 OIDC 로그인 요청 승인 | `auth_handler_oidc_test.go` | +| | `Init/Poll/ScanQRLogin` | QR 코드 생성, 폴링, 승인으로 이어지는 전체 흐름 | `auth_handler_qr_test.go` | +| | `Init/Verify/PollEnchantedLink` | Magic Link 생성, 검증, 세션 발행으로 이어지는 전체 흐름 | `auth_handler_link_test.go`| +| | `HandleKratosCourierRelay` | Kratos의 OTP 발송 요청(Email/SMS) 수신 및 처리 | `auth_handler_otp_test.go` | +| **핸들러: 세션/RP 관리** | `ListLinkedRps` | Hydra 세션, 로컬 DB, Audit Log 3-way 병합 로직 | `auth_handler_linked_test.go` | +| | `RevokeLinkedRp` | 특정 RP(클라이언트) 연동 해제 및 세션 종료 | `auth_handler_client_test.go` | +| | `ListRpHistory` | Audit Log 기반의 RP 연동 이력 조회 | `auth_handler_client_test.go` | +| | `resolveConsentSubjects` | 토큰/쿠키에서 다중 사용자 식별자(Subject) 추출 | `auth_handler_qr_test.go` | +| **서비스: 클라이언트 관리** | `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` | + + +## 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: 결과값 검증 +} +``` +