OpenParable
Skip to content
← Back to skills

Build Screenshot Tests

Testing & Quality
build_screenshot_tests

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

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/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 RemoteScreenshotTestRule for all tests. If the user asks you to write a screenshot test, you MUST first explicitly ask them: "Would you like me to use the RemoteScreenshotTestRule for 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:

  1. Capturing the remote document.
  2. Rendering it using RemoteDocumentPlayer.
  3. Verifying the rendered image against a "golden" screenshot.

Setup

  1. Test Class Annotations: Annotate the test class with @MediumTest, @SdkSuppress(minSdkVersion = 35, maxSdkVersion = 35), and @RunWith(AndroidJUnit4::class).

  2. 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_DIRECTORY is 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 moduleDirectory points to the correct golden assets folder.
  • Remote Scope: Inside the runScreenshotTest lambda, you are in a @RemoteComposable @Composable scope. Make sure to use RemoteModifier and Remote components (e.g. RemoteBox, RemoteText).