Compose 미리보기 스크린샷 테스트

스크린샷 테스트는 사용자에게 UI가 어떻게 표시되는지 확인하는 효과적인 방법입니다. Compose 미리보기 스크린샷 테스트 도구는 컴포저블 미리보기의 간편함과 기능을 호스트 측 스크린샷 테스트 실행의 생산성 향상과 결합합니다. Compose 미리보기 스크린샷 테스트는 컴포저블 미리보기만큼 사용하기 쉽도록 설계되었습니다.

스크린샷 테스트는 UI의 스크린샷을 찍은 후 이전에 승인된 참조 이미지와 비교하는 자동화된 테스트입니다. 이미지가 일치하지 않으면 테스트가 실패하고 차이점을 비교하고 찾을 수 있는 HTML 보고서가 생성됩니다.

Compose 미리보기 스크린샷 테스트 도구를 사용하면 다음 작업을 할 수 있습니다.

  • @PreviewTest를 사용하여 기존 또는 새 컴포저블 미리보기에 대한 스크린샷 테스트를 만듭니다.
  • 이러한 컴포저블 미리보기에서 참조 이미지를 생성합니다.
  • 코드 변경 후 이러한 미리보기의 변경사항을 식별하는 HTML 보고서를 생성합니다.
  • uiMode 또는 fontScale와 같은 @Preview 매개변수와 다중 미리보기를 사용하여 테스트를 확장할 수 있습니다.
  • 새로운 screenshotTest 소스 세트로 테스트를 모듈화하세요.
그림 1. HTML 보고서의 예입니다.

요구사항

Compose 미리보기 스크린샷 테스트를 사용하려면 다음이 필요합니다.

  • Android Gradle 플러그인 8.5.0 이상
  • Kotlin 1.9.20 이상 Compose 컴파일러 Gradle 플러그인을 사용할 수 있도록 Kotlin 2.0 이상을 사용하는 것이 좋습니다.
  • JDK 23 이하

  • 프로젝트에 Compose가 사용 설정되어 있습니다. Compose 컴파일러 Gradle 플러그인을 사용하여 Compose를 사용 설정하는 것이 좋습니다.

설정

도구를 사용 설정하려면 다음 단계를 따르세요.

  1. 프로젝트의 gradle.properties 파일에서 실험용 속성을 사용 설정합니다. 
          android.experimental.enableScreenshotTest=true
  2. 모듈 수준 build.gradle.kts 파일의 android {} 블록에서 실험용 플래그를 사용 설정하여 screenshotTest 소스 세트를 사용합니다. 
          android {
          experimentalProperties["android.experimental.enableScreenshotTest"] = true
      }
  3. 프로젝트에 com.android.compose.screenshot 플러그인 버전 0.0.1-alpha13을 추가합니다.
    1. 버전 카탈로그 파일에 플러그인을 추가합니다. 
                [versions]
          agp = "9.0.0-rc03"
          kotlin = "2.1.20"
          screenshot = "0.0.1-alpha13"

          [plugins]
          screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}
    2. 모듈 수준 build.gradle.kts 파일의 plugins {} 블록에 플러그인을 추가합니다. 
                plugins {
              alias(libs.plugins.screenshot)
          }
  4. screenshot-validation-api 및 ui-tooling 종속 항목을 추가합니다.
    1. 버전 카탈로그에 추가합니다. 
                [libraries]
          screenshot-validation-api = { group = "com.android.tools.screenshot", name = "screenshot-validation-api", version.ref = "screenshot"}
          androidx-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling"}
    2. 모듈 수준 build.gradle.kts 파일에 추가합니다. 
                dependencies {
            screenshotTestImplementation(libs.screenshot.validation.api)
            screenshotTestImplementation(libs.androidx.ui.tooling)
          }

스크린샷 테스트에 사용할 컴포저블 미리보기 지정

스크린샷 테스트에 사용할 컴포저블 미리보기를 지정하려면 @PreviewTest 주석으로 미리보기를 표시합니다. 미리보기는 새 screenshotTest 소스 세트(예: app/src/screenshotTest/kotlin/com/example/yourapp/ExamplePreviewScreenshotTest.kt)에 있어야 합니다.

이 파일이나 동일한 소스 세트에서 생성된 다른 파일에 컴포저블 및/또는 미리보기(다중 미리보기 포함)를 추가할 수 있습니다.

package com.example.yourapp

import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.android.tools.screenshot.PreviewTest
import com.example.yourapp.ui.theme.MyApplicationTheme

@PreviewTest
@Preview(showBackground = true)
@Composable
fun GreetingPreview() {
    MyApplicationTheme {
        Greeting("Android!")
    }
}

