DEV Community: Anders Ullnæss

Get your Compose callbacks under control using scopes

Anders Ullnæss — Sun, 18 Jun 2023 15:26:16 +0000

Dumb composables

When developing with Jetpack Compose, we want our composables to be "dumb". We want to pass them the state they need to display and callbacks for when the user interacts with them. You can read more about state and compose here:
https://developer.android.com/jetpack/compose/state

A dumb button could look something like this:

@Composable
fun DumbButton(
    text: String,
    onClick: () -> Unit
) {
    Button(onClick = onClick) {
        Text(text = text)
    }
}

The button will tell the caller when it is clicked through the onClick callback. In some part of our code we need to react to this click and do something, typically updating the state of the screen or navigating to a different screen. Maybe we even have to show a loader and call a backend and then navigate to another screen.

Such decision making usually belongs in the ViewModel.
In our setup, the screen composable is the only one that knows about and has access to the ViewModel. It is recommended not to pass the reference to the ViewModel further down to other composables. The screen is therefore often just a thin layer around another "dumb" composable which we call content.

@Composable
fun HomeScreen(
    viewModel: HomeViewModel = getViewModel()
) {
    HomeContent(
        state = viewModel.screenState,
        onDumbButtonClick = viewModel::onDumbButtonClick
    )
}

@Composable 
fun HomeContent(
    state: ScreenState<HomeUiModel>,
    onDumbButtonClick: () -> Unit 
) {
    DumbButton(text = "Click me", onClick = onDumbButtonClick)
}

So far so good, but this screen does not do a whole lot.
What if instead of just one dumb button, the screen has 42 different things the user can do?

@Composable
fun HomeContent(
    state: ScreenState<HomeUiModel>,
    onDumbButtonClick: () -> Unit,
    onOtherButtonClick: () -> Unit,
    onLoginClick: () -> Unit,
    onRegisterClick: () -> Unit,
    onCloseClick: () -> Unit,
    ..
    onYouGetThePoint: () -> Unit) 
{
    ..
}

The list of callbacks can quickly get out of hand for a more complicated screen.

Scopes to the rescue

What is a scope? You have probably seen them around already, with examples such as BoxScope, RowScope, ColumnScope, LazyListScope etc.

interface BoxScope {
    @Stable
    fun Modifier.align(alignment: Alignment): Modifier

    @Stable
    fun Modifier.matchParentSize(): Modifier
}

@Composable
inline fun Box(
    ..
    content: @Composable BoxScope.() -> Unit
) {
    ..
}

If I am in a BoxScope, I can use these modifiers that are not available elsewhere

Scopes are mostly just interfaces and instead of passing them to our composables as a parameter we take advantage of extension functions to give our composable access to all the functions within the scope.

Now, how can we use a scope to avoid our list of 42 callbacks?

interface HomeScreenScope {
    fun onDumbButtonClick()
    fun onOtherButtonClick()
    fun onLoginClick()
    fun onRegisterClick()
    fun onCloseClick()
    ..
    fun onYouGetThePoint()
}

@Composable
fun HomeScreenScope.HomeContent(
    state: ScreenState<HomeUiModel>
) {
    ..
}

The long list of callbacks is gone, but the code within HomeContent still has access to all of them through the scope.
But now we need to call HomeContent on a class that implements the scope.

Among the 42 things the user can do on the home screen, there are two main things that could happen:

The app navigates to another screen
The state changes and (parts of) the screen recomposes

Typically the state changes are handled by the ViewModel and the navigation is handled by a NavHost or similar.

One way to deal with this could be to implement the interface in HomeScreen and direct some callbacks to the ViewModel and others to the NavHost:

@Composable
fun HomeScreen(
    onCloseClick: () -> Unit,
    onLoginClick: () -> Unit,
    onRegisterClick: () -> Unit,
    viewModel: HomeViewModel = getViewModel(),
) {
    val scope = object: HomeScreenScope {
        override fun onDumbButtonClick() = viewModel.onDumbButtonClick()

        override fun onOtherButtonClick() = viewModel.onOtherButtonClick()

        override fun onLoginClick() {
            viewModel.onLoginClick() // For analytics
            onLoginClick() // For navigation
        }

        override fun onRegisterClick() = onRegisterClick()

        override fun onCloseClick() = onCloseClick()
    }
    scope.HomeContent(
        state = viewModel.screenState
    )
}

