Shot

🔝 Top sponsors 🔝

Shot is an Android project you can use to write screenshot for your apps in a simple and friendly way.

What is this?

Shot is a Gradle plugin and a core android library thought to run screenshot tests for Android. This project provides a handy interface named ScreenshotTest and a ready to use ShotTestRunner you can use in order to write tests like these:

class GreetingScreenshotTest : ScreenshotTest {

    // If you are using regular Android views

    @Test
    fun theActivityIsShownProperly() {
        val mainActivity = startMainActivity()

        compareScreenshot(activity)
    }

    // If you are using Jetpack Compose

    @Test
    fun rendersGreetingMessageForTheSpecifiedPerson() {
        composeRule.setContent { Greeting(greeting) }

        compareScreenshot(composeRule)
    }
}

Since Shot 5.0.0 we provide screenshot testing support for Jetpack Compose. If you are testing your components using Shot we strongly recommend you to configure your emulator using the gpu mode swiftshader_indirect. This will help you to avoid rendering issues when verifying your screenshots from any CI environment.

Record your screenshots executing ./gradlew executeScreenshotTests -Precord

And verify your tests executing ./gradlew executeScreenshotTests

If Shot finds any error in your tests execution the Gradle plugin will show a report as follows:

You can find the complete Facebook SDK documentation here.

Getting started

Setup the Gradle plugin:

Modify your root build.gradle file:

  buildscript {
    // ...
    dependencies {
      // ...
      classpath 'com.karumi:shot:<LATEST_RELEASE>'
    }
  }

Apply the plugin from any of the modules configured in your project. In a simple Android app your app/build.gradle file:

apply plugin: 'shot'

You will also have to configure the instrumentation test runner in your module build.gradle file as follows:

android {
    // ...
    defaultConfig {
        // ...
        testInstrumentationRunner "com.karumi.shot.ShotTestRunner"
    }
    // ...

We created this test runner for you extending from the Android one.

This plugin sets up a few convenience commands you can list executing ./gradlew tasks and reviewing the Shot associated tasks:

If you are using flavors the available Shot gradle tasks will be configured based on your flavors and build types configuration. You can find all the available shot tasks by executing ./gradlew tasks. For example, if your app has two flavors: green and blue the list of available Shot tasks will be:

executeScreenshotTests - Checks the user interface screenshot tests. If you execute this task using -Precord param the screenshot will be regenerated.
blueDebugDownloadScreenshots - Retrieves the screenshots stored into the Android device where the tests were executed for the build BlueDebug
blueDebugExecuteScreenshotTests - Records the user interface tests screenshots. If you execute this task using -Precord param the screenshot will be regenerated for the build BlueDebug
blueDebugRemoveScreenshotsBefore - Removes the screenshots recorded before the tests execution from the Android device where the tests were executed for the build BlueDebug
blueDebugRemoveScreenshotsAfter - Removes the screenshots recorded after the tests execution from the Android device where the tests were executed for the build BlueDebug
greenDebugDownloadScreenshots - Retrieves the screenshots stored into the Android device where the tests were executed for the build GreenDebug
greenDebugExecuteScreenshotTests - Records the user interface tests screenshots. If you execute this task using -Precord param the screenshot will be regenerated for the build GreenDebug
greenDebugRemoveScreenshotsBefore - Removes the screenshots recorded before the tests execution from the Android device where the tests were executed for the build GreenDebug
greenDebugRemoveScreenshotsAfter - Removes the screenshots recorded after the tests execution from the Android device where the tests were executed for the build GreenDebug

You can specify a directory suffix where screenshot & report will be saved ({FLAVOR}/{BUILD_TYPE}/{DIRECTORY_SUFFIX}) :
./gradlew executeScreenshotTests -PdirectorySuffix=Api26

If for some reason you are running your tests on a different machine and you want to skip the instrumentation tests execution and just compare the sources remember you can use the following shot configuration:

  shot {
    runInstrumentation = false
  }

Create this AndroidManifest.xml file inside your androidTest folder.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="<YOUR_APP_ID>.test"
    android:sharedUserId="<YOUR_APP_ID>.uid">

</manifest>

You'll have to add the same android:sharedUserId="<YOUR_APP_ID>.uid" configuration to your app/AndroidManfiest.xml file in order to let the testing APK write into the SDCard.. If you don't do this, you can end up facing a weird error with this message while running your tests:

java.lang.RuntimeException: Failed to create the directory /sdcard/screenshots/com.example.snapshottesting.test/screenshots-default for screenshots. Is your sdcard directory read-only?

If you want to use Shot to test your Android libraries code, you will have to configure the testApplicationId parameter as follows

android {
    // ...
    defaultConfig {
        // ...
        testApplicationId "<MY_TEST_APPLICATION_ID>"
    }
    // ...

If you are using AGP 7.X in your Android library you may need to configure the applicationId as part of the Shot extension configuration as follows:

shot {
  applicationId = "com.myapp"
}

AGP introduced a bug in 7.0.1-alpha4 we are not able to fix without this workaround for now. In the future, once AGP fixes the bug, we will remove this extension property.

Be careful and do not use the same id you are using for any other of the installed apps.

Now you are ready to use the ScreenshotTest interface from your tests:

class MyActivityTest: ScreenshotTest {
    @Test
    fun theActivityIsShownProperly() {
            val mainActivity = startMainActivity();
           /*
             * Take the actual screenshot. At the end of this call, the screenshot
             * is stored on the device and the gradle plugin takes care of
             * pulling it and displaying it to you in nice ways.
             */
            compareScreenshot(activity);
    }
}

Since Shot 5.0.0, if you are using Jetpack Compose your tests will look like this:

class GreetingScreenshotTest : ScreenshotTest {

    @Test
    fun rendersGreetingMessageForTheSpecifiedPerson() {
        composeRule.setContent { Greeting(greeting) }

        compareScreenshot(composeRule)
    }

This interface is full of useful methods you can use to take your screenshots with your activities, dialogs fragments, view holders or even custom views

You can find a complete example in this repository under the folder named shot-consumer or review this kata.***

Now you are ready to record and verify your screenshot tests!

Using shot on API 28+

If you want to use Shot on devices running API >= 28, you will have to enable access to non-SDK interfaces.
Execute the following commands:

For Android 9 (API level 28)

adb shell settings put global hidden_api_policy_pre_p_apps 1
adb shell settings put global hidden_api_policy_p_apps 1

For Android 10 (API level 29) or higher

adb shell settings put global hidden_api_policy 1

Recording tests

You can record your screenshot tests executing this command:

./gradlew <Flavor><BuildType>ExecuteScreenshotTests -Precord

or

./gradlew executeScreenshotTests -Precord

This will execute all your integration tests and it will pull all the generated screenshots into your repository so you can easily add them to the version control system.

Executing tests

Once you have a bunch of screenshot tests recorded you can easily verify if the behaviour of your app is the correct one executing this command:

./gradlew <Flavor><BuildType>ExecuteScreenshotTests

or

./gradlew executeScreenshotTests

After executing your screenshot tests using the Gradle task <Flavor><BuildType>ExecuteScreenshotTests a report with all your screenshots will be generated.

ScreenshotTest interface

ScreenshotTest interface has been designed to simplify the usage of the library. These are the features you can use:

• Take a screenshot of any activity by using compareScreenshot(activity). Activity height, width, background color and screenshot name are configurable.
• Take a screenshot of any fragment by using compareScreenshot(fragment). Fragment height, width and screenshot name are configurable.
• Take a screenshot of any dialog by using compareScreenshot(dialog). Dialog height, width and screenshot name are configu