diff --git a/docs/docs/recipes/20-gmd.md b/docs/docs/recipes/20-gmd.md new file mode 100644 index 00000000..26ad5486 --- /dev/null +++ b/docs/docs/recipes/20-gmd.md @@ -0,0 +1,104 @@ +import OpenNew from '@site/static/img/open_new.svg'; + +# Configuring Testify to run on Gradle managed device + +Starting from API levels +27 [Android Gradle Plugin allows you to configure virtual test devices in your project's Gradle files ](https://developer.android.com/studio/test/gradle-managed-devices). +This feature improves testing experience by delegating the task of starting, shutting down and +managing emulator to the Gradle. + +When using Gradle managed device user must +use [Test storage service ](https://developer.android.com/reference/androidx/test/services/storage/TestStorage) +to save screenshots. Using this service Android Gradle Plugin would be able to save test output +including screenshots and diffs to the `build` folder + +### Adding Gradle managed device configuration to build file + +To create new Gradle managed device add it's definition to the `build.gradle` file: + +```groovy + +android { + testOptions { + managedDevices { + devices { + NAME_OF_THE_DEVICE(com.android.build.api.dsl.ManagedVirtualDevice) { + device = "Pixel 2" + apiLevel = 30 + systemImageSource = "aosp" + } + } + } + } +} + +``` + +In order to receive screenshots after test execution enable `TestStorageService`: + +```groovy + +android { + defaultConfig { + testInstrumentationRunnerArguments useTestStorageService: "true" + } +} + +dependencies { + androidTestUtil("androidx.test.services:test-services:1.4.2") +} +``` + +With that changes applied couple of new Gradle tasks should be added to your project. Suppose, you +named your device `tester`, then `testerCheck` and `testDebugAndroidTest` tasks should be added to +your project. + +### Configuring the Testify library + +You also need to instruct Testify to use Test storage to store screenshots and diffs. This could be +done using Testify plugin configuration: + +```groovy +testify { + useTestStorage = true +} +``` + +### Running screenshot tests + +To perform screenshot test verification run any of the new Gradle tasks, for +example `./gradlew testerDebugAndroidTest`. + +Because we need to run specific Gradle task to execute our tests using Gradle managed device, we +cannot use `screenshotPull` task. When execution completed go to the +module's `build/outputs/managed_device_android_test_additional_output/tester` folder to get recorded +screenshots or diffs. + +### Updating baselines + +Because we need to run specific Gradle task to execute our tests using Gradle managed device, we +cannot use `screenshotRecord` task. In order to generate new baseline apply necessary setting to +the `ScreenshotRule`: + +```kotlin +@get:Rule +var rule = ScreenshotRule(ClientListActivity::class.java) + +@ScreenshotInstrumentation +@Test +fun testMissingBaseline() { + rule + .setRecordModeEnabled(true) + .assertSame() +} +``` + +Again we cannot use `screenshotPull` task. When execution completed go to the +module's `build/outputs/managed_device_android_test_additional_output/tester` and copy recorded +baseline into folder named after your device configuration inside `androidTest/assets/screenshots/` +directory, for example: `androidTest/assets/screenshots/30-1080x1920@420dp-en_US` + +### Sample + +Please check +provided [sample ](https://github.com/ndtp/android-testify/tree/main/Samples/Gmd). \ No newline at end of file