시뮬레이터 컨트롤을 활용한 iOS UI 시각적 회귀 테스트 구현

시뮬레이터 스크립트로 자동화하는 iOS 화면 검증

iOS 인터페이스의 일관성을 유지하기 위한 시각적 회귀 테스트는 애플리케이션 실행 인수 제어에서 시작할 수 있습니다. 지정된 페이지로의 진입을 파라미터로 설정하고, simctl 명령어를 활용해 대량의 화면을 캡처한 후, 기존 베이스라인과 현재 상태를 픽셀 단위로 비교하는 방식이 유효합니다. 특히 다국어 지원 환경이나 다크 모드 전환 시 발생하는 레이아웃 이탈을 점검하는 데 적합하지만, 신뢰할 수 있는 결과를 위해서는 촬영 환경의 통제와 결과물의 사후 검토가 필수적입니다.

최근 구독 결제 화면 (Paywall) 최적화 사례에서 버튼 배치 변경과 배지 텍스트 강조 등을 시도했습니다. 그러나 보고서 분석 결과, 예상치 못한 하단 요소들의 이동이 발생했습니다. 라벨에 적용된 패딩 증가가 줄 높이를 변화시키고, 이에 따라 아래의 구독 목록과 푸터 영역까지 연쇄적으로 변형되었기 때문입니다.

흥미로운 점은 코드 수정량이 화면 차이 면적과 항상 비례하지는 않는다는 사실입니다. 텍스트만 변경했을 때에도 레이아웃 차이는 줄어들었으나, 일부 구조 변경은 큰 영향을 주었습니다.

본 가이드에서는 이러한 문제를 해결하기 위한 로컬 기반 시각적 회귀 엔진을 설계하는 과정을 설명합니다. 목표 페이지 도달 방법, 차이점 산출 로직, 결과 신뢰도 판단 기준, 그리고 CI 연동 전 고려사항을 다룹니다.

1. 검사 대상 정의 및 매트릭스 설정

특정 언어 (예: 영어) 와 라이트 모드에서 정상인 UI 가 반드시 다른 언어 (예: 일본어) 와 다크 모드에서도 완벽하지 않을 수 있습니다. 텍스트 길이, 줄 바꿈, 색상 대비, 시스템 컴포넌트 렌더링 등이 최종 화면 구성에 영향을 미칩니다.

프로젝트의 검사 매트릭스를 설계할 때, 단순히 '페이지'가 아닌 '페이지와 상태 조합'을 단위로 삼아야 합니다. 예를 들어 4 개 언어, 2 가지 테마, 5 개의 주요 페이지라면 총 40 가지 상태가 커버리지의 기준이 됩니다.

이 엔진의 핵심 목적은 정의된 환경과 입력 조건에서, 현재 화면의 정적 모습이 이전 검수된 모습과 얼마나 다른지를 확인하는 것입니다. 구매 성공 여부나 버튼 클릭 이벤트 등의 동작 테스트는 포함되지 않으며, 가격 안내 문구의 정확성 역시 시각적 데이터만으로 판단하기 어렵습니다.

테스트 접근법은 관찰하고자 하는 계층에 따라 달라집니다:

접근 방법 주요 관찰 대상 적용 시 고려 사항
XCUITest 및 스크린샷 사용자 상호작용 경로, 앱 구동 흐름, 네비게이션 이동 상태 준비 및 테스트 케이스 유지보수 필요, 특정 페이지 직행 파라미터 활용 가능
Swift Snapshot Testing 라이브러리 UIView, ViewController 의 렌더링 결과 및 기타 값 테스트 종속성 추가 필요, 렌더링 설정 및 어설션 설계 요구
디버그 진입구와 simctl 결합 애플리케이션 내 특정 페이지의 전체 화면 정적 상태 앱 내부에 페이지 생성 엔트리 포인트 추가 필요, 상태 격리 및 검증 로직 직접 관리

스냅샷 라이브러리는 고립된 뷰만을 렌더링하는 도구로 오해받기 쉽지만, 실제로는 장치 구성 및 트레잇 컬렉션까지 지원하는 경우가 많습니다. 본 사례에서는 세 번째 방법을 선택하여, 애플리케이션 진입을 명확히 하고 외부 스크립트를 통한 캡처 및 검증 프로세스를 통합했습니다.

