Build Grid Screenshot Tests
Testing & Qualitybuild_grid_screenshot_testsBuild Grid 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 tests in Remote Compose using GridScreenshotUI.
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/grid_screenshot_testing/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/build-grid-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 Instrumented Tests using GridScreenshotUI
[!IMPORTANT] AI INSTRUCTION: Do not assume you should use
GridScreenshotUIfor all tests in this directory. If the user asks you to write a screenshot test, you MUST first explicitly ask them: "Would you like me to use theGridScreenshotUIutility for this test?" Proceed with using this skill only if they confirm.
This skill provides guidelines for building screenshot tests using GridScreenshotUI in the @compose/remote/remote-creation-compose project.
Purpose
GridScreenshotUI is a utility class designed to lay out multiple small remote UI components in a grid. This is particularly useful for screenshot testing as it allows you to capture many variations of a component (e.g., different alignments, modifiers, or arrangements) in a single screenshot, making tests more efficient and easier to compare visually.
How to use GridScreenshotUI
-
Test Class Setup: Create a test class annotated with
@MediumTest,@SdkSuppress(minSdkVersion = 35, maxSdkVersion = 35), and@RunWith(AndroidJUnit4::class). -
Add the Screenshot Rule: Define a
RemoteScreenshotTestRuleexplicitly specifying the module directory and matcher.@get:Rule val composeTestRule: RemoteScreenshotTestRule by lazy { RemoteScreenshotTestRule( moduleDirectory = SCREENSHOT_GOLDEN_DIRECTORY, context = ApplicationProvider.getApplicationContext(), matcher = MSSIMMatcher(threshold = 0.999), ) } -
Instantiate GridScreenshotUI: Create an instance of
GridScreenshotUIin your test class.private val gridScreenshotUI = GridScreenshotUI() -
Define your UI variations: Create a method or variable that provides a list of
Pair<String, @RemoteComposable @Composable () -> Unit>. The string is the label for the variation, and the lambda is the actual Compose UI content. You can use the.toInput()extension functions defined inGridScreenshotUI.Companionto easily convert a list of composables into the required pair format if you don't want to specify labels manually. -
Write the Test: Use
composeTestRule.runScreenshotTestand callgridScreenshotUI.GridContent(...)with your list of variations.@Test fun exampleGridTest() = composeTestRule.runScreenshotTest { gridScreenshotUI.GridContent(getLayoutAlignmentUIs()) }
Best Practices
- Reuse Dimensions: Use
GridScreenshotUI.Companion.DefaultContainerSizeto maintain consistent container dimensions across tests. - RTL Testing: You can easily test RTL (Right-to-Left) layouts by passing
layoutDirection = LayoutDirection.RtltoGridContent.gridScreenshotUI.GridContent( getLayoutAlignmentUIs(), layoutDirection = LayoutDirection.Rtl, ) - Helper methods: Create builder methods to generate the list of
Pairitems if you have a combinatorial explosion of parameters (like trying out all combinations ofArrangementsandAlignmentsthroughsequence).private fun getLayoutAlignmentUIs(): List<Pair<String, @RemoteComposable @Composable () -> Unit>> = sequence { for (alignment in alignments) { for (arrangement in arrangements) { yield( "${alignment.propertyName()} ${arrangement.propertyName()}" to @RemoteComposable @Composable { RemoteRow( modifier = RemoteModifier.size(DefaultContainerSize), horizontalArrangement = arrangement, verticalAlignment = alignment, ) { // Your content here } } ) } } }.toList()