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

- Skill name: `build_grid_screenshot_tests`
- Category: [Testing & Quality](https://www.openparable.com/skill/testing-quality/1)
- Source: https://github.com/androidx/androidx/blob/HEAD/compose/remote/remote-creation-compose/.agents/skills/grid_screenshot_testing/SKILL.md
- Repository: androidx/androidx (6,038 GitHub stars when collected)

## SKILL.md

# 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.
   ```kotlin
   @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.
   ```kotlin
   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.
   ```kotlin
   @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`.
  ```kotlin
  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`).
  ```kotlin
  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()
  ```

---

Source: https://www.openparable.com/skill/testing-quality/build-grid-screenshot-tests (OpenParable). Cite the canonical URL above.
