app-test-workflow

# 앱 테스트 워크플로우 (App Test Workflow)

Flutter 앱의 특정 기능을 에뮬레이터에서 직접 테스트하고, 실패 시 자동으로 수정하는 워크플로우입니다.

## 활성화 방법

다음 명령어로 워크플로우를 시작합니다:

- `앱 테스트 워크플로우` 또는 `앱 테스트 워크플로우로 진행해줘`
- `/app-test-workflow`
- `앱 테스트로 [테스트할 기능]`

### 예시

```
사용자: 앱 테스트 워크플로우로 로그인 기능을 테스트해줘
사용자: /app-test-workflow 거래 추가 기능 테스트
사용자: 앱 테스트로 카테고리 관리 확인해줘
```

---

## 워크플로우 개요

```
[요청 접수]
    |
    v
[Phase 1: 테스트 계획 수립] ────────────────────────
    |  - 테스트할 기능 분석
    |  - 테스트 시나리오 정의
    |  - Todo 리스트 작성
    |  - 사용자 확인
    v
[Phase 2: 환경 준비] ────────────────────────────────
    |  - 에뮬레이터 상태 확인
    |  - 테스트 데이터 준비 (Supabase)
    |  - 앱 빌드 및 실행
    v
[Phase 3: 테스트 실행 Loop] ─────────────────────────
    |  - app-test-agent 호출
    |  - Todo 항목별 테스트 수행
    |  +──[테스트 실패]──> [app-debug-agent 호출]
    |  |                      - 버그 분석
    |  |                      - 코드 수정
    |  |                      - 수정 검증
    |  +<────────────────── [재테스트]
    |
    v (모든 Todo 완료)
[Phase 4: 완료 보고] ────────────────────────────────
    - 테스트 결과 요약
    - 수정된 코드 목록
    - 보고서 생성
```

---

## Phase 1: 테스트 계획 수립

### 1.1 기능 분석

테스트할 기능의 코드와 구조를 파악합니다.

```
Task(
  subagent_type: "Explore",
  prompt: "[기능명] 관련 코드를 분석하고 테스트 포인트를 파악해주세요.
  - 관련 파일 목록
  - 주요 로직 흐름
  - 의존성 (API, DB 등)"
)
```

### 1.2 테스트 시나리오 정의

기능별 테스트 시나리오를 정의합니다.

```markdown
## 테스트 시나리오: [기능명]

### 정상 케이스
1. [시나리오 1 설명]
   - 입력: [테스트 입력]
   - 예상 결과: [예상 출력]

2. [시나리오 2 설명]
   - 입력: [테스트 입력]
   - 예상 결과: [예상 출력]

### 에러 케이스
1. [에러 시나리오 설명]
   - 입력: [잘못된 입력]
   - 예상 결과: [에러 메시지/처리]
```

### 1.3 Todo 리스트 작성

테스트 항목을 Todo로 등록합니다.

```
TodoWrite([
  { content: "[기능명] 테스트 환경 준비", status: "pending", activeForm: "테스트 환경 준비 중" },
  { content: "[시나리오 1] 정상 케이스 테스트", status: "pending", activeForm: "정상 케이스 테스트 중" },
  { content: "[시나리오 2] 에러 케이스 테스트", status: "pending", activeForm: "에러 케이스 테스트 중" },
  ...
])
```

### 1.4 사용자 확인

```
테스트 계획이 수립되었습니다:

테스트 대상: [기능명]
테스트 항목: [N]개
- [ ] 시나리오 1
- [ ] 시나리오 2
...

진행하시겠습니까? (Y/n)
```

---

## Phase 2: 환경 준비

### 2.1 디바이스 확인 (Mobile MCP)

```
// Mobile MCP로 연결된 디바이스 확인 (권장)
mcp__mobile-mcp__mobile_list_devices

// Flutter CLI로도 확인 가능
flutter devices
flutter emulators
```

### 2.2 에뮬레이터 실행 (필요시)

```bash
# Android 에뮬레이터 실행
flutter emulators --launch <emulator_id>

# iOS 시뮬레이터 실행
flutter emulators --launch apple_ios_simulator

# 에뮬레이터 실행 후 약 10-20초 대기
```

### 2.3 Mobile MCP 도구 목록

