capturing-preview-screenshots-in-ci

name	capturing-preview-screenshots-in-ci
description	Use this skill to render every Jetpack Compose `@Preview` as a screenshot on a real Android device or emulator and publish a browsable HTML catalog from CI. Covers the Compose HotSwan Gradle compiler plugin (`com.github.skydoves.compose.hotswan.compiler`) and `debugImplementation("com.github.skydoves.compose.hotswan:preview")`, the `captureAllPreviews` task, capturing one preview over ADB via `HotSwanPreviewActivity` + `screencap`, the `hotSwanCompiler { preview { renderDelayMs; demoMode; sdkModeEnabled } }` DSL, per-preview `@PreviewScreenshot(renderDelay = …)`, running it on an emulator in GitHub Actions (`reactivecircus/android-emulator-runner` or Gradle Managed Devices) and deploying the catalog to GitHub Pages, and how device rendering differs from host-JVM tools (Paparazzi, Roborazzi). Use when the user mentions "captureAllPreviews", "HotSwan", "preview screenshots in CI", "screenshot catalog", "preview catalog on GitHub Pages", or "Paparazzi vs Roborazzi vs device screenshots".
license	Apache-2.0. See LICENSE for complete terms.
metadata	{"author":"Jaewoong Eum (skydoves)","keywords":["jetpack-compose","ui-testing","screenshot-testing","compose-preview","hotswan","captureAllPreviews","preview-catalog","github-actions","github-pages","paparazzi-roborazzi"]}

Capturing Preview Screenshots In CI — A Device-Rendered Catalog On Every Commit

A @Preview lives in one engineer's IDE, behind a recompile, on a renderer (layoutlib) that is not the device. This skill turns it into a shared artifact: render every @Preview on a real device/emulator (real ART, real fonts, real image loading, system bars), collect the PNGs into a searchable HTML catalog, regenerate it from CI on every commit, and serve it from GitHub Pages. The tool is Compose HotSwan's Gradle plugin. For structuring previews so this is worth doing, see ../developing-with-compose-previews/SKILL.md.

When to use this skill

• The user wants ./gradlew captureAllPreviews — render all @Previews and produce an HTML catalog.
• The user wants to screenshot one preview from a shell script over ADB without the IDE.
• The user wants a preview catalog deployed to GitHub Pages so designers/QA/PMs can browse components at a URL.
• A preview that loads a network image or settles an animation is captured half-painted — needs render-delay tuning.
• The user asks "Paparazzi vs Roborazzi vs device screenshots — which, and can I run both?".

When NOT to use this skill

• The user wants pixel-diff golden-image regression gates (store a reference PNG, fail on diff). captureAllPreviews does not diff; that is Paparazzi's/Roborazzi's job. Run both if you need both — see the comparison table below.
• The user wants behavioral assertions on a Compose UI (ComposeTestRule, finders) — use ../../setup/choosing-test-rule-vs-runtest/SKILL.md and the compose/finders/ skills.
• The user is fixing why a preview won't render or keeps going "out of date" — that is preview structure; use ../developing-with-compose-previews/SKILL.md.
• The user wants Compose live hot reload (edit code, see it on a running device) — that is the HotSwan IDE plugin's reload feature, a different surface from screenshot capture.

Prerequisites

