baron-sso/docs/hydra_backend_test_guide.md

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/ 디렉토리에서 작업을 수행해야 합니다.

cd backend

3. 테스트 파일 목록 및 실행 방법

작성된 Hydra 관련 테스트 코드는 크게 3가지 파일로 나뉩니다.

3.1. HydraAdminService (백엔드 내부 서비스) 테스트

백엔드 내부에서 Ory Hydra Admin API와 통신하는 최하단 로직(클라이언트 관리, OIDC 흐름, 세션 관리)을 검증합니다.

• 위치: backend/internal/service/hydra_admin_service_test.go
• 실행:

  go test -v ./internal/service -run TestHydraAdminService
  

3.2. Relying Party Service 테스트

HydraAdminService와 로컬 DB(RelyingParty) 간의 통합 및 롤백 로직을 검증합니다.

• 위치: backend/internal/service/relying_party_service_test.go
• 실행:

  go test -v ./internal/service -run TestRelyingPartyService
  

3.3. Auth Handler 로그인 테스트

로그인 요청 시 백엔드 핸들러 레벨에서 발생하는 OIDC/Hydra 흐름(Login Challenge 처리 등)을 검증합니다.

• 위치: backend/internal/handler/auth_handler_login_test.go
• 실행:

  go test -v ./internal/handler -run TestPasswordLogin
  

3.4. 전체 테스트 실행 (권장)

모든 Hydra 관련 연동 테스트를 한 번에 실행하려면 다음 명령어를 사용합니다.

go test -v ./internal/service ./internal/handler -run "TestHydraAdminService|TestRelyingPartyService|TestPasswordLogin"

4. 테스트 커버리지 측정

테스트가 코드의 어느 부분을 검증했는지 수치로 확인합니다.

4.1. 수치로 확인 (CLI)

# 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

예시 출력:

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) 브라우저에서 색상으로 확인합니다.

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. 테스트 코드 작성 가이드

새로운 기능을 추가하거나 커버리지를 높일 때 다음 패턴을 참고하세요.

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: 결과값 검증
}