DEV Community: Paul Hameteman

An Introduction to Paparazzi for Snapshot Testing

Paul Hameteman — Thu, 03 Aug 2023 05:28:36 +0000

TL;DR: Snapshot testing with Paparazzi allows you to ensure your Jetpack Compose components behave as expected, without needing an emulator. This article covers setting up Paparazzi, creating a simple Tag composable, and using Paparazzi to create, verify, and update snapshot tests for your Android app.

What is Snapshot Testing?

Snapshot testing allows you to ensure that your output continues to behave as expected. This is useful because as you revisit your code, some changes might cause something to break.

When writing snapshot tests for Jetpack Compose components, you first need to have your code in a working state. Then generate a snapshot of its expected output given certain data. The snapshot tests are committed alongside the component.

Paparazzi is an Android library you can use to create those snapshots for your apps in a simple and friendly way and compare them. One of the advantages this library has over its competitor Shot is that it doesn't need an emulator to run the tests, it just runs in the unit test stage which is much faster.

cashapp / paparazzi

Render your Android screens without a physical device or emulator

Set up

Let's begin the setup process for our first test! To get started, we need to make some changes to the root build.gradle file. First, we'll add the necessary dependency for Paparazzi and apply the plugin. The latest version available at the time of writing is 1.3.1.

The build.gradle file should look like this after adding the dependency:

buildscript {
    // ... Repositories and other settings
    dependencies {
        classpath 'app.cash.paparazzi:paparazzi-gradle-plugin:1.3.1'
        // ... Other dependencies
    }
}

// ... The rest of your build.gradle content

apply plugin: 'app.cash.paparazzi'

Next, in your Android library or app module, we need to include the Paparazzi plugin in the plugins block within build.gradle:

plugins {
    // Other plugin ids
    id 'app.cash.paparazzi'
}

After making these changes, perform a Gradle sync to complete the setup process. Now, we are all set to create our first snapshot using Paparazzi!

Creating the first snapshot test

Let's create a simple Tag composable of which we can make a snapshot later on. Normally a component like this would also have support for click interactions and accessibility. For brevity, we will leave these out in this example.

@Composable
fun Tag(
    name: String,
    modifier: Modifier = Modifier,
    backgroundColor: Color = MaterialTheme.colors.primarySurface,
    contentColor: Color = contentColorFor(backgroundColor)
) {
    Text(
        text = "#$name".toLowerCase(Locale.current),
        modifier = modifier
            .background(
                color = backgroundColor,
                shape = MaterialTheme.shapes.small
            )
            .padding(horizontal = 4.dp, vertical = 2.dp),
        color = contentColor,
        fontSize = 12.sp
    )
}

This will end up in a component looking like this:

Next, let's create the snapshot test. Create a new test and make sure to place it inside the unitTest folder instead of androidTest.

In the TagTest class, add the Paparazzi rule, use rendering mode SHRINK here if you only want to capture the component instead of the whole screen of the device.

@get:Rule
val paparazzi = Paparazzi(
    deviceConfig = DeviceConfig.NEXUS_5.copy(softButtons = false),
    renderingMode = SessionParams.RenderingMode.SHRINK
)

Create a test to render the component like so;

@Test
fun testTag() {
    paparazzi.snapshot("Tag") {
        MaterialTheme {
            Tag(name = "Snapshot-Test")
        }
    }
}

Because we've added Paparazzi to the Gradle files already, there are now 2 additional tasks that you can run.

verifyPaparazziDebug -- Runs tests and verifies against previously-recorded golden values. Failures generate diffs at build/paparazzi/failures.
recordPaparazziDebug -- Saves snapshots as golden values to a predefined source-controlled location (defaults to src/test/snapshots).

Because we haven't created the golden values yet, running the verify task now will result in a failed test.

$ ./gradlew :app:verifyPaparazziDebug

> Task :app:testReleaseUnitTest

com.appsoluut.paparazzi.tag.TagTest > testTag FAILED
    java.lang.AssertionError at TagTest.kt:19

* What went wrong:
Execution failed for task ':app:testReleaseUnitTest'.
> There were failing tests. See the report at: file://android/paparazzi/app/build/reports/tests/testReleaseUnitTest/index.html