• A connected device or running emulator with the app installed and launched at least once in the current run — captureAllPreviews drives the running app's process so previews render with the real dependency graph (Hilt/Koin, network, DB) and need no mocks.
• The HotSwan Gradle compiler plugin and the preview library (versions from the project's catalog; 1.3.2 at time of writing):

// libs.versions.toml
[plugins]
hotswan-compiler = { id = "com.github.skydoves.compose.hotswan.compiler", version = "1.3.2" }

// root build.gradle.kts
plugins { alias(libs.plugins.hotswan.compiler) apply false }

// app module build.gradle.kts
plugins { alias(libs.plugins.hotswan.compiler) }
dependencies {
    debugImplementation("com.github.skydoves.compose.hotswan:preview:1.3.2")  // debug only — out of release builds
}

• For CI: an emulator step (reactivecircus/android-emulator-runner@v2) or Gradle Managed Devices (see ../../../instrumentation/managed-devices/running-tests-on-gradle-managed-devices/SKILL.md). KVM enabled on the runner for an accelerated emulator.

Workflow

• 1. Verify why this needs a device. Host-JVM renderers (Paparazzi, Roborazzi) run layoutlib without a device — fast, but the pixels are an approximation. Device rendering goes through ART: device font metrics, real Coil/Glide loading (placeholder, network image, crossfade all execute), GPU/AGSL/blur on the real path, and the full screen including status and navigation bars. The cost is an emulator in CI. Accept that trade only if catalog fidelity matters; otherwise stick with host-JVM diffing.

• 2. Capture one preview over ADB (the primitive). With the debug app built and launched once on the device, the HotSwan preview library exposes HotSwanPreviewActivity, which takes the fully-qualified @Preview function name as a composable string extra:

adb shell am start -S \
  -n com.example.app/com.skydoves.compose.hotswan.preview.HotSwanPreviewActivity \
  --es composable "com.example.app.feature.home.PokedexHomePreview"
sleep 1                                  # let it render
adb exec-out screencap -p > home-preview.png

Replace the package with the applicationId and the extra with the FQN of the preview function. This is the unit every higher-level capture is built on; doing it preview-by-preview does not scale, so use step 3.

• 2a. (Optional) interactive loop in the IDE. With the HotSwan IDE plugin installed, the gutter icon next to a @Preview launches it on device in under half a second with no rebuild, and resolves @PreviewParameter providers via reflection. The IDE plugin is only needed for that interactive flow and for live hot reload — captureAllPreviews below needs only the Gradle plugin.

• 3. Capture every preview at once. With the app running on a connected device:

./gradlew captureAllPreviews

The task: scans every .kt under src/ for @Preview functions and resolves each one's FQN and Gradle module; enables Android System UI Demo Mode so the clock/battery/signal are pinned (diffs stay about your UI, not the time of day); for each preview launches HotSwanPreviewActivity, waits the render delay, runs screencap; restores the status bar and returns the device to the app's main Activity; generates index.html. Everything lands in .hotswan/preview-captures/ at the project root. The catalog has search, module grouping, dark/light toggle, fullscreen view, and per-shot device model + timestamp. With sdkModeEnabled = true it also traces each preview to the composable it wraps and renders a KDoc + parameter table (a design-system reference that cannot drift). No test code anywhere — the task reads @Preview annotations directly.

• 4. Tune the render delay: small global default, per-preview overrides. A shot is taken a fixed number of ms after the composable launches. Too short and a screen loading a network image / running a query / starting an animation is captured half-painted; too long and a big catalog wastes minutes. Set a low global default near the floor and pay extra only where it is earned:

// app module build.gradle.kts
hotSwanCompiler {
    preview {
        renderDelayMs.set(1000L)        // ships at 2500L; most previews are static layout — keep the baseline low
        demoMode.set(true)              // pin status bar for deterministic shots
        sdkModeEnabled.set(false)       // true => KDoc + parameter tables in the catalog (design systems)
    }
}

// per-preview override for the slow minority (network/DB/animation): 3000–5000 ms is typical
@Preview
@PreviewScreenshot(renderDelay = 4000)
@Composable
private fun PokemonDetailPreview() { AppTheme { PokemonDetail(pokemon = samplePokemon) } }

A preview with no @PreviewScreenshot falls back to the global value, so fast stays fast. If most of your previews are data-loading feature screens, the other valid choice is a higher global and overrides on the static minority — match the baseline to the majority.

• 5. Run it in GitHub Actions on an emulator. captureAllPreviews is a normal Gradle task driving ADB, so it runs anywhere a managed Android device exists. The app must be installed and launched before the task runs:

# .github/workflows/preview-screenshots.yml
name: Preview Screenshots
on:
  workflow_dispatch:
  push: { branches: [ main ], paths: [ '**/*.kt', '**/*.xml' ] }
permissions: { contents: write, pages: write, id-token: write }
concurrency: { group: preview-screenshots, cancel-in-progress: true }

jobs:
  capture:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with: { distribution: zulu, java-version: 17 }
      - name: Enable KVM
        run: |
          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
          sudo udevadm control --reload-rules && sudo udevadm trigger --name-match=kvm
      - run: ./gradlew :app:assembleDebug
      - run: rm -rf .hotswan/preview-captures        # so a deleted preview leaves the catalog
      - name: Run emulator and capture
        uses: reactivecircus/android-emulator-runner@v2
        with:
          api-level: 31
          arch: x86_64
          profile: pixel_6
          emulator-options: -no-snapshot-save -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim
          disable-animations: true
          script: |
            adb install -r app/build/outputs/apk/debug/app-debug.apk
            adb shell am start -n com.example.app/.MainActivity
            sleep 10
            ./gradlew :app:captureAllPreviews
      - uses: actions/upload-artifact@v4
        if: always()                                  # keep whatever rendered even if one preview throws
        with: { name: preview-screenshots, path: .hotswan/preview-captures/, retention-days: 30 }

(Gradle Managed Devices is the equivalent if you prefer Google's built-in option — see the GMD skill. The runner action is just less config for a single device.)

• 6. Deploy the catalog to GitHub Pages. A zip you download is not a team asset; a URL is. A second job publishes the captured directory:

  deploy:
    needs: capture
    runs-on: ubuntu-latest
    environment: { name: github-pages, url: '${{ steps.deployment.outputs.page_url }}' }
    steps:
      - uses: actions/download-artifact@v4
        with: { name: preview-screenshots, path: preview-captures }
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with: { path: preview-captures }
      - id: deployment
        uses: actions/deploy-pages@v4

Push to main → emulator boots → every @Preview is rendered and screenshotted → the HTML catalog is built → Pages serves the new version.

Patterns

Pattern: capturing in CI without the app running

# WRONG — captureAllPreviews on a fresh emulator with nothing installed
- uses: reactivecircus/android-emulator-runner@v2
  with:
    api-level: 31
    script: ./gradlew :app:captureAllPreviews
# WRONG because: HotSwanPreviewActivity renders inside the *running app's* process. With no APK
# installed and no Activity started, every launch fails and the catalog comes out empty.

# RIGHT — build, install, launch, settle, then capture
    script: |
      adb install -r app/build/outputs/apk/debug/app-debug.apk
      adb shell am start -n com.example.app/.MainActivity
      sleep 10
      ./gradlew :app:captureAllPreviews

Pattern: one global render delay set high "to be safe"

// WRONG
hotSwanCompiler { preview { renderDelayMs.set(5000L) } }
// WRONG because: every preview now costs 5 s. A 60-preview catalog wastes ~4 extra minutes per run
// to accommodate the handful that actually load remote data.

// RIGHT — low global, opt into the cost where the pixels need it
hotSwanCompiler { preview { renderDelayMs.set(1000L); demoMode.set(true) } }

@Preview @PreviewScreenshot(renderDelay = 4000) @Composable
private fun NetworkImagePreview() { AppTheme { UserAvatar(imageUrl = "https://example.com/p.jpg") } }

Pattern: treating captureAllPreviews as a regression gate

// WRONG — expecting captureAllPreviews to fail the build on a visual change
- run: ./gradlew captureAllPreviews   # then... assume it diffs against last run? it does not.
// WRONG because: captureAllPreviews produces a catalog; it does not store golden images or pixel-diff.
// Nothing fails when a screenshot changes.

// RIGHT — pick the tool for the job; run both if you need both
// Pixel-diff regression gate, no emulator, fast: Paparazzi or Roborazzi (test class per composable, golden PNGs).
// Browsable device-rendered catalog for docs/design review: captureAllPreviews.
// Many projects run Paparazzi/Roborazzi on PRs as a gate AND captureAllPreviews on main for the catalog.

HotSwan captureAllPreviews vs Paparazzi / Roborazzi

Aspect	captureAllPreviews (HotSwan)	Paparazzi / Roborazzi
Rendering	Real device or emulator (ART)	Host JVM, layoutlib
System bars	Included (status + navigation)	Not included
Runtime behavior	Full — network, image loading, DB, DI all execute	UI shell only
Test code required	None — scans @Preview directly	One test class per composable
Output	PNGs + searchable HTML catalog (module grouping, KDoc, params)	PNGs
Pixel-diff regression	Not built in	Yes — the core feature
CI setup	Emulator required (GitHub Actions / GMD supported)	No emulator needed
Best for	Visual cataloging, documentation, design review	Golden-image regression testing

Mandatory rules

• MUST build, install, and launch the debug app on the device/emulator before captureAllPreviews — it renders in the running app's process.
• MUST keep the preview library on debugImplementation so HotSwanPreviewActivity never ships in release builds.
• MUST set a low global renderDelayMs and use @PreviewScreenshot(renderDelay = …) only on previews that load remote data or settle animations — not a blanket high default.
• MUST clear .hotswan/preview-captures/ before a CI run so deleted previews disappear from the catalog instead of lingering, and use if: always() on the artifact upload.
• MUST NOT treat captureAllPreviews as a pixel-diff regression gate — it has no golden-image comparison. Pair it with Paparazzi/Roborazzi if you need that.
• MUST NOT rely on host-JVM screenshot tools (Paparazzi/Roborazzi) when the screenshot must match device fonts, real image loading, GPU/AGSL effects, or system chrome — those need device rendering.
• PREFERRED: enable demoMode so the status bar is deterministic across shots; enable sdkModeEnabled for design-system modules so the catalog carries KDoc + parameter tables.
• PREFERRED: deploy the catalog to GitHub Pages so it has a stable URL non-engineers can open.

Verification

• ./gradlew captureAllPreviews with the app running produces .hotswan/preview-captures/index.html and one PNG per @Preview.
• The single-preview ADB recipe (am start … HotSwanPreviewActivity --es composable <FQN> + screencap) returns a non-empty PNG of that composable.
• debugImplementation("com.github.skydoves.compose.hotswan:preview:…") (not implementation/releaseImplementation); a release build does not contain HotSwanPreviewActivity.
• The CI job installs + launches the app before invoking captureAllPreviews; the uploaded artifact is non-empty on a green run.
• The GitHub Pages deploy job runs needs: capture and the published URL shows the latest catalog after a push to main.
• Slow previews (network/DB/animation) carry @PreviewScreenshot(renderDelay = …); the global renderDelayMs is near the floor for the static majority.

References

• hotswan.dev/blog/compose-preview-screenshots-ci — skydoves, "Compose Preview Screenshots in CI: A Real Device Catalog on Every Commit" (single-preview ADB capture, captureAllPreviews, render-delay strategy, GitHub Actions + emulator-runner, GitHub Pages deploy, Paparazzi/Roborazzi comparison).
• hotswan.dev/blog/compose-preview-driven-development — skydoves, "Compose Preview Driven Development with Instant Feedback" (Preview Runner, captureAllPreviews, why device rendering, CI workflow).
• github.com/skydoves/compose-hotswan — the HotSwan Gradle compiler plugin (com.github.skydoves.compose.hotswan.compiler), the preview artifact, HotSwanPreviewActivity, the captureAllPreviews task, and the hotSwanCompiler { preview { … } } / @PreviewScreenshot API.
• github.com/skydoves/pokedex-compose — a reference project running this exact setup (the screenshot.yml workflow and the published preview catalog).
• developer.android.com/develop/ui/compose/tooling/previews — @Preview and @PreviewParameter (the annotations captureAllPreviews scans).
• github.com/ReactiveCircus/android-emulator-runner — the GitHub Actions emulator step used to host a real Android image in CI.
• Sibling skill: ../developing-with-compose-previews/SKILL.md — structuring @Preview functions so capturing them is worthwhile (state hoisting, @PreviewParameter, anti-patterns).
• Cross-set: ../../../instrumentation/managed-devices/running-tests-on-gradle-managed-devices/SKILL.md — the Gradle Managed Devices alternative to android-emulator-runner for hosting the device in CI.