tdc114plus/docs/00_policy_tdc114plus_testing_2026-07-02.md

tdc114plus 테스트 정책

작성일: 2026-07-02 최종 개정일: 2026-07-09 상태: v2.1

목적: tdc114plus Flutter 앱의 mock 기반 개발, Swagger 계약 검증, 실제 API 연동 검증 기준을 단계별로 정의한다.

상위 기준 문서:

• docs/00_policy_tdc114plus_decoupled_api_migration_2026-07-07.md
• docs/00_policy_tdc114plus_development_2026-07-02.md
• docs/00_contract_tdc114plus_api_2026-07-02.md

1. 적용 범위

본 정책은 아래 영역에 적용한다.

• Flutter 앱 화면, 라우팅, 상태관리
• API client, repository, provider
• API 계약 기반 model, DTO, JSON 변환
• Baron SSO Hosted Login + PKCE 시작/callback/token 교환 흐름
• 직원검색, 조직도, 직원 상세
• 즐겨찾기 로컬 저장
• 전화걸기, 문자보내기 등 플랫폼 액션

2. 기본 검증 게이트

Flutter 앱 코드를 변경한 모든 작업은 아래 검증을 통과해야 한다.

./scripts/flutter-docker.sh analyze
./scripts/flutter-docker.sh test

필요 시 formatter를 적용한다.

./scripts/format-dart.sh

검증 실패 상태의 코드는 main 브랜치에 반영하지 않는다.

3. 테스트 레이어

3.1 Mock 레이어

목적:

• 백엔드 미구현 상태에서도 화면과 상태 흐름을 개발 가능하게 유지한다.

대상:

• widget test
• fake/mock repository
• local mock data

핵심 검증:

• 로그인 화면 표시
• Baron SSO 로그인 시작 버튼 렌더링
• 앱 내부에서 휴대폰번호를 직접 입력받지 않는지 확인
• callback token 교환 완료 후 첫 화면 진입
• 직원검색, 조직 탐색, 즐겨찾기, 상세 화면 흐름

3.2 계약 레이어

목적:

• Swagger 기준 request/response DTO와 앱 모델 간 불일치를 조기에 찾는다.

대상:

• fromJson, toJson
• API error parsing
• request body 생성
• polling 상태값 파싱

핵심 검증:

• OIDC authorization URL query 생성
• PKCE state, nonce, code_verifier 저장/검증
• token endpoint 응답 DTO
• 세션 저장 모델
• directory/organization DTO
• 400/401/403/429/timeout 처리

3.3 실제 API 레이어

목적:

• mock 구조가 실제 API와 동일한 사용자 흐름을 유지하는지 확인한다.

대상:

• smoke test
• integration test
• staging 또는 동등 환경 점검

핵심 검증:

• Hosted Login authorization endpoint 진입
• App Link callback 수신
• PKCE token 교환 후 세션 저장
• 로그인 후 직원검색 첫 화면 진입
• directory/organization 실제 응답 정합성

4. 우선 테스트 대상

강한 단위 테스트가 필요한 영역:

• API model fromJson, toJson
• API error parsing
• authorization URL 생성 규칙
• 로그인 상태 전이
• state, nonce, code_verifier 처리
• 세션 저장/삭제/복원
• 직원검색 query/filter 생성
• 가족사/조직 필터 상태
• 즐겨찾기 추가/삭제/조회
• API 실패, 401, 403, 429, timeout 처리

화면 테스트가 필요한 영역:

• 앱 실행 후 로그인 화면 표시
• 앱 내부 전화번호 입력창 미노출
• callback 처리 완료 후 직원검색 진입
• 직원 검색어 입력과 결과 표시
• 가족사 필터 선택/해제
• 조직도 탐색
• 직원 상세 표시
• 전화걸기/문자보내기 액션 노출
• 즐겨찾기 토글

5. 단계별 테스트 전략

5.1 Phase A: Mock 우선 개발

목표:

• API 없이도 앱의 핵심 화면 흐름을 검증한다.

완료 기준:

• flutter analyze 통과
• flutter test 통과
• mock repository 기반 주요 widget test 존재

5.2 Phase B: 계약 정합성 검증

목표:

• Swagger 기준 DTO와 앱 모델의 구조를 맞춘다.

완료 기준:

• DTO 파싱/직렬화 테스트 통과
• 에러 응답 테스트 통과
• 로그인 흐름 상태값 테스트 통과

5.3 Phase C: 실제 API 연동

목표:

• Hosted Login + PKCE 흐름이 실제 Baron SSO RP 설정과 맞물리는지 확인한다.

실행 원칙:

• 실제 API smoke는 환경 준비 확인 후 실행한다.
• local, staging, 기타 검증 환경 중 어떤 환경을 쓰더라도 동일한 계약 기준을 적용한다.
• 실제 검증은 authorization URL 열기 -> Baron SSO Hosted Login에서 인증 -> App Link callback -> state 검증 -> token 교환 -> 세션 저장 -> 첫 화면 진입 흐름 완료를 기준으로 본다.
• phone-login, link/poll은 개발용 fallback 또는 Baron SSO 내부 구현 참고일 뿐, 신규 앱 기본 로그인 검증 완료로 간주하지 않는다.

완료 기준:

• authorization URL query 확인
• callback 수신과 state 검증 확인
• token 교환 후 세션 저장 확인
• 로그인 후 첫 화면 진입 확인
• directory/organization 응답 필드 정합성 확인

6. 수동 검증 원칙

• Android target 검증은 mock 검증과 별도로 본다.
• 로그인 완료 가정 세션 주입 경로는 post-login 기능 점검용으로만 사용한다.
• 실제 승인 완료 검증을 세션 bootstrap 경로로 대체하지 않는다.
• staging 반영 검토 전에는 승인 완료 end-to-end를 최소 1회 이상 확인하는 것을 목표로 한다.

7. 문서 및 로그 반영 원칙

• 테스트 기준이 바뀌면 정책 문서를 먼저 갱신한다.
• 중요한 실행 결과는 docs/test-logs/에 기록한다.
• 실패 시에는 원인, 재현 조건, 후속 조치를 함께 남긴다.
• mock 기준 통과와 real API 기준 통과를 구분해서 기록한다.