Roborazzi로 안드로이드 스크린샷 변경점 시각화 테스트 구축하기

// root build.gradle.kts
plugins {
    // ...
    id("io.github.takahirom.roborazzi") version "[version]" apply false
}

// root build.gradle.kts
buildscript {
  dependencies {
    // ...
    classpath("io.github.takahirom.roborazzi:roborazzi-gradle-plugin:[version]")
  }
}

// module build.gradle.kts
plugins {
    // ...
    id("io.github.takahirom.roborazzi")
}

android {
    // 기존 설정
    
    testOptions {
        unitTests {
            isIncludeAndroidResources = true
            // Robolectric의 하드웨어 렌더링 모드 사용
            all {
                it.systemProperties["robolectric.pixelCopyRenderMode"] = "hardware"
            }
        }
    }
}

dependencies {
    // Core functions
    testImplementation("io.github.takahirom.roborazzi:roborazzi:[version]")

    // Jetpack Compose
    testImplementation("io.github.takahirom.roborazzi:roborazzi-compose:[version]")

    // JUnit rules
    testImplementation("io.github.takahirom.roborazzi:roborazzi-junit-rule:[version]")
}

// Roborazzi 설정
roborazzi {
    // 레퍼런스 이미지 저장 경로 설정
    outputDir.set(file("src/test/screenshots"))

    // 비교 이미지 저장 경로 (Experimental option)
    compare {
        outputDir.set(file("build/outputs/screenshots_comparison"))
    }
}

# 스크린샷 테스트 활성화 옵션
roborazzi.test.record=true
# roborazzi.test.compare=true
# roborazzi.test.verify=true

# 이미지 리사이즈 스케일 설정
roborazzi.record.resizeScale=0.5

# 파일 경로 전략 설정
# 기본값은 relativePathFromCurrentDirectory
roborazzi.record.filePathStrategy=relativePathFromRoborazziContextOutputDirectory

# 이미지 포맷 설정 (WebP 지원, Experimental)
# roborazzi.record.image.extension=webp

# 오래된 스크린샷 자동 정리 (주의 필요)
# roborazzi.cleanupOldScreenshots=true

@RunWith(RobolectricTestRunner::class)
@GraphicsMode(GraphicsMode.Mode.NATIVE) // Robolectric Native Graphics 모드 활성화 (필수)
class LoginScreenshotTest {

    @get:Rule
    val composeTestRule = createComposeRule()
    
    @Test
    fun captureLoginScreen_defaultState() {
        // 컴포즈 UI 설정
        composeTestRule.setContent {
            MyAppTheme {
                LoginScreen(
                    uiState = LoginUiState.Default,
                    onLoginClick = {},
                    onEmailChanged = {},
                    onPasswordChanged = {}
                )
            }
        }
        
        // 스크린샷 캡처
        composeTestRule.onRoot()
            .captureRoboImage(
                // 파일명 지정 (기본 출력 디렉토리에 저장됨)
                "loginScreen_defaultState",
                // 추가 옵션 설정
                roborazziOptions = RoborazziOptions(
                    // 이미지 리사이징
                    recordOptions = RoborazziOptions.RecordOptions(
                        resizeScale = 0.75f
                    ),
                    // 비교 옵션
                    compareOptions = RoborazziOptions.CompareOptions(
                        changeThreshold = 0.01f
                    )
                )
            )
    }
    
    @Test
    fun captureLoginScreen_errorState() {
        composeTestRule.setContent {
            MyAppTheme {
                LoginScreen(
                    uiState = LoginUiState.Error("Invalid credentials"),
                    onLoginClick = {},
                    onEmailChanged = {},
                    onPasswordChanged = {}
                )
            }
        }
        
        // 특정 컴포넌트만 캡처할 수도 있음
        composeTestRule.onNodeWithTag("errorMessage")
            .captureRoboImage(
                "loginScreen_errorMessage"
            )
        
        // 전체 화면 캡처
        composeTestRule.onRoot()
            .captureRoboImage(
                "loginScreen_errorState"
            )
    }
}

@RunWith(RobolectricTestRunner::class)
@GraphicsMode(GraphicsMode.Mode.NATIVE)
class RuleTest {
    @get:Rule
    val composeTestRule = createComposeRule()
    