Creating the golden values is simple. Look at the tasks table above and see you only need to run the recordPaparazziDebug task to start recording. If it doesn't already exists, a new snapshots folder will be created in the src/test directory. This will contain our snapshot and should look something like this.

If you would run the verifyPaparazziDebug task again, all tests should report successfully. But let's make it more interesting and break the snapshot! Remove the .toLowerCase(Locale.current) part from the Tag composable so we have minimal changes. Run the verifyPaparazziDebug task again and see what happens.

> Task :app:testDebugUnitTest FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':app:testDebugUnitTest'.
> There were failing tests. See the report at: file://android/paparazzi/app/build/reports/tests/testDebugUnitTest/index.html

Unsurprisingly the test failed. You can either open up the HTML report and get a written report of what was going wrong, but that one will only tell you the percentage difference or if the size has changed of the snapshot.

More interesting is to see the actual difference in the snapshot. The tasks will now have created 2 output files which can be found in the build/paparazzi/outputs directory. The delta variant will show the expected, difference and actual snapshot in one handy image.

It's directly clear from the above image what the problem is. If this was expected to change, you can just run the recordPaparazziDebug task again to update the golden values.

Final words

I hope this article helped you get a basic understanding of snapshot testing and inspired you to add them to your project. The next part in this series will be adding the tests to be part of your CI/CD setup.

How-to not clear the logcat on a crash

Paul Hameteman — Mon, 13 Dec 2021 08:51:24 +0000

It is already annoying that your app crashes. But even more so when you can’t find the crash in the logcat due to the app restarting on either the emulator or a physical device.

Luckily, there is a very simple and quick solution for this, it stops Android Studio from clearing the logcat which means you can stop trying to reproduce it multiple times or are forced to use the command line. You can just start fixing the actual error instead.

It only consists of two steps, first open the logcat window in your Android Studio if it’s not already there. On the top right you see the filters dropdown. Open this and select Edit Filter Configuration.

In the Create New Logcat Filter window fill in the Package Name of your application. In my case it is eu.walkthecity. You can fill in anything you want in Filter Name but I would recommend to put the name of your application there so you can easily find it back if you’re working on multiple apps.

The Log Level can be set to anything you want as crashes are always reported as Error. I used Verbose so I can just leave this filter on when looking for my debug messages as well.

Voila, you’re done. Simple right? Now back to more important stuff and get those amazing apps out there!

Android Jetifier — Can we say Bye-Bye yet

Paul Hameteman — Thu, 11 Nov 2021 15:30:16 +0000

A couple of years ago Google deprecated the support libraries in favor of the new AndroidX library. Jetifier is a tool to do this conversion for you if you are using libraries that still depend on those deprecated support libraries. However, doing this conversion every build might be time consuming and it might not even be needed anymore by this time.

“But how do I know if it is still useful?” I hear you ask. Fortunately there is a Bye Bye Jetifier Gradle plugin available by Dipien that has the answer!

dipien / bye-bye-jetifier

Gradle Plugin to verify if you can keep Android Jetifier disabled

Two simple steps to get you started

Luckily it is very easy to get started! Just add the following dependency to your app build.gradle file.

buildscript {
  dependencies {
    classpath "com.dipien:bye-bye-jetifier:1.2.0"
  }
}

The version at the time of this writing was 1.2.0.

At the end of the same build.gradle file, apply the plugin.

apply plugin: "com.dipien.byebyejetifier"

You’re all set. Now when you run the Gradle command ./gradlew canISayByeByeJetifier -Pandroid.enableJetifier=false in a terminal, you'll get an output telling you if your project is still depending on Jetifier or not. In my case I still have to do some more maintenance.

You can not say Bye Bye Jetifier

Gson using AutoValue and Polymorphism

Paul Hameteman — Mon, 19 Jul 2021 06:52:44 +0000

Recently, I ran into a situation where a RESTful API provided me with a list of objects. Normally this isn’t a problem since REST provides you with a structure that is easy to convert. The catch was that some objects inside other objects were polymorphic and required to parse specific fields.