| 도구 | 설명 |
|------|------|
| `mobile_list_devices` | 연결된 디바이스/에뮬레이터 목록 |
| `mobile_list_apps` | 설치된 앱 목록 |
| `mobile_launch_app` | 앱 실행 (패키지명) |
| `mobile_terminate_app` | 앱 종료 |
| `mobile_screenshot` | 스크린샷 캡처 |
| `mobile_tap` | 화면 탭 (x, y 좌표) |
| `mobile_type_text` | 텍스트 입력 |
| `mobile_swipe` | 스와이프/스크롤 |
| `mobile_list_elements` | UI 요소 목록 (Accessibility Tree) |
| `mobile_get_element` | 특정 UI 요소 정보 |
| `mobile_press_button` | 하드웨어 버튼 (back, home) |
| `mobile_get_screen_size` | 화면 크기 |

### 2.4 테스트 데이터 준비

Supabase MCP를 사용하여 테스트 데이터를 준비합니다.

```sql
-- 테스트 사용자 생성 (필요시)
INSERT INTO profiles (id, display_name, email)
VALUES ('test-user-id', 'Test User', 'test@example.com');

-- 테스트용 가계부 생성
INSERT INTO ledgers (id, name, owner_id)
VALUES ('test-ledger-id', 'Test Ledger', 'test-user-id');
```

### 2.5 앱 빌드 및 실행

```bash
# 의존성 설치
flutter pub get

# 앱 빌드 및 실행
flutter run -d <device_id>
```

또는 Mobile MCP로 이미 설치된 앱 실행:

```
// 설치된 앱 목록 확인
mcp__mobile-mcp__mobile_list_apps

// 앱 실행
mcp__mobile-mcp__mobile_launch_app(packageName: "com.example.household_account")
```

---

## Phase 3: 테스트 실행 Loop

### 3.1 테스트 실행

각 Todo 항목에 대해 app-test-agent를 호출합니다.

```
Task(
  subagent_type: "app-test-agent",
  prompt: """
  [테스트 지시서]
  - 테스트 ID: [Todo 번호]
  - 테스트 시나리오: [시나리오 설명]
  - 입력 데이터: [테스트 입력]
  - 예상 결과: [예상 출력]
  - 디바이스: [device_id]
  - 패키지명: com.example.household_account

  Mobile MCP를 사용하여 에뮬레이터에서 직접 테스트를 수행하세요:
  1. mobile_screenshot으로 현재 화면 확인
  2. mobile_list_elements로 UI 요소 파악
  3. mobile_tap, mobile_type_text로 상호작용
  4. 결과 스크린샷 캡처 후 검증
  """
)
```

### 3.1.1 Mobile MCP 테스트 예시

```
// 1. 화면 스크린샷 캡처
mcp__mobile-mcp__mobile_screenshot

// 2. UI 요소 목록 확인 (Accessibility Tree)
mcp__mobile-mcp__mobile_list_elements

// 3. 버튼 탭 (좌표 또는 요소 기반)
mcp__mobile-mcp__mobile_tap(x: 200, y: 400)

// 4. 텍스트 입력
mcp__mobile-mcp__mobile_type_text(text: "test@email.com")

// 5. 스크롤/스와이프
mcp__mobile-mcp__mobile_swipe(startX: 200, startY: 600, endX: 200, endY: 200)

// 6. 뒤로가기 버튼
mcp__mobile-mcp__mobile_press_button(button: "back")

// 7. 결과 확인용 스크린샷
mcp__mobile-mcp__mobile_screenshot
```

### 3.2 테스트 결과 처리

#### 성공 시

```
TodoWrite([
  { content: "[시나리오 1] 정상 케이스 테스트", status: "completed", activeForm: "정상 케이스 테스트 중" },
  ...
])
```

#### 실패 시 -> app-debug-agent 호출

```
Task(
  subagent_type: "app-debug-agent",
  prompt: """
  [디버그 지시서]
  - 실패한 테스트: [테스트 ID]
  - 에러 정보:
    ```
    [테스트 결과 JSON]
    ```
  - 예상 동작: [예상 결과]
  - 실제 동작: [실제 결과]

  원인을 분석하고 코드를 수정해주세요.
  """
)
```

### 3.3 수정 후 재테스트

app-debug-agent 수정 완료 후:

1. 앱 재빌드 (Hot Reload 또는 재시작)
2. 동일 테스트 시나리오 재실행
3. 성공 시 다음 Todo로 진행
4. 실패 시 다시 app-debug-agent 호출 (최대 3회)

### 3.4 반복 제한

- 동일 테스트 최대 3회 재시도
- 초과 시 사용자에게 확인 요청

