Screengrab (Fastlane) — What It Is, Features, and Screenshot Automation

What Is Screengrab and Why You Need It

Screengrab is a component of the Fastlane ecosystem designed for automated screenshot creation for mobile apps. The tool appeared in 2015 as a response to the problem: publishing to Google Play and App Store requires 4 to 10 screenshots per language. With support for 30 languages, that’s 120–300 manual captures.

The Problem of Manual Screenshot Creation

A developer manually launches the app on a simulator or device, swipes to the desired screen, takes a screenshot, transfers it to the computer, crops it, and saves it to the correct folder. The procedure repeats for each language and each orientation. According to Google Play Console, the average app updates every two weeks, turning screenshots into a regular routine.

Advantages of Automation

Screengrab solves the problem radically: the developer describes test scenarios using a UI framework (Espresso for Android, XCTest for iOS), and Screengrab runs them on all required devices and languages automatically. Fastlane coordinates the process: builds the app, runs tests, collects screenshots, and packages them into the required folder structure.

The result — a hundred screenshots in 10–15 minutes instead of several hours of manual work. Google recommends updating screenshots with every significant UI change, and without automation this advice is often ignored.

How Screengrab Works: Architecture and Operation Principle

Architecture of Screengrab is built around two key components: a client on the device (screengrab-lib) and a runner that manages test execution and result collection. On Android, it uses the instrumented test framework; on iOS — XCTest.

Lifecycle of a Single Run

Fastlane calls the screengrab action, which reads the Screengrabfile configuration file. The runner builds the test APK with the screengrab-lib library connected, installs it on connected devices or emulators, and runs UI tests marked with annotations for screenshots.

# Fastfile — lane description for screenshots
lane :screenshots do
  capture_android_screenshots(
    output_directory: "fastlane/metadata/android/screenshots",
    locales: ["ru-RU", "en-US", "de-DE"],
    devices: ["pixel_6", "pixel_tablet"],
    use_tests_external_storage: true
  )
end

Output File Structure

Screengrab creates a folder hierarchy: language → device → screenshots. The structure fully matches the requirements of Google Play Console and App Store Connect. App Store requires strictly defined sizes for each device type, and Screengrab generates captures exactly to the specifications.

Multi-Device Support

The tool can run tests in parallel on all connected devices and emulators. Android emulators start automatically if they are not active. For iOS, Screengrab uses Xcode simulators.

Installing and Configuring Screengrab for Android

Installing Screengrab consists of two parts: adding the library to the project and configuring the configuration file. On Android, the Espresso UI framework and the screengrab-lib library from the Fastlane repository are required.

Adding Dependencies

In the app module’s build.gradle, the screengrab-lib dependency is added. The library provides the ScreenCapturer class, which takes a screenshot at the moment of the call.

// build.gradle (module: app)
androidTestImplementation(
  'tools.fastlane:screengrab-lib:2.1.0'
)

Writing a Test with Screenshots

A UI test is marked with the Screengrab.screenshot() annotation at the required points. Each call captures the current screen and saves it with the specified name.

import tools.fastlane.screengrab.Screengrab
import tools.fastlane.screengrab.locale.LocaleTestRule

class ScreenshotTest {

    @get:Rule
    val localeTestRule = LocaleTestRule()

    @Test
    fun testTakeScreenshots() {
        Screengrab.screenshot("main_screen")
        // Actions: tap the login button
        Screengrab.screenshot("login_screen")
    }
}

Screengrabfile Configuration

The Screengrabfile stores launch parameters: device list, languages, timeouts, and save path. The file is typically located in the fastlane folder next to the Fastfile.

Screenshot Localization and Multiple Languages

Localization is the key feature of Screengrab, and the main reason it is most often chosen. The tool automatically switches the app language before each test run and takes screenshots in all specified languages.

Language Configuration

Languages are set in the Screengrabfile using the locales parameter. For each language, Screengrab reinstalls the app with the corresponding resources and runs the full test cycle. LocaleTestRule on Android automatically switches the device locale.

# Screengrabfile
locales [
  "ru-RU",
  "en-US",
  "de-DE",
  "fr-FR",
  "es-ES",
  "ja-JP",
  "ko-KR"
]

Folder Structure for Localized Screenshots

Screengrab creates directories following the scheme: screenshots/{locale}/{device_name}/{screenshot_name}.png. This structure directly matches Google Play requirements, allowing screenshots to be uploaded via Fastlane deliver with a single command.

For iOS, App Store Connect expects screenshots in a flat structure by language. Fastlane automatically converts the Screengrab hierarchy into the required format when publishing.

Integrating Screengrab into a CI/CD Pipeline

CI/CD integration is one of the main advantages of Screengrab. The tool runs from the command line and requires no graphical interface, making it ideal for server builds.

GitHub Actions

In a CI environment, you need to launch an Android emulator or iOS simulator, then call the lane with screenshots. GitHub Actions supports AVD caching, which speeds up repeated runs.

Parameters for CI

In CI configuration, it is important to consider memory and time constraints. Android emulators require at least 2 GB of RAM per device, and a full run on 7 languages and 2 devices takes 20–40 minutes.

# Fastfile — lane for CI with timeouts
lane :ci_screenshots do
  capture_android_screenshots(
    locales: ["en-US", "ru-RU"],
    devices: ["pixel_6"],
    clear_previous_screenshots: true,
    tests_timeout: "600",
    output_directory: "screenshots/ci"
  )
end

Jenkins Pipeline

For Jenkins, the sh step with a call to bundle exec fastlane is used. It is recommended to run screenshots at night or by trigger after merging into the main branch to avoid slowing down the development cycle.

Screengrab vs Alternatives: Tool Comparison

Screengrab is not the only tool for screenshot automation. There are alternatives with different approaches: built-in OS tools, commercial platforms, and in-code screenshot libraries.

ADB Shell gives full control but requires writing scripts for each scenario. XCTest is built into Xcode but does not manage localization automatically. Firebase Test Lab runs tests on real devices in the cloud, giving maximum coverage, but charges per minute.

Screengrab wins due to the combination: Fastlane manages the entire build lifecycle — from compilation to publishing. Google Play directly accepts the Screengrab folder structure via Fastlane deliver.

Common Problems and Their Solutions

When working with Screengrab, developers most often encounter several recurring issues. Knowing common errors reduces debugging time on the first run.

Screenshots Are Empty or Black

The problem occurs when Screengrab takes a screenshot before screen rendering completes. The solution is to add a Thread.sleep() delay before calling screenshot() or use Espresso’s IdlingResource to wait for asynchronous operations.

Version Compatibility Error

The screengrab-lib version must match the Fastlane version. Fastlane is updated monthly, and an old library may not support new configuration parameters. The solution is to synchronize versions via Gemfile and gradle.properties.

Long Run Time on CI

Running on 30 languages on 5 devices can take over an hour. The solution is to split runs: one for the store on all languages, another for internal needs on two languages. GitHub Actions allows using matrix strategies for parallel runs.

Emulator Issues on CI

The Android emulator requires hardware virtualization, which is not always available on CI servers. KVM must be enabled, otherwise the emulator does not start. The solution is to use x86 images without GPU acceleration or Firebase Test Lab.