Paparazzi 2.0 Design

[geoff-powell]

👋🏽 Hello,

This discussion will be used to ideate over the next API design of paparazzi.

WIP

Old 2.0 Refactor
Old snapshotter branch

Brainstorming a way to separate our snapshotter interface from the component that renders the views. This could provide a way to allow Paparazzi snapshotting in Robolectric or Espresso tests (KMP when?).

(interceptor pattern)

interface Snapshotter {
  fun snapshot(): Snapshot
  fun clip(): Clip // Video
}


// Could be future iteration?
(multi-platform apis for other snapshot producers)

// Eventually have LayoutLibEngine, RobolectricEngine, EspressoEngine, SwiftUiEngine, etc.
interface Engine {
  fun render(View): BufferedImage
}



// test module
interface TestSnapshotHandler {
  fun handleSnapshot(Snapshot, TestRecord)
  fun handleClip(Clip, TestRecord)
}

class Paparazzi(...) : TestRule {}}

Keyframe API example

Adds ability to take actions at different points of the video being captured

paparazzi.gif(
      view = container,
      start = 0L,
      end = 2_000L,
      keyframes = listOf(
        // t=200: start loading. Transition will finish at t=500. (start + 300).
        Keyframe(200L) { loadingHelper.isLoading = true },

        // t=400: request stop loading. It will schedule this for t=1200 (start + 1000).
        Keyframe(400L) { loadingHelper.isLoading = false },

        // t=1600: start loading again. Will finish at t=1900.
        Keyframe(1_600L) { loadingHelper.isLoading = true },
      ),
    )

TODOs

• Look into SSIM, FLIP diffing algorithms

• Paparazzi annotation accessibility support

• Paparazzi code-gen manifest useful for Google Compose snapshots

• SDK-ify work needs to be done generating R.jar

• SDK paparazzi values need to come from somewhere

• Jessie's Keyframe API (above)

Meeting Notes

Agenda [1/22/25]

• 2.0 Design thoughts:
• Want to cut a 2.0.0 release in next 2 weeks
• Merge in annotation processing
• Update on sdkification of paparazzi
• Font resource loading: Bypass font path prefix check in ResourcesCompat::loadFont #1798 : solved via comment

[Ashl7]

I think @saket brought up this idea, a .waitForIdle() api similar to android tests would be nice, since paparazzi usually captures screenshot on first frame. Happy to contribute to this.

[geoff-powell]

Ya unfortunately this is a tough api to support. I know there is the InstantAnimationRule for legacy views but I would argue the correct approach is:

• Use pararazzi.gif() and record video of expected output
• Use paparazzi.snapshot(offsetMillis = {offsetToDesiredState}) to take snapshot of your expected state. (I know there is a caveat here that this doesn't work for compose animations at the moment)

[saket]

While I agree that supporting this will require a larger refactor, I don't think using offsets is the correct approach, as it relies on knowing the correct offset. I would never be able to calculate it accurately and would have to resort to guessing random numbers until my screenshots look correct.

[TWiStErRob]

Rename historical paparazzi.gif to express what it does instead of expressing what file format it does not save. Some ideas:

• .snapshotAnimation()
• .animatedSnapshot()
• .movingSnapshot() (feels a bit contradictory, as "snapshot" is a still photograph as far as I understand)
• .video()
• .animation()
• .snapshot() (i.e. just rely on overload with named params)