baron-sso/docs/hydra_be_test_guide.md

Backend Hydra Test Guide

이 문서는 Baron SSO 백엔드 내에서 Ory Hydra Admin API와 연동되는 기능(HydraAdminService)을 테스트하는 방법과 커버리지 측정 방법을 설명합니다.

1. 테스트 개요

백엔드는 OAuth2 클라이언트 관리, 인증/동의(Consent) 요청 승인 등을 위해 Ory Hydra의 Admin API를 호출합니다. 본 테스트 가이드는 httptest 패키지와 Mocking을 활용하여 실제 Hydra 서버 없이 백엔드의 연동 로직을 빠르고 독립적으로 검증하는 방법을 다룹니다.

2. 테스트 환경 준비

테스트는 Go 언어의 표준 테스팅 프레임워크를 사용하므로 별도의 설치가 필요 없으나, 커버리지 확인을 위해 backend/ 디렉토리에서 작업을 수행해야 합니다.

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
• 실행 (패키지 전체):

  cd backend
  go test -v ./internal/handler/...
  

3.2. 서비스 레벨 단위 테스트 (Service Level)

백엔드 내부에서 Ory Hydra Admin API와 직접 통신하는 서비스의 단위 기능을 검증합니다.

• 주요 파일: backend/internal/service/hydra_admin_service_test.go
• 실행:

  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
• 실행:

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

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

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

go test -v ./internal/service ./internal/handler

4. 테스트 커버리지 측정

internal/handler 패키지에 대한 커버리지를 측정하고 90% 임계값을 확인합니다.

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

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

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