TRazDev/Mugshot

You already wrote a @Preview for most of your screens. Mugshot is a screenshot testing library that turns each one into a test: put @Mugshot on it, record once, and the build fails whenever that screen changes. The screens render on the JVM with layoutlib, the renderer behind Android Studio's previews, so the tests run as ordinary unit tests on any machine that can build your app.

_{Golden images recorded from the previews in this repository's sample module. The last one is the profile screen with @MugshotLocales set to Arabic.}

There's no test class to write and no list of screens to keep in sync. A KSP processor finds every annotated preview and generates the test, so adding a preview adds its screenshot and deleting one removes it.

It works in Kotlin Multiplatform modules. Previews in commonMain are picked up like any others, and Compose Multiplatform resources, including stringResource, render in the golden images.

It's quick. On a 30-module app with 7,176 screenshots, Mugshot verified everything in 58 seconds. Paparazzi took 89, and Google's Compose Preview Screenshot Testing ran out of memory at default settings. The benchmark has the details and a public repository to rerun it.

It stays out of your way in Gradle. Screenshot tests run in a task and a JVM of their own, so they don't collide with Robolectric, and the Gradle plugin supports the configuration cache.

Apply KSP and the plugin to a module that has Compose previews:

plugins {
  id("com.google.devtools.ksp")
  id("uk.co.fractalmotion.mugshot") version "3.4.2"
}

Annotate a preview:

@Mugshot
@Preview
@Composable
internal fun ProfileScreenPreview() {
  AppTheme { ProfileScreen(state = sampleProfile) }
}

Record the golden images:

./gradlew recordMugshotDebug

The images are in src/test/snapshots/images/. Commit them, and from then on ./gradlew verifyMugshotDebug fails if any screen changes.

Mugshot runs in a module that uses com.android.kotlin.multiplatform.library. Apply the same two plugins and turn on host tests, which is where the generated test lives:

kotlin {
  android {
    withHostTest {
      isIncludeAndroidResources = true
    }
  }
}

That's the whole setup. The plugin adds the annotations to commonMain and the test machinery to androidHostTest, so there are no dependencies to declare. Annotate previews in commonMain, run ./gradlew :shared:recordMugshot, and the golden images land in src/androidHostTest/snapshots/images/.

_{MugshotSampleKMP is a Compose Multiplatform app for Android, iOS and desktop with Mugshot set up, and 192 golden images across four devices, two themes and four locales.}

The images are Android renders of your shared UI. Platform-specific code runs its Android actual, so something that only differs on iOS won't show up.

@Mugshot records one image on the default device, a Pixel 10. Every other annotation adds an axis, and axes multiply:

MugshotDevice is one of PHONE, FOLDABLE, TABLET, LANDSCAPE, WEAR_ROUND and WEAR_SQUARE.

@MugshotMatrix on a single preview gives you this:

Pass arguments to narrow an axis rather than dropping the annotation:

@Mugshot
@MugshotDevices(MugshotDevice.PHONE, MugshotDevice.TABLET)
@MugshotLightDark
@Preview
@Composable
internal fun ProfileScreenPreview() { ... }
// 2 devices × 2 appearances = 4 images

@MugshotLocales is the one axis that keeps a baseline of its own. The others already include theirs (PHONE, light, 1f), so naming a single locale gives you two images: the default and that locale.

The annotations work on annotation classes as well as functions, so a team can put its house style behind one name:

@Mugshot
@MugshotDevices(MugshotDevice.PHONE, MugshotDevice.TABLET)
@MugshotLightDark
annotation class OurScreenshots

@OurScreenshots
@Preview
@Composable
internal fun ProfileScreenPreview() { ... }

A @PreviewParameter provider is expanded when the test runs, one image per value, so a single preview covers a screen's loading, empty and populated states:

@Mugshot
@Preview
@Composable
internal fun StorefrontScreenPreview(
  @PreviewParameter(StorefrontStateProvider::class) state: StorefrontUiState
) {
  MyTheme { StorefrontScreen(state) }
}

Images are indexed (_0, _1, …) rather than named after the value, because a value's toString() isn't safe in a filename.

An annotated function must be @Composable, must carry a @Preview, must not be private, and must take no parameters other than a single @PreviewParameter.

A preview that breaks one of those rules is skipped. There's no test file to fail, so the build stays green and no image appears. The lint checks turn that silence into a message:

dependencies {
  lintChecks 'uk.co.fractalmotion.mugshot:mugshot-preview-lints:3.4.2'
}

The warning is worth having even when everything works. @Preview's own arguments are ignored: Mugshot takes its configuration from its annotations, so setting device, uiMode, locale or fontScale on @Preview changes what the IDE renders while the golden image stays the same.

LIMITATIONS.md covers what Mugshot doesn't do and where its rendering differs from a device.

A failed verification shows up in the HTML test report with the golden image, a difference image and the new render side by side. In the difference image, red marks every pixel that changed and everything else is white, so you can see at a glance which part of the screen moved.

The report is in build/reports/tests/<testTask>. The same images, plus a single combined image the console error links to, go to build/mugshot/failures for CI to upload.

To make CI fail on visual changes:

tasks.named("check") {
  dependsOn("verifyMugshot")
}

If the change was intentional, record again and commit the new golden images with the code.

Mugshot, Paparazzi and Google's Compose Preview Screenshot Testing screenshotted the same generated app: 30 modules and 299 previews, each rendered on four devices, in light and dark, at three font scales. That's 7,176 screenshots per tool.

Verify times are the median of three runs on a MacBook Pro with an M5 Pro and 24 GB. Compose Preview Screenshot Testing needed android.compose.screenshot.maxHeapSize=2g to record without running out of memory, and even then couldn't verify at default parallelism on that machine.

Part of the lead comes from resolution. Mugshot renders the device at a third of its resolution, Paparazzi renders at full size and shrinks the image to 1,000 pixels, and Compose Preview Screenshot Testing keeps full size. At full resolution Mugshot verifies in 149 seconds, slower than Paparazzi. The layout is identical either way, because Mugshot scales density along with the screen, so every dp stays a dp.

Everything is reproducible from TRazDev/screenshot-testing-benchmark: the app, one branch per tool, the benchmark script and every raw result. It doesn't include Roborazzi yet.

Each task has an anchor form that covers every variant and a per-variant form (recordMugshotDebug, verifyMugshotRelease, and so on).

./gradlew recordMugshotDebug
./gradlew verifyMugshotDebug
./gradlew verifyMugshotDebug --tests '*ProfileScreen*'

The generated test is MugshotGeneratedPreviewTest, in your module's namespace, so golden images are named:

<namespace>_MugshotGeneratedPreviewTest_snapshot[<preview>_<axes>].webp

for example com.example.myapp_MugshotGeneratedPreviewTest_snapshot[ui_ProfileScreen_ProfileScreenPreview_Dark].webp.

Set these in gradle.properties; the plugin forwards them to the test JVM.

Snapshots render a third of the device's resolution by default. Dimensions, dpi and density scale together, so every dp stays a dp and the layout is identical to the full-size device, with fewer pixels in it. On a 30-module project of 7,176 images that made verification 27% faster and the golden images 45% smaller. Nothing is resampled after rendering, so glyph edges come out crisper, though at that size letter spacing can be slightly uneven.

uk.co.fractalmotion.mugshot.downscale=1 renders at the device's own resolution. That's the most detail available, so lower values are rejected. Two reasons to reach for it:

• A module shipping density-qualified bitmaps. The qualifier resolves from the scaled density, so a drawable-xxhdpi PNG can be passed over for one the real device wouldn't pick. Vector and Compose UIs are unaffected.
• Small text you need to read in a failure report, where a third of the pixels is a third of the glyph.

Changing it changes every image, so re-record when you do.

Some things the annotations don't reach. For those, drive the rule yourself:

class ProfileScreenTest {
  @get:Rule
  val mugshot = Mugshot(
    deviceConfig = DeviceConfig.PIXEL_6,
    theme = "android:Theme.Material.Light.NoActionBar",
    showSystemUi = true
  )

  @Test
  fun profile() {
    mugshot.snapshot { MyTheme { ProfileScreen(state = sampleProfile) } }
  }
}

Reachable only this way: unsafeUpdateConfig to change device, theme or rendering mode part-way through a test; a custom RenderExtension to decorate every snapshot; showSystemUi, downscale and maxPercentDifference; and Android Views, via mugshot.inflate<MyView>(R.layout.my_view) and mugshot.snapshot(view). For JUnit 5, build the rule yourself and call setup(TestName(...)) and teardown() around each test.

The sample project's screen/ and component/ test packages have worked examples of each.

Mugshot and Robolectric can't share a JVM. Mugshot loads layoutlib's native library, patches Build.VERSION, and permanently redefines android.view.View.isInEditMode in the test JVM through a Byte Buddy agent. Robolectric's own native setup then fails with UnsatisfiedLinkError, including in Robolectric tests that take no screenshots at all.

Generated preview tests keep out of the way. The plugin runs them in a task of their own, mugshotTest<Variant>, with its own JVM, and leaves them out of the module's unit test task, so Robolectric tests in the same module keep working. uk.co.fractalmotion.mugshot.isolateTests=false puts them back in the unit test task.

Hand-written Mugshot tests can't be separated that way, because nothing about them is visible to the plugin. They run with the rest of the module's unit tests, so a module whose Robolectric tests have to stay needs its hand-written Mugshot tests in a module of their own.

Tests must not run concurrently inside one JVM. Layoutlib is initialised once and reused, which is most of why a suite is quick, and the renderer that holds it is shared by every test in the JVM. Gradle's default of a worker per fork is fine, and so is maxParallelForks, which forks more JVMs. Running tests concurrently within one JVM, with JUnit 5's parallel execution for instance, isn't: they will render over each other.

A golden image is named after the test that took it: the package, the class, the method, and the label if snapshot was given one. Nothing about those is bounded, and a name has to survive a filesystem, so a name longer than 200 characters keeps its readable beginning and ends in a hash of the whole of it:

com.example.feature_VeryLongTest_aVeryLongMethodName...~3f9c1a7b2e04.webp

The hash comes from the full name, so it's the same on every machine and every run, and two long names that begin alike stay apart. Real names are nowhere near the limit (the longest in this repository's own sample is 136 characters), so this only affects names that would otherwise be rejected.

