Build Screenshot Tests
Testing & Qualitybuild_screenshot_testsBuild Screenshot Tests is an Agent Skill for testing & quality published in the androidx/androidx repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
A skill for building instrumented screenshot tests in Remote Compose using RemoteScreenshotTestRule.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/androidx/androidx/blob/HEAD/compose/remote/remote-creation-compose/.agents/skills/screenshot_testing/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/build-screenshot-tests, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Building Screenshot Tests using RemoteScreenshotTestRule
[!IMPORTANT] AI INSTRUCTION: Do not assume you should use
RemoteScreenshotTestRulefor all tests. If the user asks you to write a screenshot test, you MUST first explicitly ask them: "Would you like me to use theRemoteScreenshotTestRulefor this test?" Proceed with using this skill only if they confirm.
This skill provides guidelines for building screenshot tests in the @compose/remote/remote-creation-compose project.
Purpose
RemoteScreenshotTestRule is a JUnit rule that allows taking screenshots of Remote Compose components. It handles:
- Capturing the remote document.
- Rendering it using
RemoteDocumentPlayer. - Verifying the rendered image against a "golden" screenshot.
Setup
-
Test Class Annotations: Annotate the test class with
@MediumTest,@SdkSuppress(minSdkVersion = 35, maxSdkVersion = 35), and@RunWith(AndroidJUnit4::class). -
Add the Rule: Define the rule inside the test class.
@get:Rule val composeTestRule: RemoteScreenshotTestRule by lazy { RemoteScreenshotTestRule( moduleDirectory = SCREENSHOT_GOLDEN_DIRECTORY, context = ApplicationProvider.getApplicationContext(), matcher = MSSIMMatcher(threshold = 0.999), ) }Note:
SCREENSHOT_GOLDEN_DIRECTORYis usually defined in the module, e.g.,androidx.compose.remote.creation.compose.SCREENSHOT_GOLDEN_DIRECTORY.
How to use RemoteScreenshotTestRule
1. Basic Usage (Direct Testing)
Use runScreenshotTest and provide a lambda with the Remote Composable content you want to test.
@Test
fun simpleTest() {
composeTestRule.runScreenshotTest {
RemoteBox(
modifier = RemoteModifier.fillMaxSize().background(Color.Red)
)
}
}
2. Overriding Configuration
You can override profile, layout direction, or offer outer content if needed.
@Test
fun alignByBaseline() {
composeTestRule.runScreenshotTest(profile = TestProfiles.androidXExperimental) {
RemoteColumn(modifier = RemoteModifier.fillMaxSize()) {
RemoteRow(modifier = RemoteModifier.fillMaxWidth()) {
RemoteText(
text = "Large String",
fontSize = 40.rsp,
modifier = RemoteModifier.alignByBaseline(),
)
RemoteText(
text = "Small String",
fontSize = 14.rsp,
modifier = RemoteModifier.alignByBaseline(),
)
}
}
}
}
3. Grid Testing (Optional)
For testing multiple variations efficiently, you can combine this rule with GridScreenshotUI.
Refer to the build_grid_screenshot_tests skill for detailed instructions on using the grid utility.
Best Practices
- Thresholds: Use
MSSIMMatcher(threshold = 0.999)for high-precision matching. - Golden Directory: Ensure
moduleDirectorypoints to the correct golden assets folder. - Remote Scope: Inside the
runScreenshotTestlambda, you are in a@RemoteComposable @Composablescope. Make sure to useRemoteModifierand Remote components (e.g.RemoteBox,RemoteText).