스크린샷 테스트는 사용자에게 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 이상을 사용하는 것이 좋습니다.
스크린샷 테스트에 사용할 컴포저블 미리보기를 지정하려면 @PreviewTest 주석으로 미리보기를 표시합니다. 미리보기는 새 screenshotTest 소스 세트(예: app/src/screenshotTest/kotlin/com/example/yourapp/ExamplePreviewScreenshotTest.kt)에 있어야 합니다.
이 파일이나 동일한 소스 세트에서 생성된 다른 파일에 컴포저블 및/또는 미리보기(다중 미리보기 포함)를 추가할 수 있습니다.
호스트 머신의 언어와 관계없이 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를 업데이트하세요.
이 페이지에 나와 있는 콘텐츠와 코드 샘플에는 콘텐츠 라이선스에서 설명하는 라이선스가 적용됩니다. 자바 및 OpenJDK는 Oracle 및 Oracle 계열사의 상표 또는 등록 상표입니다.
최종 업데이트: 2025-08-11(UTC)
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-08-11(UTC)"],[],[],null,["# Compose Preview Screenshot Testing\n\n| **Experimental:** Compose Preview Screenshot Testing is still in development. Its features and APIs are subject to change substantially during the alpha phase. Report any feedback and issues through the [issue tracker](https://issuetracker.google.com/issues/new?component=192708&template=840533).\n\nScreenshot testing is an effective way to verify how your UI looks to users. The\nCompose Preview Screenshot Testing tool combines the simplicity and features of\n[composable previews](/develop/ui/compose/tooling/previews) with the\nproductivity gains of running host-side screenshot tests. Compose Preview\nScreenshot Testing is designed to be as easy to use as composable previews.\n\nA screenshot test is an automated test that takes a screenshot of a piece of UI\nand then compares it against a previously approved reference image. If the\nimages don't match, the test fails and produces an HTML report to help you\ncompare and find the differences.\n\nWith the Compose Preview Screenshot Testing tool, you can:\n\n- Use `@PreviewTest` to create screenshot tests for existing or new composable previews.\n- Generate reference images from those composable previews.\n- Generate an HTML report that identifies changes to those previews after you make code changes.\n- Use `@Preview` parameters, such as `uiMode` or `fontScale`, and multi-previews to help you scale your tests.\n- Modularize your tests with the new `screenshotTest` source set.\n\n**Figure 1.** Example HTML report.\n\nRequirements\n------------\n\nTo use Compose Preview Screenshot Testing, you need the following:\n\n- Android Gradle plugin 8.5.0 or higher.\n- Kotlin 1.9.20 or higher. We recommend using Kotlin 2.0 or higher so you can use the Compose Compiler Gradle plugin.\n- JDK 23 or lower.\n- Compose enabled for your project. We recommend enabling Compose using\n the [Compose Compiler Gradle plugin](/develop/ui/compose/compiler).\n\n | **Note:** If you can't use the Compose Compiler Gradle plugin, you can enable Compose by [declaring a dependency on the Compose Compiler directly](/jetpack/androidx/releases/compose-kotlin#kts). Make sure you use `kotlinCompilerExtensionVersion` version 1.5.4 or higher.\n\nSetup\n-----\n\nTo enable the tool, follow these steps:\n\n1. Add the `com.android.compose.screenshot` plugin, version `0.0.1-alpha11` to your project.\n 1. Add the plugin to your version catalogs file: \n\n ```ini\n [versions]\n agp = \"8.11.0-alpha06\"\n kotlin = \"2.1.20\"\n screenshot = \"0.0.1-alpha11\"\n\n [plugins]\n screenshot = { id = \"com.android.compose.screenshot\", version.ref = \"screenshot\"}\n ```\n 2. In your module-level `build.gradle.kts` file, add the plugin in the `plugins {}` block: \n\n ```kotlin\n plugins {\n alias(libs.plugins.screenshot)\n }\n ```\n2. Enable the experimental property in your project's `gradle.properties` file. \n\n ```text\n android.experimental.enableScreenshotTest=true\n ```\n3. In the `android {}` block of your module-level `build.gradle.kts` file, enable the experimental flag to use the `screenshotTest` source set. \n\n ```\n android {\n experimentalProperties[\"android.experimental.enableScreenshotTest\"] = true\n }\n ```\n4. Add the [`screenshot-validation-api`](https://maven.google.com/web/index.html?q=screenshot-validation-api#com.android.tools.screenshot:screenshot-validation-api) and [`ui-tooling`](https://maven.google.com/web/index.html?q=tooling#androidx.compose.ui:ui-tooling) dependencies.\n 1. Add them to your version catalogs: \n\n ```ini\n [libraries]\n screenshot-validation-api = { group = \"com.android.tools.screenshot\", name = \"screenshot-validation-api\", version.ref = \"screenshot\"}\n androidx-ui-tooling = { group = \"androidx.compose.ui\", name = \"ui-tooling\"}\n ```\n 2. Add them to your module-level `build.gradle.kts` file: \n\n ```kotlin\n dependencies {\n screenshotTestImplementation(libs.screenshot.validation.api)\n screenshotTestImplementation(libs.androidx.ui.tooling)\n }\n ```\n\nDesignate composable previews to use for screenshot tests\n---------------------------------------------------------\n\nTo designate the composable previews you want to use for screenshot tests, mark\nthe previews with the `@PreviewTest` annotation. The previews must be located in\nthe new `screenshotTest` source set, for example\n`app/src/screenshotTest/kotlin/com/example/yourapp/ExamplePreviewScreenshotTest.kt`.\n\nYou can add more composables and/or previews, including multi-previews, in\nthis file or other files created in the same source set. \n\n package com.example.yourapp\n\n import androidx.compose.runtime.Composable\n import androidx.compose.ui.tooling.preview.Preview\n import com.android.tools.screenshot.PreviewTest\n import com.example.yourapp.ui.theme.MyApplicationTheme\n\n @PreviewTest\n @Preview(showBackground = true)\n @Composable\n fun GreetingPreview() {\n MyApplicationTheme {\n Greeting(\"Android!\")\n }\n }\n\nGenerate reference images\n-------------------------\n\nAfter you set up a test class, you need to generate reference images for each\npreview. These reference images are used to identify changes later, after you\nmake code changes. To generate reference images for your composable preview\nscreenshot tests, run the following Gradle task:\n\n- Linux and macOS: `./gradlew updateDebugScreenshotTest` (`./gradlew :{module}:update{Variant}ScreenshotTest`)\n- Windows: `gradlew updateDebugScreenshotTest` (`gradlew :{module}:update{Variant}ScreenshotTest`)\n\nAfter the task completes, find the reference images in\n`app/src/screenshotTestDebug/reference`\n(`{module}/src/screenshotTest{Variant}/reference`).\n| **Note:** The reference images are named with a concatenation of the fully-qualified name of the test function and a hash of the preview parameters, for example `com.sample.screenshottests.test1_da39a3ee_c2200e98_0.png`.\n\nGenerate a test report\n----------------------\n\nOnce the reference images exist, run the validate task to take a new screenshot\nand compare it with the reference image:\n\n- Linux and macOS: `./gradlew validateDebugScreenshotTest` (`./gradlew :{module}:validate{Variant}ScreenshotTest`)\n- Windows: `gradlew validateDebugScreenshotTest` (`gradlew :{module}:validate{Variant}ScreenshotTest`)\n\nThe verification task creates an HTML report at\n`{module}/build/reports/screenshotTest/preview/{variant}/index.html`.\n\nKnown issues\n------------\n\nYou can find the current list of known issues in the tool's\n[issue tracker component](https://issuetracker.google.com/issues?q=status:open%20componentid:1581441&s=created_time:desc). Report any other feedback and issues\nthrough the [issue tracker](https://issuetracker.google.com/issues/new?component=192708&template=840533).\n\nRelease updates\n---------------\n\n### 0.0.1-alpha11\n\nThis release introduces:\n\n- Compatibility with Android Gradle Plugin (AGP) 8.13.\n- Added support for parsing XML drawables with decimal values regardless of the host machine's locale.\n- For a host machine using JDK 24 or higher, compatible JDK (11-23) will be picked up, provided one is installed.\n\n### 0.0.1-alpha10\n\nThis release introduces:\n\n- From this version, you need to mark all of your preview functions with the\n `@PreviewTest` annotation. Previews without the annotation won't be executed.\n\n- Reference image directory is changed from\n `{module}/src/{variant}/screenshotTest/reference` to\n `{module}/src/screenshotTest{Variant}/reference`. This is to make sure those\n generated reference images won't be part of the production code, and to be\n aligned with the [directory structure](/studio/test/advanced-test-setup#create-instrumented-test-for-build-variant) of other test types.\n\n- The `{variant}PreviewScreenshotRender` task is removed. Image rendering is\n migrated into JUnit Test Engine.\n\n- The `update{Variant}ScreenshotTest` task will compare new rendering images to\n reference images before updating. It will only update images that have\n differences greater than a specified threshold. `--updateFilter` commandline\n flag was removed.\n\n### 0.0.1-alpha06\n\nThis release introduces:\n\nImage Difference Threshold: This new global threshold setting will allow you to\ngain finer control over screenshot comparisons. To configure, update your\nmodule's build.gradle.kts: \n\n android {\n testOptions {\n screenshotTests {\n imageDifferenceThreshold = 0.0001f // 0.01%\n }\n }\n }\n\nThis threshold will be applied to all screenshot tests defined in the module.\n\n- Bug Fixes: Some Compose Renderer bugs and added support for empty compose\n- Performance Enhancements: Image diffing algorithm was updated to be faster"]]