    @get:Rule
    val roborazziRule = RoborazziRule(
        composeRule = composeTestRule,
        captureRoot = composeTestRule.onRoot(),
        options = RoborazziRule.Options(
            // 테스트 실패 시에만 이미지 캡처
            captureType = RoborazziRule.CaptureType.Gif(onlyFail = true),
            // 이미지 비교 옵션 설정
            roborazziOptions = RoborazziOptions(
                compareOptions = RoborazziOptions.CompareOptions(
                    // 안티앨리어싱 문제 해결을 위한 설정
                    imageComparator = SimpleImageComparator(
                        maxDistance = 0.007f,
                        vShift = 2,    // 수직 이동 허용
                        hShift = 2     // 수평 이동 허용
                    )
                )
            )
        )
    )
    
    @Test
    // RoborazziRule 무시 어노테이션
    // @RoborazziRule.Ignore
    fun testWithRule() {
        composeTestRule.setContent {
            MyAppTheme {
                // ...
            }
        }
        
        // RoborazziRule이 테스트 실행 과정에서 자동으로 이미지 캡처
    }
}

@Test
fun captureRoboGifSample() {
    onView(ViewMatchers.isRoot())
        .captureRoboGif("build/test.gif") {
            // 앱 실행
            ActivityScenario.launch(MainActivity::class.java)
            // 다음 페이지로 이동
            onView(withId(R.id.button_first))
                .perform(click())
            // 뒤로 가기
            pressBack()
            // 다시 다음 페이지로 이동
            onView(withId(R.id.button_first))
                .perform(click())
        }
}

// 클래스 레벨에서 기본 디바이스 설정
@RunWith(RobolectricTestRunner::class)
@GraphicsMode(GraphicsMode.Mode.NATIVE)
@Config(qualifiers = RobolectricDeviceQualifiers.Pixel5)
class DeviceSpecificScreenshotTest {
    // ...
}

// 특정 테스트 메서드에만 다른 설정 적용
@Test
@Config(qualifiers = RobolectricDeviceQualifiers.MediumTablet + "+land")
fun captureLoginScreen_landscapeTablet() {
    // ...
}

// 다크 모드 설정
@Test
@Config(qualifiers = "+night")
fun captureLoginScreen_darkMode() {
    // ...
}

// 로케일 설정
@Test
@Config(qualifiers = "+ja")  // 일본어 로케일
fun captureLoginScreen_japaneseLocale() {
    // ...
}

// build.gradle.kts
android {
    testOptions {
        unitTests.all {
            maxHeapSize = "4096m"
        }
    }
}

// 테스트 클래스에 적용
@Config(sdk = [35])  // 최신 API 레벨 사용
@GraphicsMode(GraphicsMode.Mode.NATIVE)  // Native Graphics 모드 필수

// build.gradle.kts
android {
    testOptions {
        unitTests.all {
            it.systemProperties["robolectric.pixelCopyRenderMode"] = "hardware"
        }
    }
}

name: Android Pull Request CI

on:
  pull_request:
    branches: [ main, develop ]

