fastlane screenshots for Android

Your app screenshots are probably the most important thing when it comes to convincing potential users to download or purchase your app. Unfortunately, many apps don't do screenshots well. This is often because taking screenshots of your app and then preparing them for display is time consuming, and it's hard to get everything right and consistent! For example:

  • Are the screenshots in Google Play inconsistent with your latest app design?
  • Is your app localized into many languages that require different screenshots for each?
  • Is the same content displayed for each of your size variations?

fastlane tools can automate this process, making it fast and consistent while giving you beautiful results!

running screengrab

Capture Screenshots Automatically

screengrab works with fastlane to automate the process of capturing screenshots of your app. It allows you to:

  • Capture hundreds of screenshots in multiple languages on any simulator
  • Do something else while the computer takes the screenshots for you
  • Configure it once, and store the configuration so anyone on the team can run it
  • Get a summary of how your app looks like across all supported devices and languages

After screengrab completes, it will show you summary of the screenshots you captured:

screengrab results

Getting Started Using Espresso

screengrab uses the capabilities of Android's built-in Instrumented tests combined with Espresso to drive interactions with your app. To get familiar with writing UI Tests with Espresso, check out Testing UI for a Single App.

Installing screengrab

Install the gem:

sudo gem install screengrab

Gradle dependency

Add the test dependency to your Gradle build:

androidTestCompile 'tools.fastlane:screengrab:x.x.x'

The latest version can be determined by visiting the screengrab RubyGems page

Configuring your Manifest Permissions

Ensure that the following permissions exist in your src/debug/AndroidManifest.xml

<!-- Allows unlocking your device and activating its screen so UI tests can succeed -->
<uses-permission android:name="android.permission.DISABLE_KEYGUARD"/>
<uses-permission android:name="android.permission.WAKE_LOCK"/>

<!-- Allows for storing and retrieving screenshots -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

<!-- Allows changing locales -->
<uses-permission android:name="android.permission.CHANGE_CONFIGURATION" />

Configuring your UI Tests for screengrab

  1. Add @ClassRule public static final LocaleTestRule localeTestRule = new LocaleTestRule(); to your tests class to handle automatic switching of locales
  2. To capture screenshots, add the following to your tests Screengrab.screenshot("name_of_screenshot_here"); on the appropriate screens

Generating Screenshots with Screengrab

  • Run ./gradlew assembleDebug assembleAndroidTest to generate debug and test APKs
  • Run fastlane screengrab in your app project directory to generate screenshots
    • You will be prompted to provide any required parameters which are not in your Screengrabfile, or provided as command line arguments
  • Your screenshots will be saved to fastlane/metadata/android in the directory where you ran fastlane screengrab

Improved screenshot capture with UI Automator

As of screengrab 0.5.0, you can specify different strategies to control the way screengrab captures screenshots. The newer strategy delegates to UI Automator which fixes a number of problems compared to the original strategy:

  • Shadows/elevation are correctly captured for Material UI
  • Multi-window situations are correctly captured (dialogs, etc.)
  • Works on Android N

However, UI Automator requires a device with API level >= 18, so it is not yet the default strategy. To enable it for all screenshots by default, make the following call before your tests run:

Screengrab.setDefaultScreenshotStrategy(new UiAutomatorScreenshotStrategy());

Upload Screenshots to Google Play

After generating your screenshots using fastlane screengrab, you'll usually want to upload them to Google Play.

To upload the screenshots stored in fastlane/metadata/android, just run:

fastlane supply

Use in Fastfile

To put all of this together so that anyone on your team could trigger generating and uploading new screenshots, you can define a fastlane lane called screenshots. It would be responsible for:

  1. Running your app through screengrab to automatically capture your screenshots
  2. Having supply send your screenshots to Google Play for use in the store

Add the following code to your fastlane/Fastfile:

lane :screenshots do

To get a list of all available options for each of the steps, run

fastlane action screengrab
fastlane action supply

Advanced screengrab

Launch Arguments

You can provide additional arguments to your testcases on launch. These strings will be available in your tests through InstrumentationRegistry.getArguments().

  "username hjanuschka",
  "build_number 201"
Bundle extras = InstrumentationRegistry.getArguments();
String peerID = null;
if (extras != null) {
  if (extras.containsKey("username")) {
    username = extras.getString("username");
    System.out.println("Username: " + username);
  } else {
    System.out.println("No username in extras");
} else {
  System.out.println("No extras");