참조 이미지 생성

테스트 클래스를 설정한 후 각 미리보기에 대한 참조 이미지를 생성해야 합니다. 이러한 참조 이미지는 나중에 코드를 변경한 후 변경사항을 식별하는 데 사용됩니다. 컴포저블 미리보기 스크린샷 테스트의 참조 이미지를 생성하려면 다음 Gradle 작업을 실행하세요.

  • Linux 및 macOS: ./gradlew updateDebugScreenshotTest (./gradlew :{module}:update{Variant}ScreenshotTest)
  • Windows: gradlew updateDebugScreenshotTest (gradlew :{module}:update{Variant}ScreenshotTest)

작업이 완료되면 app/src/screenshotTestDebug/reference({module}/src/screenshotTest{Variant}/reference)에서 참조 이미지를 찾습니다.

테스트 보고서 생성

참조 이미지가 있으면 validate 작업을 실행하여 새 스크린샷을 찍고 참조 이미지와 비교합니다.

  • Linux 및 macOS: ./gradlew validateDebugScreenshotTest (./gradlew :{module}:validate{Variant}ScreenshotTest)
  • Windows: gradlew validateDebugScreenshotTest (gradlew :{module}:validate{Variant}ScreenshotTest)

확인 작업은 {module}/build/reports/screenshotTest/preview/{variant}/index.html에 HTML 보고서를 만듭니다.

알려진 문제

알려진 문제의 현재 목록은 도구의 문제 추적 도구 구성요소에서 확인할 수 있습니다. 다른 의견과 문제는 Issue Tracker를 통해 보고해 주세요.

업데이트 출시

0.0.1-alpha13

이번 출시에서는 다음이 도입되었습니다.

  • JDK 17 이상과의 호환성
  • 버그가 수정되고 Android 스튜디오와의 통합이 개선되었습니다.

0.0.1-alpha12

이번 출시에서는 다음이 도입되었습니다.

  • Android Gradle 플러그인 (AGP) 9.0과의 호환성
  • JDK 24 이상에서 스크린샷 테스트 실행 지원
  • 최대 힙 크기를 구성하는 지원
  • 렌더링 실패가 수정되고 테스트 안정성이 개선되었습니다.
  • 새 이미지 및 참조 이미지와 관련된 백분율 차이 및 기타 메타데이터를 포함하도록 보고서가 개선되었습니다.

0.0.1-alpha11

이번 출시에서는 다음이 도입되었습니다.

  • Android Gradle 플러그인 (AGP) 8.13과의 호환성
  • 호스트 머신의 언어와 관계없이 10진수 값으로 XML 드로어블을 파싱하는 지원이 추가되었습니다.
  • JDK 24 이상을 사용하는 호스트 머신의 경우 호환되는 JDK (11~23)가 설치되어 있다면 선택됩니다.

0.0.1-alpha10

이번 출시에서는 다음이 도입되었습니다.

  • 이 버전부터는 모든 미리보기 함수를 @PreviewTest 주석으로 표시해야 합니다. 주석이 없는 미리보기는 실행되지 않습니다.

  • 참조 이미지 디렉터리가 {module}/src/{variant}/screenshotTest/reference에서 {module}/src/screenshotTest{Variant}/reference로 변경됩니다. 생성된 참조 이미지가 프로덕션 코드에 포함되지 않도록 하고 다른 테스트 유형의 디렉터리 구조와 일치시키기 위해서입니다.

  • {variant}PreviewScreenshotRender 작업이 삭제됩니다. 이미지 렌더링이 JUnit 테스트 엔진으로 이전됩니다.

  • update{Variant}ScreenshotTest 작업은 업데이트하기 전에 새 렌더링 이미지를 참조 이미지와 비교합니다. 지정된 기준점보다 큰 차이가 있는 이미지만 업데이트됩니다. --updateFilter 명령줄 플래그가 삭제되었습니다.

0.0.1-alpha06

이번 출시에서는 다음이 도입되었습니다.

이미지 차이 임계값: 이 새로운 전역 임계값 설정을 사용하면 스크린샷 비교를 더 세밀하게 제어할 수 있습니다. 구성하려면 모듈의 build.gradle.kts를 업데이트하세요.

android {
    testOptions {
        screenshotTests {
            imageDifferenceThreshold = 0.0001f // 0.01%
        }
    }
}

이 기준점은 모듈에 정의된 모든 스크린샷 테스트에 적용됩니다.

  • 버그 수정: 일부 Compose 렌더러 버그 수정 및 빈 Compose 지원 추가
  • 성능 개선: 이미지 차이 알고리즘이 더 빨라지도록 업데이트됨