부제: Appium 3.0 + 이미지 매칭 + Google Sheets 실시간 리포팅

Unity SurfaceView 렌더링으로 인한 UI 요소 접근 불가 환경에서,

이미지 매칭과 해상도 독립적 터치 제어를 통해 사용자 여정을 자동 검증하고,

결과를 Google Sheets에 실시간 기록하는 엔드투엔드 QA 자동화 솔루션입니다.

🏗️ 프레임워크 아키텍처

레이어드 아키텍처(Layered Architecture) 기반으로 설계하여, 각 계층의 책임을 명확히 분리하고 유지보수성과 확장성을 확보했습니다.

📦 자동화 프레임워크
 │
 ├── 📂 testcase          # [Test Layer] 실제 테스트 시나리오 (SmokeTestSuite)
 │   └── 🔵 SmokeTestSuite.java    // TC01~07 순차 실행 및 전체 결과 관리
 │        ├─ TC01: 앱 실행 검증
 │        ├─ TC02: 메인 화면 로고 검증 (이미지 매칭)
 │        ├─ TC03: 메인 화면 진입 동작 검증 (해상도 독립 드래그)
 │        ├─ TC04: 앱 종료 검증
 │        ├─ TC05: 최초 게임 실행 동작 (6단계 통합 온보딩)
 │        ├─ TC06: 구글 계정 최초 로그인 (하이브리드 UI 제어)
 │        └─ TC07: 로그아웃 플로우 (9단계 네비게이션)
 │             // TC08(재로그인)은 구글 세션 정책상 TC06과 중복으로 SKIP
 │
 ├── 📂 main              # [Core Layer] 테스트 실행 기반
 │   └── 🔵 BaseTestCase.java      // 공통 설정 및 셋업/티어다운 관리
 │        ├─ recordResult() // Pass/Fail + 스크린샷 + Google Sheets 통합 기록
 │        └─ recordBlock()  // 전제조건 미충족 시 Block 상태 처리
 │
 ├── 📂 flow              # [Business Layer] 앱 동작 흐름 단위 모듈 ⭐ 대폭 확장
 │   ├── 🔵 StartAppFlow.java      // 앱 실행 및 연결 상태 확인 플로우
 │   ├── 🔵 FirstLaunchFlow.java   // 최초 실행 6단계 통합 플로우
 │   │    ├─ 앱 데이터 완전 초기화 (adb pm clear)
 │   │    ├─ Native 권한 팝업 처리 (하이브리드 제어)
 │   │    ├─ Unity 리소스 다운로드 시작/완료 대기 (Smart Polling)
 │   │    └─ 게임 시작 + 이용약관 동의까지 온보딩 자동화
 │   ├── 🔵 LoginFlow.java         // 구글 로그인 플로우
 │   │    ├─ runFirstLogin(): Unity 버튼 → Native 계정 선택 → Unity 완료 확인
 │   │    └─ runReLogin(): 세션 활용 자동 로그인 (현재 SKIP)
 │   └── 🔵 LogoutFlow.java        // 로그아웃 9단계 네비게이션 플로우
 │        └─ 로비 → 메뉴 → 설정 → 기타 → 로그아웃 → 이용약관 복귀
 │
 ├── 📂 marker            # [Verification Layer] 검증 및 증거 수집
 │   ├── 🔵 ImageAssert.java       // OpenCV 기반 이미지 매칭 및 좌표 추출
 │   │    ├─ waitUntilImageVisible() // 타임아웃까지 이미지 대기
 │   │    ├─ findImageCenter()       // 터치용 중앙 좌표 계산
 │   │    └─ isImageVisible()        // Polling용 빠른 존재 여부 확인
 │   └── 🔵 Evidence.java          // Pass/Fail 시점 스크린샷 자동 저장
 │
 ├── 📂 infra             # [Infrastructure Layer] 환경 설정 및 외부 연동
 │   ├── 🔵 AppiumConfig.java      // 설정값 중앙 관리 (Single Source of Truth)
 │   │    ├─ 앱 정보, 타임아웃, 이미지 리소스 경로
 │   │    └─ FirstLaunch/Login/Logout용 세부 설정 확장
 │   ├── 🔵 DriverFactory.java     // AndroidDriver 세션 생성 및 관리
 │   ├── 🔵 ScreenHelper.java      // 화면 정보 수집 및 해상도 계산
 │   └── 🔵 TouchActionHelper.java // W3C Actions 기반 터치/드래그 제어
 │        ├─ tapOnImageCenter() // 이미지 매칭 + 터치 통합 (TC05~07 핵심)
 │        └─ dragCheekAdaptive() // 해상도 독립적 드래그 (TC03)
 │
 └── 📂 reporting         # [Reporting Layer] 결과 리포팅
     ├── 🔵 ChecklistReporter.java // 동적 셀 계산 로직 및 결과 포맷팅
     └── 🔵 GoogleSheetsClient.java// Service Account 인증 및 API 통신

🛠️ 기술 스택

💡 핵심 특징

Unity 게임 특화 검증

Inspector로 식별되지 않는 SurfaceView UI 요소를 이미지 매칭으로 탐지하고, 동적 좌표 추출을 통해 정확한 터치 제어를 구현했습니다.

해상도 독립적 설계

화면 해상도를 실시간 감지하여 비율 기반으로 터치 좌표를 계산함으로써, 다양한 기기에서 스크립트 수정 없이 동작합니다.

실시간 협업 리포팅

테스트 실행 즉시 Google Sheets 체크리스트에 Pass/Fail이 자동 기록되어, 팀 전체가 실시간으로 결과를 확인할 수 있습니다.

Fail Fast 전략

선행 TC 실패 시 후속 테스트를 즉시 중단하여 불필요한 리소스 낭비를 방지하고, 근본적인 실패 원인을 빠르게 파악합니다.