Testify — Android Screenshot Testing

Add screenshots to your Android tests

Expand your test coverage by including the View-layer. Testify allows you to easily set up a variety of screenshot tests in your application. Capturing a screenshot of your view gives you a new tool for monitoring the quality of your UI experience. It's also an easy way to review changes to your UI. Once you've established a comprehensive set of screenshots for your application, you can use them as a "visual dictionary". In this case, a picture really is worth a thousand words; it's easy to catch unintended changes in your view rendering by watching for differences in your captured images.

Testify screenshot tests are built on top of Android Instrumentation tests and so integrate seamlessly with your existing test suites. You can run tests and capture screenshots from within Android Studio or using the Gradle command-line tools. Testify also works well with most Continuous Integration services.

You can easily capture screenshots with different resolutions, orientations, API versions, and languages by simply configuring different emulators. Testify natively supports grouping screenshot tests by device characteristics. Testify captures a bitmap of your specified View after all layout and draw calls have been completed so you know that you're capturing an authentic rendering representative of what your users will see in your final product.

Warning

The Testify 2.0 platform requires new build artifacts and a migration from the com.shopify.testify package to the new dev.testify package.

Please refer to the migration guide for more information

Getting Started

📷 Visit testify.dev for full documentation, blogs, and code recipes to help you get started with Android Testify! 📷

Testify.dev is the go-to resource for everything related to Android Testify. There, you'll find comprehensive documentation, tutorials, and code recipes that will help you write better tests for your Android apps.

By visiting testify.dev, you'll learn how to:

Write reliable and maintainable UI tests for your Android apps
Improve your test coverage and reduce flakiness
Save time and improve productivity with Testify's powerful APIs and tools
Get help and support from the Android Testify community

Click the link above and start your journey to better Android testing today!

Set up Testify

Before building your screenshot test with Testify, make sure to set a dependency reference to the Testify plugin:

Root build.gradle

plugins {
    id("dev.testify") version "3.2.0" apply false
}

settings.gradle

Ensure that mavenCentral() is available to both pluginManagement and dependencyResolutionManagement.

Application build.gradle

plugins {
    id("dev.testify")
}

dependencies {
    androidTestImplementation "androidx.test:rules:1.5.0"
}

Device Configuration

It is required for you to turn off animations on your test device — leaving system animations turned on in the test device might cause synchronization issues which may lead your test to fail. Turn off animations from Settings by opening Developer options and turning all the following options off:

Window animation scale
Transition animation scale
Animator duration scale

You can find a recommended emulator configuration here .

Android Studio Plugin

Testify screenshot tests are built on top of Android Instrumentation tests and so already integrate seamlessly with existing test suites. Screenshots can be captured directly from within Android Studio or using the Gradle command-line tools.

Android Studio support relies on the fact that Testify tests extend ActivityTestRule and can be invoked using the built-in support for running instrumentation tests with various commands (notably sidebar icons) in Android Studio. With the installation of the Intellij-platform plugin, many common Testify actions can be seamlessly integrated into your IDE. The Testify Android Studio plugin is available for Android Studio Flamingo 222.+ and greater via the Intellij Marketplace.

This plugin will enhance the developer experience by adding fully integrated IDE UI for all relevant Testify commands:

With the installation of an Intellij-platform plugin, many common Testify actions can be seamlessly integrated into your IDE. The Testify Android Studio plugin is available for Android Studio version Flamingo and greater via the Intellij Marketplace.

Run the Testify screenshot tests
Record a new baseline image
Pull screenshots from the device and into your project
Remove any existing screenshot test images from the device
Reveal the baseline image in Android Studio
Delete the baseline image from your project

Write a test

Testify is a subclass of Android's ActivityTestRule . The testing framework launches the activity under test before each test method annotated with @Test and before any method annotated with @Before.

Each screenshot test method must be annotated with the @ScreenshotInstrumentation annotation.

Within your test method, you can configure the Activity as needed and call assertSame() to capture and validate your UI. The framework handles shutting down the activity after the test finishes and all methods annotated with @After are run.

@RunWith(AndroidJUnit4::class)
class MainActivityScreenshotTest {

    @get:Rule val rule = ScreenshotRule(MainActivity::class.java)

    @ScreenshotInstrumentation
    @Test
    fun default() {
        rule.assertSame()
    }
}

For additional testing scenarios, please refer to the recipe book.

Update your baseline

Testify works by referencing a PNG baseline found in your androidTest/assets directory for each test case that you write. As you write and run tests, an updated baseline image is maintained on your device or emulator. In order to update the baseline, you need to copy or pull the image from the device to your local development environment. Testify offers a variety of Gradle tasks to simplify the copying of your baseline images.

Record a new baseline

Run all the screenshot tests in your app and update the local baseline.

./gradlew screenshotRecord

Verify the tests

Run all the screenshot tests in your app and fail if any differences from the baseline are detected.

./gradlew screenshotTest

Pull images from the device

Copy images from the app_images directory on your emulator to your local androidTest/assets directory.

./gradlew screenshotPull

Erase any existing images from the device

Clear any baseline images that may be remaining on your emulator.

./gradlew screenshotClear

Generate a YAML test report

You can optionally generate a YAML test report for offline parsing by adding <meta-data android:name="testify-reporter" android:value="true" /> to your AndroidManifest.xml. Once enabled, Testify will create a report.yml cataloging the statistics about the most recent test run. You can view the report with:

./gradlew reportShow

You can copy the report.yml file to your local project directory with:

./gradlew reportPull

There are a variety of additional Gradle commands available through the Testify plugin. For advance usage, please refer to the Plugin guide.

License

MIT License

Modified work copyright (c) 2022-2024 ndtp
Original work copyright (c) 2021 Shopify

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

ndtp/android-testify