# dropbox/dropshots architecture

> Architecture diagram of the GitHub repository dropbox/dropshots, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dropbox/dropshots
- Repository: https://github.com/dropbox/dropshots

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build-Time Layer
    subgraph "Build-Time Layer"
        direction TB
        Gradle["Gradle Build System\n(Kotlin DSL)"]:::buildtime
        Plugin["Dropshots Gradle Plugin"]:::buildtime
        subgraph "Plugin Tasks"
            direction TB
            Record["record<Variant>Screenshots\nTask"]:::buildtime
            Pull["pullScreenshots\nTask"]:::buildtime
            Clear["clearScreenshots\nTask"]:::buildtime
        end
    end

    %% Runtime Layer
    subgraph "Runtime Layer"
        direction TB
        Module["Android Module\n(Consumer/Sample App)"]:::runtime
        RuntimeLib["Dropshots Runtime Library"]:::runtime
        Device["Android Device/\nEmulator"]:::runtime
    end

    %% CI/CD & Artifact Repo
    subgraph "CI/CD & Artifact Repo"
        direction TB
        CI["CI Workflows"]:::ci
        Repo["Maven Central\n(Artifact Repository)"]:::ci
    end

    %% Connections
    Gradle -->|"apply plugin"| Plugin
    Plugin -->|"register tasks"| Record
    Plugin -->|"register tasks"| Pull
    Plugin -->|"register tasks"| Clear
    Plugin -->|"applies to modules"| Module
    Record -->|"adb push reference images"| Device
    Gradle -->|"connectedAndroidTest"| Device
    Device -->|"adb pull diff images & results"| Pull
    Module -->|"uses TestRule\nassertSnapshot"| RuntimeLib
    RuntimeLib -->|"captures & compares\nscreenshots"| Device
    CI -->|"publish artifacts"| Repo

    %% Click Events - Build System
    click Gradle "https://github.com/dropbox/dropshots/blob/main/build.gradle.kts"
    click Gradle "https://github.com/dropbox/dropshots/blob/main/settings.gradle.kts"
    click Gradle "https://github.com/dropbox/dropshots/blob/main/gradle/libs.versions.toml"
    click Gradle "https://github.com/dropbox/dropshots/blob/main/gradle.properties"

    %% Click Events - Plugin
    click Plugin "https://github.com/dropbox/dropshots/blob/main/dropshots-gradle-plugin/src/main/kotlin/com/dropbox/dropshots/DropshotsPlugin.kt"
    click Plugin "https://github.com/dropbox/dropshots/blob/main/dropshots-gradle-plugin/src/main/kotlin/com/dropbox/dropshots/DropshotsExtension.kt"
    click Record "https://github.com/dropbox/dropshots/blob/main/dropshots-gradle-plugin/src/main/kotlin/com/dropbox/dropshots/PushFileTask.kt"
    click Pull "https://github.com/dropbox/dropshots/blob/main/dropshots-gradle-plugin/src/main/kotlin/com/dropbox/dropshots/PullScreenshotsTask.kt"
    click Clear "https://github.com/dropbox/dropshots/blob/main/dropshots-gradle-plugin/src/main/kotlin/com/dropbox/dropshots/ClearScreenshotsTask.kt"
    click Plugin "https://github.com/dropbox/dropshots/blob/main/dropshots-gradle-plugin/build.gradle.kts"
    click Plugin "https://github.com/dropbox/dropshots/blob/main/dropshots-gradle-plugin/src/test/kotlin/com/dropbox/dropshots/DropshotsPluginTest.kt"

    %% Click Events - Runtime Library
    click RuntimeLib "https://github.com/dropbox/dropshots/blob/main/dropshots/src/main/java/com/dropbox/dropshots/Dropshots.kt"
    click RuntimeLib "https://github.com/dropbox/dropshots/blob/main/dropshots/src/main/java/com/dropbox/dropshots/BitmapImage.kt"
    click RuntimeLib "https://github.com/dropbox/dropshots/blob/main/dropshots/src/main/java/com/dropbox/dropshots/ResultValidator.kt"
    click RuntimeLib "https://github.com/dropbox/dropshots/blob/main/dropshots/src/androidTest/kotlin/com/dropbox/dropshots/DropshotsTest.kt"
    click RuntimeLib "https://github.com/dropbox/dropshots/blob/main/dropshots/src/androidTest/kotlin/com/dropbox/dropshots/BitmapImageTest.kt"
    click RuntimeLib "https://github.com/dropbox/dropshots/blob/main/dropshots/src/androidTest/kotlin/com/dropbox/dropshots/CustomImageComparatorTest.kt"
    click RuntimeLib "https://github.com/dropbox/dropshots/blob/main/dropshots/src/androidTest/kotlin/com/dropbox/dropshots/FakeResultValidator.kt"
    click RuntimeLib "https://github.com/dropbox/dropshots/blob/main/dropshots/src/androidTest/kotlin/com/dropbox/dropshots/ScreenshotTestFragment.kt"
    click RuntimeLib "https://github.com/dropbox/dropshots/blob/main/dropshots/src/debug/kotlin/com/dropbox/dropshots/TestActivity.kt"
    click RuntimeLib "https://github.com/dropbox/dropshots/tree/main/dropshots/src/androidTest/assets/static"

    %% Click Events - Sample App Module
    click Module "https://github.com/dropbox/dropshots/blob/main/sample/app/build.gradle.kts"
    click Module "https://github.com/dropbox/dropshots/blob/main/sample/app/src/main/java/com/dropbox/dropshots/sample/MainActivity.kt"
    click Module "https://github.com/dropbox/dropshots/blob/main/sample/app/src/androidTest/java/com/dropbox/dropshots/sample/ExampleInstrumentedTest.kt"
    click Module "https://github.com/dropbox/dropshots/tree/main/sample/app/src/androidTest/screenshots"
    click Module "https://github.com/dropbox/dropshots/tree/main/sample/app/src/androidTest/screenshots/views/colors"

    %% Click Events - CI/CD
    click CI "https://github.com/dropbox/dropshots/blob/main/.github/workflows/publish.yml"
    click CI "https://github.com/dropbox/dropshots/blob/main/.github/dependabot.yaml"
    click CI "https://github.com/dropbox/dropshots/blob/main/.github/scripts/checksum.sh"

    %% Styles
    classDef buildtime fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef runtime fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20
    classDef ci fill:#eceff1,stroke:#37474f,color:#37474f
```