The previous solution was to have a HashMap that contained all the supplied fields. The application then needed to check what kind of object was returned and decide if all required key-value pairs were filled with usable data. This was not a preferred solution and prone to errors.

A lot of suggestions were made to look into custom (de)serializers, which is a good idea, but also a lot of work. I came across the “hidden” RuntimeTypeAdapterFactory class in the Gson repository which solved most of my problem quite nicely.

An Example Problem

Take the following JSON-structure for example:

{
  "article": {
    "title": "Hello world",
    "body": [{
        "type": "text",
        "text": "Hi there"
      }, {
        "type": "image",
        "source": "https://example.com/hello-world-banner.jpg",
        "author": "John Doe",
        "description": "Hello World! banner"
      }, {
        "type": "video",
        "source": "http://mirrorblender.top-ix.org/peach/bigbuckbunny_movies/big_buck_bunny_1080p_surround.avi",
        "thumbnail": "https://peach.blender.org/wp-content/uploads/dl_1080p.jpg",
        "title": "Big Buck Bunny",
        "duration": 574
      }
    ]
  }
}

As you can see, the objects in the body array contain a field called type, which determines the type of object being returned. This will give you flexibility to parse the objects into their own respected models, which in this case should be “text”, “image” and “video”. See the 3 model examples below using Google’s AutoValue.

public interface Block {
}

@AutoValue
public abstract class TextBlock implements Block {
  @SerializedName("text")
  public abstract String text();
}

@AutoValue
public abstract class ImageBlock implements Block {
  @SerializedName("source")
  public abstract String source();

  @Nullable
  @SerializedName("author")
  public abstract String author();

  @Nullable
  @SerializedName("description")
  public abstract String description();
}

@AutoValue
public abstract class VideoBlock implements Block {
  @SerializedName("source")
  public abstract String source();

  @SerializedName("thumbnail")
  public abstract String thumbnail();

  @SerializedName("title")
  public abstract String title();

  @SerializedName("duration")
  public abstract int duration();
}

(For brevity sake I left out the Builders and Gson Type Adapter generators in the above examples.)

The Solution

First we’ll need to create the Article model itself. In the example below you’ll notice the List<Block> return type. If you take a look at the Blocks example code, you’ll see these all implement the Block interface. This way we can easily define new typed objects we want to support in future updates.

@AutoValue
public abstract class Article {
  @SerializedName("title")
  public abstract String title();

  @SerializedName("blocks")
  public abstract List<Block> blocks();
}

But now parsing it; here the magic called RuntimeTypeAdapterFactory will step in! When creating the Gson parser, you can register all kinds of type adapter factories. Add the generated AutoValue adapter and the Runtime adapter and you’re set.

For example:

RuntimeTypeAdapterFactory<Block> articleBlockFactory = RuntimeTypeAdapterFactory.of(Block.class, "type")
  .registerSubtype(TextBlock.class, "text")
  .registerSubtype(ImageBlock.class, "image")
  .registerSubtype(VideoBlock.class, "video");

Gson gson = new GsonBuilder()
  .setDateFormat("yyyy-MM-dd'T'HH:mm:ssZ")
  .registerTypeAdapterFactory(AutoValueTypeAdapterFactory.create())
  .registerTypeAdapterFactory(articleBlockFactory)
  .create();

Retrofit retrofit = new Retrofit.Builder()
  .baseUrl("https://api.example.com/")
  .addConverterFactory(GsonConverterFactory.create(gson))
  .build();

Whenever the Gson parser encounters an object of the type Block the adapter will check if it can parse to any of the defined subtypes. If your API defines the type in a different field than "type" you can provide it. "type" is the default name for the key so you can omit it entirely if your API does work this way.

Caveats

I ran into a couple of minor issues which I needed to solve for my purpose. These findings might also come in handy for you to know when you’ll start working with the RuntimeTypeAdapterFactory.

If the parser encounters an unexpected type, an exception will be thrown and your complete object will be invalid — You can modify the parser to return null instead if you don’t like this approach
The parsed "type" field will not be returned to the model — if you want this info, you’ll need to re-add it

Happy coding!