jobs:
  verify-screenshots:
    runs-on: ubuntu-latest
    
    permissions:
      checks: write
      pull-requests: write
      contents: write
      
    steps:
      - name: Checkout the code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
        
      - name: Set up JDK
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'
          cache: 'gradle'
          
      - name: Set up Android SDK
        uses: android-actions/setup-android@v3
        
      - name: Grant execute permission for gradlew
        run: chmod +x gradlew
        
      - name: Run ktlint
        run: ./gradlew ktlintCheck
        
      # 스크린샷 검증 단계
      - name: Verify Roborazzi Screenshots
        id: screenshotsverify
        continue-on-error: true
        run: ./gradlew verifyRoborazziDebug
        
      # 검증 실패 시 새 스크린샷 생성
      - name: Generate new screenshots if verification failed
        id: screenshotsrecord
        if: steps.screenshotsverify.outcome == 'failure'
        run: ./gradlew recordRoborazziDebug
        
      # 브랜치명에서 JIRA 티켓 추출 (회사 상황에 맞게 조정)
      - name: Extract JIRA ticket
        id: extract_ticket
        if: steps.screenshotsrecord.outcome == 'success'
        run: |
          BRANCH_NAME=$(echo ${{ github.head_ref }})
          echo "branch_name=$BRANCH_NAME" >> $GITHUB_OUTPUT
          
          if [[ $BRANCH_NAME =~ (TICKET-[0-9]+) ]]; then
            TICKET="${BASH_REMATCH[1]}"
            echo "ticket=$TICKET" >> $GITHUB_OUTPUT
            echo "Found JIRA ticket: $TICKET"
          else
            echo "ticket=NO-TICKET" >> $GITHUB_OUTPUT
            echo "No JIRA ticket found in branch name"
          fi
          
      # 새 스크린샷 커밋
      - name: Push new screenshots if available
        uses: stefanzweifel/git-auto-commit-action@v5
        if: steps.screenshotsrecord.outcome == 'success'
        with:
          file_pattern: '**/*.png'
          disable_globbing: false
          commit_message: "${{ steps.extract_ticket.outputs.ticket != 'NO-TICKET' && format('{0} feat: 스크린샷 업데이트', steps.extract_ticket.outputs.ticket) || 'NO-TICKET feat: 스크린샷 업데이트' }}"
          
      # 비교 이미지 수집
      - name: Copy screenshot comparison files
        id: copy_screenshots
        if: steps.screenshotsverify.outcome == 'failure'
        run: |
          mkdir -p /tmp/screenshot-diff
          
          cd ${{ github.workspace }}
          find . -name "*_compare.png" -exec cp {} /tmp/screenshot-diff/ \;
          
          if [ -z "$(find /tmp/screenshot-diff -type f -name '*.png')" ]; then
            echo "No screenshot files found"
            echo "has_images=false" >> $GITHUB_OUTPUT
          else
            echo "Found screenshot comparison images:"
            ls -la /tmp/screenshot-diff
            echo "has_images=true" >> $GITHUB_OUTPUT
          fi
          
      # Companion Branch 생성
      - name: Create companion branch for screenshot comparison
        id: companion_branch
        if: steps.copy_screenshots.outputs.has_images == 'true'
        run: |
          BRANCH_NAME="screenshot-compare-${{ github.event.pull_request.number }}"
          echo "branch_name=$BRANCH_NAME" >> $GITHUB_OUTPUT
          
          git config --global user.name "GitHub Actions"
          git config --global user.email "actions@github.com"
          
          git stash -u || true
          
          git branch -D "$BRANCH_NAME" || true
          git checkout --orphan "$BRANCH_NAME"
          git rm -rf .
          
          mkdir -p screenshot-diff
          
          cp /tmp/screenshot-diff/*.png screenshot-diff/
          
          git add screenshot-diff
          git commit -m "Add screenshot comparison results"
          git push origin "$BRANCH_NAME" -f
          
          echo "companion_push_success=echo "companion_push_success=true" >> $GITHUB_OUTPUT

          git checkout -f ${{ github.head_ref }} || git checkout -f HEAD
          
      # 마크다운 리포트 생성
      - name: Generate markdown report for screenshot diffs
        id: generate_report
        if: steps.companion_branch.outputs.companion_push_success == 'true'
        run: |
          REPORT="## 📸 스크린샷 비교 결과\n\n"
          REPORT+="| 화면 이름 | 비교 이미지 |\n"
          REPORT+="|:--------:|:----------:|\n"
          
          BRANCH_NAME="${{ steps.companion_branch.outputs.branch_name }}"
          
          for FILE in /tmp/screenshot-diff/*.png; do
            FILENAME=$(basename "$FILE")
            SCREENNAME=${FILENAME%_compare.png}
          
            IMG_URL="https://github.com/${{ github.repository }}/blob/$BRANCH_NAME/screenshot-diff/$FILENAME?raw=true"
          
            REPORT+="| \`$SCREENNAME\` | ![Screenshot]($IMG_URL) |\n"
          done
          
          EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
          echo "report<<$EOF" >> $GITHUB_OUTPUT
          echo -e "$REPORT" >> $GITHUB_OUTPUT
          echo "$EOF" >> $GITHUB_OUTPUT
          
          echo "found_images=true" >> $GITHUB_OUTPUT
          
      # 기존 PR 코멘트 찾기
      - name: Find existing comment
        uses: peter-evans/find-comment@v3
        id: find_comment
        if: steps.generate_report.outputs.found_images == 'true'
        with:
          issue-number: ${{ github.event.pull_request.number }}
          comment-author: 'github-actions[bot]'
          body-includes: '## 📸 스크린샷 비교 결과'
          
      # PR 코멘트 생성 또는 업데이트
      - name: Create or update comment with comparison results
        uses: peter-evans/create-or-update-comment@v4
        if: steps.generate_report.outputs.found_images == 'true'
        with:
          comment-id: ${{ steps.find_comment.outputs.comment-id }}
          issue-number: ${{ github.event.pull_request.number }}
          body: ${{ steps.generate_report.outputs.report }}
          edit-mode: replace
          
      # 단위 테스트 실행
      - name: Run unit tests
        run: ./gradlew testDebugUnitTest --stacktrace

- name: Store reference images as artifacts
  uses: actions/upload-artifact@v4
  with:
    name: reference-screenshots
    path: src/test/screenshots
    retention-days: 30