2. 아키텍처 분할: 진입 제어, 캡처, 리포트

검증 시스템은 다음과 같이 세 영역으로 분리됩니다.

  • 앱 내부 진입 모듈: 실행 인자를 해석하고 언어/테마를 초기화하며, 목표 뷰 컨트롤러를 생성해 메인 윈도우에 할당합니다.
  • 캡처 실행 스크립트: Mac 에서 작동하며, 해당UDID 를 가진 시뮬레이터를 선정, 설치된 앱을 로드하고 언어/테마/화면별로 반복하여 이미지 저장합니다.
  • 차이점 분석 모듈: 베이스라인 PNG 와 현재 캡처 이미지를 대조하여 차이 비율 계산 및 하이라이트 영역을 표시, HTML 요약 리포트를 생성합니다.

이 세 부분은 최소한의 합의 규칙만으로 연결됩니다:

  • -TestPage, -AppLang, -DisplayStyle 형태의 런타임 인수 사용.
  • test_config.json 파일의 screens[].id가 앱 내부 등록 키와 매핑됨.
  • 파일 경로는 <언어>/<테마>/<화면명>.png 규칙을 따르며, 동일 경로를 기반으로 비교 수행.

이러한 분리는 범용 스크립트가 각 앱의 비즈니스 로직을 알지 못하게 하여 재사용성을 높입니다. 새로운 앱을 도입할 때는 페이지 구성 및 고정 데이터, 테마 전환 로직 부분만 조정하면 됩니다.

Swift 코드는 기존 UIKit 기능을 그대로 활용하므로 외부 의존성이 없으나, 호스트 측에서는 파이썬, Pillow 라이브러리 및 Xcode 환경의 simctl 도구가 필요합니다. "앱 내 제로 의존성"이라는 것은 전 체계의 환경 요구 사항이 없다는 의미는 아닙니다.

3. 실행 인수 파싱 및 초기화 순서 최적화

스크립트는 시뮬레이터 실행 요청을 다음과 같이 보낼 수 있습니다. 실제 UDID 와 번들 ID 는 프로젝트에 맞게 교체해야 합니다.

xcrun simctl launch --console \
  [UDID] [BundleID] \
  -TestPage checkout \
  -AppLang ko \
  -DisplayStyle dark

simctl 는 단순히 인자를 전달하는 역할만 수행합니다. -AppLang ko가 자동으로 앱의 현지화를 변경하지 않으며, 이 의미는 앱 내부의 진입 모듈에서 처리합니다.

효율적인 실행 흐름은 다음과 같습니다: 인수 해석 → 고정 데이터 준비 → 언어 설정 → 테마 동기화 → 뷰 컨트롤러 생성 → 창 노출. 특히 컨트롤러 생성 전에 언어 설정을 완료해야만 기존 캐시된 텍스트가 새로고침되어 올바른 로케일을 반영합니다.

일반 라우팅보다 먼저 진입 핸들러 삽입

다음은 UIKit 기반 SceneDelegate 에서 참조할 수 있는 설정 예시입니다. 프로젝트 자체의 테스터 클래스와 테마 관리자를 사용하여 기존 초기화 함수에 병합되어야 합니다.

class UICaptureInitializer {
    static func configure(
        in scene: UIWindowScene,
        with launchArgs: [String: String]
    ) {
        guard let targetClass = launchArgs["page"],
              let locale = Locale(identifier: launchArgs["lang"] ?? "en") else {
            return
        }

        // 테마 및 언어 미리 설정
        applyTheme(style: launchArgs["style"])
        updateSystemLocale(locale)
        
        // 타겟 뷰 컨트롤러 인스턴스화
        let viewController = createViewController(for: targetClass)
        
        // 메인 윈도우에 적용
        scene.windows.first?.rootViewController = viewController
        scene.windows.first?.makeKeyAndVisible()
    }
}

이 방식은 애플리케이션이 일반적인 사용자 입력 없이도 즉시 테스트 환경으로 진입하도록 보장하며, 스크립트 측에서의 복잡한 상태 복원 작업을 제거합니다.

태그: iOS Swift simctl visual-testing python

10월 16일 11:18에 게시됨