Screenshot testing is an effective way to verify how your UI looks to users. The Compose Preview Screenshot Testing tool combines the simplicity and features of composable previews with the productivity gains of running host-side screenshot tests. Compose Preview Screenshot Testing is designed to be as easy to use as composable previews.
A screenshot test is an automated test that takes a screenshot of a piece of UI and then compares it against a previously approved reference image. If the images don't match, the test fails and produces an HTML report to help you compare and find the differences.
With the Compose Preview Screenshot Testing tool, you can:
- Identify a number of existing or new composable previews you want to use for screenshot tests.
- Generate reference images from those composable previews.
- Generate an HTML report that identifies changes to those previews after you make code changes.
- Use
@Preview
parameters, such asuiMode
orfontScale
, and multi-previews to help you scale your tests. - Modularize your tests with the new
screenshotTest
source set.
Requirements
To use Compose Preview Screenshot Testing, you need the following:
- Android Gradle 8.5.0-beta01 or higher.
- Kotlin 1.9.20 or higher.
Setup
To enable the tool, follow these steps:
- Add the
com.android.compose.screenshot
plugin, version0.0.1-alpha01
to your project. - Add the plugin to your version catalogs file:
[versions] agp = "8.5.0-beta01" kotlin = "1.9.20" ... screenshot = "0.0.1-alpha01" [plugins] ... screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}
- In your module-level
build.gradle.kts
file, add the plugin in theplugins {}
block:plugins { ... alias(libs.plugins.screenshot) }
- Enable the experimental property in your project's
gradle.properties
file.android.experimental.enableScreenshotTest=true
- In the
android {}
block of your module-levelbuild.gradle.kts
file, enable the experimental flag to use thescreenshotTest
source set and ensure thatkotlinCompilerExtensionVersion
is set to 1.5.4 or higher.android { ... composeOptions { kotlinCompilerExtensionVersion = "1.5.4" } experimentalProperties["android.experimental.enableScreenshotTest"] = true }
- Make sure you've added the
ui-tooling
dependency.- Add it to your version catalogs:
[libraries] androidx-compose-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling"}
- Add it to your module-level
build.gradle.kts
file:dependencies { screenshotTestImplementation(libs.androidx.compose.ui.tooling) }
- Add it to your version catalogs:
Designate composable previews to use for screenshot tests
To designate the composable previews you want to use for screenshot tests, place
the previews in a test class. The test class file must be located in the new
screenshotTest
source set, for example
app/src/screenshotTest/kotlin/com/google/yourapp/ExamplePreviewScreenshots.kt
({module}/src/screenshotTest/{kotlin|java}/com/your/package
).
You can add more composables and/or previews, including multi-previews, in this file or other files created in the same sourceset.
package com.google.yourapp
import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.google.yourapp.ui.theme.MyApplicationTheme
class ExamplePreviewsScreenshots {
@Preview(showBackground = true)
@Composable
fun GreetingPreview() {
MyApplicationTheme {
Greeting("Android!")
}
}
}
Generate reference images
After you set up a test class, you need to generate reference images for each preview. These reference images are used to identify changes later, after you make code changes. To generate reference images for your composable preview screenshot tests, run the following Gradle task:
- Linux and macOS:
./gradlew updateDebugScreenshotTest
(./gradlew {:module:}update{Variant}ScreenshotTest
) - Windows:
gradlew updateDebugScreenshotTest
(gradlew {:module:}update{Variant}ScreenshotTest
)
After the task completes, find the reference images in
app/src/debug/screenshotTest/reference
({module}/src/{variant}/screenshotTest/reference
).
Generate a test report
Once the reference images exist, run the validate task to take a new screenshot and compare it with the reference image:
- Linux and macOS:
./gradlew validateDebugScreenshotTest
(./gradlew {:module:}validate{Variant}ScreenshotTest
) - Windows:
gradlew validateDebugScreenshotTest
(gradlew {:module:}validate{Variant}ScreenshotTest
)
The verification task creates an HTML report at
{module}/build/reports/screenshotTest/preview/{variant}/index.html
.
Known issues
You can find the current list of known issues in the tool's Issue Tracker component. Report any other feedback and issues through the issue tracker.
Release updates
Release notes and changes for ongoing versions
0.0.1-alpha06
This release introduces:
Image Difference Threshold: This new global threshold setting will allow you to gain finer control over screenshot comparisons. To configure, update your module's build.gradle.kts:
android {
...
testOptions {
...
screenshotTests {
imageDifferenceThreshold = 0.0001f // 0.01%
}
}
}
This threshold will be applied to all screenshot tests defined in the module.
- Bug Fixes: Some Compose Renderer bugs and added support for empty compose
- Performance Enhancements: Image diffing algorithm was updated to be faster