How dropbox/dropshots works
Project type and purpose
• This is an Android-focused open-source library plus accompanying Gradle plugin (“Dropshots”) for on-device screenshot testing. It has three main modules:
• dropshots-gradle-plugin (a Kotlin Gradle plugin)
• dropshots (the runtime Android library, including instrumentation tests and reference images)
• sample/app (an example Android application illustrating usage)
File structure
• Top-level: build scripts (build.gradle.kts, settings.gradle.kts, gradle wrapper), CI/deploy workflows under .github, plugin folder, library folder, sample folder.
• dropshots-gradle-plugin: implements custom Plugin, Extension, and Tasks (PushFile, PullScreenshots, ClearScreenshots).
• dropshots (runtime): contains Android code under src/main (BitmapImage, Dropshots rule, ResultValidator), instrumentation tests under src/androidTest, screenshot assets under src/androidTest/assets/static.
• sample/app: a consumer Android app that depends on both the Android plugin and runtime library to show how to write screenshot tests.
Key architecture notes from README
• The Gradle plugin injects tasks into the build (e.g., recordDebugAndroidTestScreenshots) that push reference images to the device, invoke connectedAndroidTest, and pull diffs back.
• The runtime library provides a JUnit TestRule (Dropshots) that captures views or activities, compares screenshots on-device, and writes results to the test report folder.
Main components & their interactions
A. Gradle Build System (Gradle daemon + Kotlin DSL)
– reads build.gradle.kts of each module
– applies com.android.application/library + com.dropbox.dropshots plugin
B. Dropshots Gradle Plugin
– Applies to Android modules
– On configuration: registers DropshotsExtension (configurable thresholds, paths)
– On evaluation: creates tasks
• record<Variant>Screenshots → runs instrumentation tests on an emulator/emulator with reference images pushed
• pullScreenshots → after tests, fetches actual/diff images
• clearScreenshots → cleans generated images
– Hooks into the test task graph (connectedAndroidTest)
C. Android Device / Emulator
– Receives reference screenshots (from version-controlled src/androidTest/screenshots) via ADB push
– Runs instrumentation tests (Dropshots.assertSnapshot)
– Captures actual screenshots on device and runs comparison
– Writes pass/fail images and diffs back to host via ADB pull
D. Dropshots Runtime Library
– Exposes a JUnit TestRule Dropshots()
– Uses AndroidX Test APIs + ActivityScenarioRule
– Captures bitmaps of Views/Activities (BitmapImage.kt)
– Compares against reference images using an ImageComparator + ResultValidator
E. Reference Images Storage
– Committed under src/androidTest/screenshots in each module
– Managed by the plugin’s record tasks
F. CI / Publishing
– .github/workflows/publish.yml publishes plugin artifacts to Maven Central
– dependabot.yaml for dependency updates
Architectural patterns & design principles
• Separation of concerns: build‐time logic in Gradle plugin vs. runtime logic in Android library
• Plugin-extension–task pattern (Gradle’s canonical model)
• TestRule pattern for integration with JUnit instrumentation tests
• Decoupling of screenshot management (push/pull tasks) from test assertions (Dropshots rule)
Diagramming recommendations
• From Gradle → Plugin → Tasks → Device
• From Device → Gradle/Host (for results)
• Build time (plugin tasks) in blue
• Runtime (library + device) in green
• CI/CD & artifact repo in gray