스크린샷 테스트는 사용자에게 UI가 어떻게 표시되는지 확인하는 효과적인 방법입니다. Compose 미리보기 스크린샷 테스트 도구는 구성 가능한 미리보기의 단순성과 기능을 호스트 측 스크린샷 테스트 실행의 생산성 향상과 결합합니다. Compose 미리보기 스크린샷 테스트는 구성 가능한 미리보기만큼 사용하기 쉽도록 설계되었습니다.
스크린샷 테스트는 UI의 스크린샷을 찍은 다음 이전에 승인된 참고 이미지와 비교하는 자동화된 테스트입니다. 이미지가 일치하지 않으면 테스트가 실패하고 차이점을 비교하고 찾는 데 도움이 되는 HTML 보고서를 생성합니다.
Compose 미리보기 스크린샷 테스트 도구를 사용하면 다음 작업을 할 수 있습니다.
@PreviewTest를 사용하여 기존 또는 새로운 구성 가능한 미리보기에 대한 스크린샷 테스트를 만듭니다.- 이러한 구성 가능한 미리보기에서 참고 이미지를 생성합니다.
- 코드 변경 후 이러한 미리보기에 대한 변경사항을 식별하는 HTML 보고서를 생성합니다.
uiMode또는fontScale과 같은@Preview매개변수와 여러 미리보기를 사용하여 테스트를 확장합니다.- 새로운
screenshotTest소스 세트로 테스트를 모듈화합니다.
IDE 통합
기본 Gradle 작업 (updateScreenshotTest 및 validateScreenshotTest)을 수동으로 실행하여 Compose 미리보기 스크린샷 테스트 도구를 사용할 수 있지만 Android 스튜디오 Otter 3 기능 출시 Canary 4에서는 전체 IDE 통합이 도입되었습니다. 이를 통해 IDE 내에서 참고 이미지를 생성하고, 테스트를 실행하고, 유효성 검사 실패를 분석할 수 있습니다. 다음은 주요 기능 중 일부입니다.
- 편집기 내 여백 아이콘. 이제 소스 코드에서 직접 테스트를 실행하거나 참고 이미지를 업데이트할 수 있습니다.
@PreviewTest로 주석 처리된 구성 가능한 함수 및 클래스 옆의 여백에 녹색 실행 아이콘이 표시됩니다.- 스크린샷 테스트 실행. 단일 함수 또는 전체 클래스에 대한 테스트를 실행합니다.
- 참고 이미지 추가 또는 업데이트. 선택한 범위에 대한 업데이트 흐름을 트리거합니다.
- 양방향 참고 관리. 이제 참고 이미지를 더 안전하고 세부적으로 업데이트할 수 있습니다.
- 새로운 참고 이미지 생성 대화상자. 일괄 Gradle 작업을 실행하는 대신 새 대화상자를 사용하면 생성하거나 업데이트할 미리보기를 정확하게 시각화하고 선택할 수 있습니다.
- 미리보기 변형. 대화상자에는 모든 미리보기 변형 (예: 밝은 테마 또는 어두운 테마, 또는 다양한 기기)이 개별적으로 나열되므로 이미지를 생성하기 전에 특정 항목을 선택하거나 선택 해제할 수 있습니다.
- 통합 테스트 결과 및 차이점 뷰어. IDE를 종료하지 않고 결과를 볼 수 있습니다.
- 통합 실행 패널. 스크린샷 테스트 결과가 표준 실행 도구 창에 표시됩니다. 테스트는 클래스 및 함수별로 그룹화되며 통과 또는 실패 상태가 명확하게 표시됩니다.
- 시각적 차이점 도구. 테스트가 실패하면 스크린샷 탭에서 참고, 실제, 차이점 이미지를 나란히 비교할 수 있습니다.
- 세부 속성. 속성 탭은 일치 비율, 이미지 크기, 사용된 특정 미리보기 구성 (예:
uiMode또는fontScale)을 비롯한 실패한 테스트에 관한 메타데이터를 제공합니다.
- 유연한 테스트 범위 지정. 이제 프로젝트 뷰에서 직접 다양한 범위로 스크린샷 테스트를 실행할 수 있습니다. 모듈, 디렉터리, 파일 또는 클래스를 마우스 오른쪽 버튼으로 클릭하여 해당 선택 항목에 대한 스크린샷 테스트를 실행합니다.
요구사항
전체 IDE 통합을 통해 Compose 미리보기 스크린샷 테스트를 사용하려면 프로젝트가 다음 요구사항을 충족해야 합니다.
- Android 스튜디오 Panda 1 Canary 4 이상
- Android Gradle 플러그인 (AGP) 버전 9.0 이상
- Compose 미리보기 스크린샷 테스트 플러그인 버전 0.0.1-alpha15 이상
- Kotlin 버전 2.2.10 이상
- JDK 버전 17 이상
- 프로젝트에 Compose 사용 설정됨. Compose Compiler Gradle 플러그인을 사용하여 Compose를 사용 설정하는 것이 좋습니다.
IDE 통합 없이 기본 Gradle 작업만 사용하려면 요구사항은 다음과 같습니다.
- Android Gradle 플러그인 (AGP) 버전 8.5.0 이상
- Compose 미리보기 스크린샷 테스트 플러그인 버전 0.0.1-alpha15 이상
- Kotlin 버전 1.9.20 이상 Compose Compiler Gradle 플러그인을 사용할 수 있도록 Kotlin 2.0 이상을 사용하는 것이 좋습니다.
- JDK 버전 17 이상
- 프로젝트에 Compose 사용 설정됨. Compose Compiler Gradle 플러그인을 사용하여 Compose를 사용 설정하는 것이 좋습니다.
설정
통합 도구와 기본 Gradle 작업은 모두 Compose 미리보기 스크린샷 테스트 플러그인을 사용합니다. 플러그인을 설정하는 방법은 다음과 같습니다.
프로젝트의
gradle.properties파일에서 실험용 속성을 사용 설정합니다.android.experimental.enableScreenshotTest=true모듈 수준
build.gradle.kts파일의android {}블록에서 실험용 플래그를 사용 설정하여screenshotTest소스 세트를 사용합니다.android { experimentalProperties["android.experimental.enableScreenshotTest"] = true }com.android.compose.screenshot플러그인 버전0.0.1-alpha15를 프로젝트에 추가합니다.플러그인을 버전 카탈로그 파일에 추가합니다.
[versions] agp = "9.0.0-rc03" kotlin = "2.1.20" screenshot = "0.0.1-alpha15" [plugins] screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}모듈 수준
build.gradle.kts파일의plugins {}블록에서 플러그인을 추가합니다.plugins { alias(libs.plugins.screenshot) }
screenshot-validation-api및ui-tooling종속 항목을 추가합니다.버전 카탈로그에 추가합니다.
[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"}모듈 수준
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!")
}
}
참고 이미지 생성
테스트 클래스를 설정한 후 각 미리보기에 대한 참고 이미지를 생성해야 합니다. 이러한 참고 이미지는 나중에 코드 변경 후 변경사항을 식별하는 데 사용됩니다. 구성 가능한 미리보기 스크린샷 테스트의 참고 이미지를 생성하려면 이 섹션의 IDE 통합 또는 Gradle 작업에 관한 안내를 따르세요.
IDE에서
@PreviewTest 함수 옆에 있는 여백 아이콘을 클릭하고 참고 이미지 추가/업데이트 를 선택합니다. 대화상자에서 미리보기를 선택하고 추가 를 클릭합니다.
Gradle 작업 사용
다음 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)에서 참고 이미지를 찾습니다.
테스트 보고서 생성
참고 이미지가 있으면 이 섹션의 IDE 통합 또는 Gradle 작업에 관한 안내에 따라 테스트 보고서를 생성합니다.
IDE에서
@PreviewTest 함수 옆에 있는 여백 아이콘을 클릭하고 'ScreenshotTests' 실행 을 선택합니다.
테스트가 실패하면 실행 패널에서 테스트 이름을 클릭합니다. 스크린샷 탭을 선택하여 통합 확대/이동 컨트롤을 사용하여 이미지 차이점을 검사합니다.
Gradle 작업 사용
유효성 검사 작업을 실행하여 새 스크린샷을 찍고 참고 이미지와 비교합니다.
- 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 보고서를 만듭니다.
문제 해결
Compose 미리보기 스크린샷 테스트는 메모리 집약적일 수 있는 호스트 측 테스트를 실행합니다. gradle.properties 파일에 다음 속성을 추가하여 테스트 JVM의 최대 힙 크기를 늘릴 수 있습니다.
android.compose.screenshot.maxHeapSize=4g
알려진 문제
- Kotlin 멀티플랫폼 (KMP): IDE와 기본 플러그인은 모두 Android 프로젝트 전용으로 설계되었습니다. KMP 프로젝트에서 Android 이외의 타겟은 지원하지 않습니다.
도구의 Issue Tracker 구성요소에서 현재 알려진 문제의 전체 목록을 확인할 수 있습니다. Issue Tracker를 통해 다른 의견과 문제를 보고하세요. issue tracker
업데이트 출시
출시 업데이트의 전체 목록은 출시 노트를 참고하세요.