But now we have a big chunk of code in our screen composable and it needs to know when we should call the ViewModel, when we should call back to the NavHost and even sometimes when we should do both, like in onLoginClick above.

Introducing the NavigationHandler

To get the code and decision making out of the screen composable we make the ViewModel implement the scope instead:

class HomeViewModel: HomeScreenScope {
    override fun onDumbButtonClick() {
        // Update state
    }

    override fun onOtherButtonClick() {
        // Update state
    }

    override fun onLoginClick() {
        // Track login click event
        // TODO: Navigate to login screen
    }

    override fun onRegisterClick() {
        // TODO: Navigate to register screen        
    }

    override fun onCloseClick() {
        // TODO: Pop the backstack
    }
}

Now our screen code gets much more concise:

@Composable
fun HomeScreen(
    onCloseClick: () -> Unit,
    onLoginClick: () -> Unit,
    onRegisterClick: () -> Unit,
    viewModel: HomeViewModel = getViewModel(),
) {
    viewModel.HomeContent(
        state = viewModel.screenState
    )
}

But how do we deal with the navigation? The ViewModel does not know how to navigate and it has no access to the NavHost.

We introduce the NavigationHandler:

interface HomeNavigationHandler {
    fun popBackStack()
    fun navigateToLogin()
    fun navigateToRegister()
}

We take it as input in the screen composable and pass it to our ViewModel. This example is using Koin, but the same idea should work in your dependency injection/service locator pattern of choice:

@Composable
fun HomeScreen(
    navigationHandler: HomeNavigationHandler,
    viewModel: HomeViewModel = getViewModel(parameters = { parametersOf(navigationHandler) }),
) {
    viewModel.HomeContent(
        state = viewModel.screenState
    )
}

Now the ViewModel can delegate the navigation to the NavigationHandler:

class HomeViewModel(
    private val navigationHandler: HomeNavigationHandler
): HomeScreenScope {
    override fun onDumbButtonClick() {
        // Update state
    }

    override fun onOtherButtonClick() {
        // Update state
    }

    override fun onLoginClick() {
        // Track login click event
        navigationHandler.navigateToLogin()
    }

    override fun onRegisterClick() {
        navigationHandler.navigateToRegister()
    }

    override fun onCloseClick() {
        navigationHandler.popBackStack()
    }
}

As a nice bonus, with the ViewModel being in charge of the decision making, whether to update the state or to navigate to another screen, we can easily test that as well:

class HomeViewModelTest {
    private val navigationHandler: HomeNavigationHandler = mockk(relaxUnitFun = true)
    private val viewModel = HomeViewModel(navigationHandler)

    @Test
    fun `Clicking on login navigates to login screen`() {
        viewModel.onLoginClick()
        verify { navigationHandler.navigateToLogin() }
    }
}

A small note about previews

If we want to make a preview of our HomeContent, we would also need to call it on a scope. Instead of creating a whole real ViewModel to do this, we crate an empty scope:

val emptyHomeScreenScope = object : HomeScreenScope {
    override fun onDumbButtonClick() {}
    override fun onOtherButtonClick() {}
    override fun onLoginClick() {}
    override fun onRegisterClick() {}
    override fun onCloseClick() {}
}

@Preview
@Composable 
fun HomeContentPreview {
    emptyHomeScreenScope.HomeContent(someState)
}

Wrapping up

I want to give a shoutout to my colleague Thomas Pienaar, who came up with the idea of using this pattern, which we then improved together.

Let me know what you think of the pattern, if you have any questions or have suggestions for further improvements to it.

You can find me here in the comments or on Twitter

Improving Compose snapshot tests with Paparazzi

Anders Ullnæss — Sun, 31 Jul 2022 13:10:00 +0000

Update:

Since writing this article I've moved on to yet another improved way of doing this. Instead of generating code with KotlinPoet, it automatically runs Paparazzi tests for each Compose Preview. Check it out in this article:
https://proandroiddev.com/no-emulator-needed-for-screenshot-tests-of-compose-previews-on-ci-d292fa0eb26e

Background

I previously wrote about snapshot testing Compose with Shot here:
https://medium.com/proandroiddev/oh-snap-966bd786b7a4

One problem with these tests is they take too long to run. Starting an actual emulator and running the tests on this emulator in our CI environment takes around 30 minutes. This is too long to include it in our continuous integration pipeline which runs on every pull request. Instead we have a nightly job that runs the snapshot tests and reports to our Teams channel if any of them fail.

This approach has some major drawbacks

You are no longer "forced" to fix your failing snapshot tests before you merge
You might discover failing tests too late - even after the changed code has been released
Someone has to take the time to check the Teams channel every morning and fix the tests

Paparazzi to the rescue

Paparazzi is a library which can render your application screens without a physical device or emulator. Not having to deal with the emulator is a massive time saver.

Back when we initially implemented our snapshot tests, Paparazzi was not an option because it did not support Compose. This all changed recently in the 1.0.0 release.

Paparazzi, like Shot, is quite easy to set up. A Paparazzi test looks something like this:



class AlertViewPaparazziTest : PaparazziTest() {

    @get:Rule
    val paparazziRule: Paparazzi = Paparazzi(
        theme = "android:Theme.MaterialComponents.Light.NoActionBar",
        deviceConfig = DeviceConfig.NEXUS_5.copy(softButtons = false, screenHeight = 1),
        renderingMode = SessionParams.RenderingMode.V_SCROLL
    )

    @Test
    fun alert() {
        paparazziRule.snapshot { AlertPreview() }
    }
}

Again like Shot, Paparazzi has one gradle task for recording:
$ ./gradlew sample:recordPaparazziDebug
And one for verifying:
$ ./gradlew sample:verifyPaparazziDebug

Unfortunately Paparazzi does not (yet) support taking a screenshot with the exact size of the Composable: https://github.com/cashapp/paparazzi/issues/383
The screenHeight = 1 and renderingMode = V_SCROLL is a trick to get the minimum height needed to take a screenshot of the Composable. Thanks https://github.com/hrach!
There is no similar trick for the width (that I know of, please let me know if you know one!), so we always get the full width of the device which leads to some screenshots looking like this (if you click it you see the full device width):

Though it would be nicer without the full width, this is not a big problem. The main point is to compare the current situation to the previously recorded snapshot and see that there are no unintended changes. This works just as well with a full width.

Rewrite all the tests

To really compare Paparazzi with Shot and see if it solved our problems, we had to rewrite all our snapshot tests. This would be quite boring and repetitive, so we decided to try to generate them instead of writing them manually.

We always write one snapshot test per @Preview annotation. Because of this, all our snapshot tests look pretty much the same,
Our idea was something like this:

Find every file that has at least one @Preview annotation
Create a snapshot test file for it
Create one test per @Preview in that file

