# 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 앱 코드를 변경한 모든 작업은 아래 검증을 통과해야 한다.

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

필요 시 formatter를 적용한다.

```bash
./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 기준 통과를 구분해서 기록한다.