Windows caps a whole path at 260 characters unless long paths are turned on. A deep module tree can reach that even with a name under the limit, so on Windows it's worth enabling long path support in both the OS and Git:

git config --global core.longpaths true

We recommend storing golden images with Git LFS:

brew install git-lfs
git config core.hooksPath  # optional, confirm where your git hooks will be installed
git lfs install --local
git lfs track "**/snapshots/**/*.webp"
git add .gitattributes
# Optional to improve git checkout performance
git config lfs.setlockablereadonly false

On CI, you might set up something like:

$HOOKS_DIR/pre-receive

# compares files that match .gitattributes filter to those actually tracked by git-lfs
diff <(git ls-files ':(attr:filter=lfs)' | sort) <(git lfs ls-files -n | sort) >/dev/null

ret=$?
if [[ $ret -ne 0 ]]; then
  echo >&2 "This remote has detected files committed without using Git LFS. Run 'brew install git-lfs && git lfs install' to install it and re-commit your files.";
  exit 1;
fi

your_build_script.sh

if [[ is running snapshot tests ]]; then
  # fail fast if files not checked in using git lfs
  "$HOOKS_DIR"/pre-receive
  git lfs install --local
  git lfs pull
fi

• MugshotSampleKMP: a Compose Multiplatform app for Android, iOS and desktop with Mugshot set up
• screenshot-testing-benchmark: the same app tested with Mugshot, Paparazzi and Compose Preview Screenshot Testing, with the benchmark and results
• Articles:
  • Screenshot tests for your Compose previews, with one annotation
  • My screenshot tests spent more time shrinking images than rendering them
  • Screenshot testing a Compose Multiplatform app without an emulator
  • Mugshot, Paparazzi and Compose Preview Screenshot Testing on the same 7,176 screenshots

The change log has release history.

Using the plugins DSL:

plugins {
  id 'uk.co.fractalmotion.mugshot' version '3.4.2'
}

Using plugin application:

buildscript {
  repositories {
    mavenCentral()
    google()
  }
  dependencies {
    classpath 'uk.co.fractalmotion.mugshot:mugshot-gradle-plugin:3.4.2'
  }
}

apply plugin: 'uk.co.fractalmotion.mugshot'

Snapshots of the development version are available in the Central Portal Snapshots repository:

repositories {
  // ...
  maven {
    url 'https://central.sonatype.com/repository/maven-snapshots/'
  }
}

Mugshot is a fork of Paparazzi, created and maintained by Square, Inc. Essentially all of the hard engineering here, the layoutlib integration, the resource loading and the rendering pipeline, is their work. This fork exists to take the project in a direction that would have been too breaking to land upstream, and is not affiliated with, endorsed by, or sponsored by Square, Inc. or Cash App.

See NOTICE for the full attribution and a summary of what has changed.

Copyright 2019 Square, Inc.
Copyright 2026 Fractal Motion

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.