```
테스트 [시나리오명]이 3회 실패했습니다.

실패 원인:
- 1차: [원인]
- 2차: [원인]
- 3차: [원인]

계속 진행하시겠습니까?
1. 건너뛰고 다음 테스트 진행
2. 수동으로 문제 해결 후 재시도
3. 워크플로우 중단
```

---

## Phase 4: 완료 보고

### 4.1 테스트 결과 요약

```markdown
# 앱 테스트 완료 보고서

## 테스트 개요
- 테스트 대상: [기능명]
- 테스트 일시: YYYY-MM-DD HH:MM
- 테스트 디바이스: [디바이스명]

## 테스트 결과

| 시나리오 | 결과 | 재시도 | 비고 |
|----------|------|--------|------|
| 시나리오 1 | PASS | 0 | - |
| 시나리오 2 | PASS | 2 | 버그 수정 후 통과 |
| 시나리오 3 | SKIP | 3 | 수동 확인 필요 |

## 수정된 코드

| 파일 | 수정 내용 |
|------|----------|
| lib/features/auth/data/repositories/auth_repository.dart | null 처리 추가 |
| lib/features/auth/presentation/pages/login_page.dart | 에러 메시지 개선 |

## 남은 이슈
- [ ] 시나리오 3 수동 확인 필요
```

### 4.2 보고서 저장

```
.app-test-reports/
├── test-report-YYYY-MM-DD-[기능명].md
└── ...
```

---

## Agent 역할 분담

### app-test-agent

| 역할 | 설명 |
|------|------|
| 에뮬레이터 관리 | 에뮬레이터 실행, 앱 실행 |
| 테스트 수행 | 시나리오별 테스트 실행 |
| 데이터 입력 | Supabase를 통한 테스트 데이터 관리 |
| 결과 수집 | 테스트 결과 JSON 형식 반환 |

### app-debug-agent

| 역할 | 설명 |
|------|------|
| 에러 분석 | 테스트 실패 원인 분석 |
| 코드 수정 | 버그 픽스, 로직 수정 |
| 검증 | 수정 후 flutter analyze 실행 |
| 보고 | 수정 내역 JSON 형식 반환 |

---

## 테스트 데이터 관리

### Supabase 테스트 계정

테스트용 계정 정보는 `.env` 파일에서 관리합니다.

```env
TEST_USER_EMAIL=test@example.com
TEST_USER_PASSWORD=TestPassword123!
```

### 테스트 데이터 정리

테스트 완료 후 테스트 데이터를 정리합니다.

```sql
-- 테스트 데이터 정리
DELETE FROM transactions WHERE ledger_id = 'test-ledger-id';
DELETE FROM categories WHERE ledger_id = 'test-ledger-id';
DELETE FROM ledgers WHERE id = 'test-ledger-id';
```

---

## 자동 승인 설정

워크플로우가 끊김 없이 실행되려면 다음 도구들을 자동 승인해야 합니다.

### settings.local.json 추가 필요

```json
{
  "permissions": {
    "allow": [
      "Bash(flutter devices:*)",
      "Bash(flutter emulators:*)",
      "Bash(flutter emulators --launch:*)",
      "Bash(flutter pub get:*)",
      "Bash(flutter run:*)",
      "Bash(flutter test:*)",
      "Bash(flutter analyze:*)",
      "mcp__supabase__execute_sql",
      "mcp__supabase__list_tables"
    ]
  }
}
```

---

## 주의사항

1. **에뮬레이터 필수**: 실제 디바이스 또는 에뮬레이터가 실행 중이어야 함
2. **Supabase 연결**: `.env` 파일에 Supabase 설정 필요
3. **테스트 격리**: 테스트 데이터는 운영 데이터와 분리
4. **재시도 제한**: 동일 테스트 최대 3회 재시도
5. **수동 개입**: 복잡한 버그는 사용자에게 알림

---

## 트러블슈팅

### 에뮬레이터가 없는 경우

```bash
# Android 에뮬레이터 생성
flutter emulators --create --name test_device

# iOS는 Xcode에서 시뮬레이터 추가 필요
```

### 앱 빌드 실패

```bash
# 캐시 정리
flutter clean
flutter pub get

# 재빌드
flutter run -d <device_id>
```

### Supabase 연결 실패

1. `.env` 파일 확인
2. Supabase 대시보드에서 서비스 상태 확인
3. 네트워크 연결 확인