To do this we created a Kotlin program with a main function and used another library, also from Square, KotlinPoet (https://github.com/square/kotlinpoet) to generate the code.

Disclaimer: This code is still quite rough, but you get the idea and it does what we needed. I am sure it could be improved further.



/**
 * Finds all files in the components module which have Compose previews
 * and generates Paparazzi screenshot tests for them.
 *
 * The generated tests can then be used to record screenshots with
 * ./gradlew components:recordPaparazziInternalDebug
 *
 * To verify that the current implementation matches the recorded screenshots
 * ./gradlew components:verifyPaparazziInternalDebug
 */
fun main() {
    val path = System.getProperty("user.dir") ?: error("Can't get user dir")

    // Paparazzi does not currently work in the app module: https://github.com/cashapp/paparazzi/issues/107
    // For now this is hardcoded to only check files in the components module.
    // If we pull our compose files out of the app module to a separate module this code has to be updated.
    File(path).walk().filter { it.path.contains("/components/src/main/java") && it.extension == "kt" }.forEach {
        if (it.readText().contains("@Preview")) {
            processFileWithPreviews(it)
        }
    }
}

/**
 * Reads the given file, finds the names of all the functions annotated with @Preview
 * and uses them to generate a Paparazzi test file with one test for each preview.
 */
private fun processFileWithPreviews(file: File) {
    val lines = file.readLines()
    val previewNames = mutableListOf<String>()
    var saveNextFunctionName = false
    var packageName = ""
    lines.forEachIndexed { i, line ->
        if (i == 0) {
            packageName = line.split(" ").last()
        }
        if (line.contains("@Preview")) {
            saveNextFunctionName = true
        }
        if (saveNextFunctionName && line.startsWith("fun ")) {
            previewNames += line.split(" ")[1].removeSuffix("()")
            saveNextFunctionName = false
        }
    }
    val pathString = file.path.replace("src/main", "src/test").split("java").first() + "java"
    val testFilePath = pathString.toPath()
    generatePaparazziTest(packageName, file.nameWithoutExtension + "PaparazziTest", testFilePath, previewNames)
}

fun generatePaparazziTest(packageName: String, fileName: String, path: Path, previewNames: List<String>) {
    val classBuilder = TypeSpec.classBuilder(fileName)
        .superclass(PaparazziTest::class)
        .addAnnotation(
            AnnotationSpec.builder(Suppress::class)
                // KotlinPoet does not let us remove redundant public modifiers or Unit return types for the functions,
                // but we don't mind for generated code as long as the tests work
                .addMember("\"RedundantVisibilityModifier\", \"RedundantUnitReturnType\"")
                .build()
        )
    previewNames.forEach {
        classBuilder.addFunction(
            FunSpec.builder(it.removeSuffix("Preview").usLocaleDecapitalize())
                .addStatement("paparazziRule.snapshot { $it() }")
                .addAnnotation(Test::class)
                .build()
        )
    }
    val testFile = FileSpec.builder(packageName, fileName)
        .addType(classBuilder.build())
        .addFileComment("AUTO-GENERATED FILE by generate_paparazzi_tests.kt\nDO NOT MODIFY")
        .build()
    val nioPath = path.toNioPath()
    testFile.writeTo(nioPath)
}

Since we always use the same device specs and Paparazzi rule, we created a parent class and the program above generates sub-classes for that:



open class PaparazziTest {

    @get:Rule
    val paparazziRule: Paparazzi = Paparazzi(
        theme = "android:Theme.MaterialComponents.Light.NoActionBar",
        deviceConfig = DeviceConfig.NEXUS_5.copy(softButtons = false, screenHeight = 1),
        renderingMode = SessionParams.RenderingMode.V_SCROLL
    )
}

As you can see from one of the comments, Paparazzi does not yet support running tests in the app module: https://github.com/cashapp/paparazzi/issues/107

In our project the composables live in two modules: :components for reusable components and :app for the screens and single use views. For now, our program only generates paparazzi tests for the :components module. We would have to move all our composables out of the app module which can turn into a bigger refactor. This recent issue gives some hope that it could be fixed soon and we might not need to do that: https://github.com/cashapp/paparazzi/issues/524

Add it to continuous integration

After all the tests had been generated, we recorded the snapshots (60 of them in our :components module) and pushed them to our source control. We then added a new step to our CI pipeline which runs on every pull request. Just a simple gradle step that runs the verifyPaparazzi task. It is super fast:

Final thoughts

Paparazzi makes snapshot test verification fast enough to run in our CI pipeline on every pull request
Recording screenshots locally when adding new UI or changing existing UI is much faster without an emulator
Not having to deal with an emulator seems to solve a problem we had in the past where screenshots would be slightly different if they were recorded on a Mac with Apple Silicon or one with Intel
It is unfortunate that we can't use Paparazzi in the app module (yet)

We have decided to move forward with Paparazzi and will wait for the app module issue to be fixed or move our composables out of the app module.

Please let me know if you have any feedback or questions in the comments or on Twitter.

I leave you with an image of some of our components recorded by Paparazzi: