OpenParable
Skip to content
← Back to skills

Build Grid Screenshot Tests

Testing & Quality
build_grid_screenshot_tests

Build 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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 GridScreenshotUI for 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 the GridScreenshotUI utility 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

  1. Test Class Setup: Create a test class annotated with @MediumTest, @SdkSuppress(minSdkVersion = 35, maxSdkVersion = 35), and @RunWith(AndroidJUnit4::class).

  2. Add the Screenshot Rule: Define a RemoteScreenshotTestRule explicitly 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),
        )
    }
    
  3. Instantiate GridScreenshotUI: Create an instance of GridScreenshotUI in your test class.

    private val gridScreenshotUI = GridScreenshotUI()
    
  4. 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 in GridScreenshotUI.Companion to easily convert a list of composables into the required pair format if you don't want to specify labels manually.

  5. Write the Test: Use composeTestRule.runScreenshotTest and call gridScreenshotUI.GridContent(...) with your list of variations.

    @Test
    fun exampleGridTest() =
        composeTestRule.runScreenshotTest {
            gridScreenshotUI.GridContent(getLayoutAlignmentUIs())
        }
    

Best Practices

  • Reuse Dimensions: Use GridScreenshotUI.Companion.DefaultContainerSize to maintain consistent container dimensions across tests.
  • RTL Testing: You can easily test RTL (Right-to-Left) layouts by passing layoutDirection = LayoutDirection.Rtl to GridContent.
    gridScreenshotUI.GridContent(
        getLayoutAlignmentUIs(),
        layoutDirection = LayoutDirection.Rtl,
    )
    
  • Helper methods: Create builder methods to generate the list of Pair items if you have a combinatorial explosion of parameters (like trying out all combinations of Arrangements and Alignments through sequence).
    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()