DEV Community: Gil Goldzweig Goldbaum

Part 1: The Philosophy of Testable Code

Gil Goldzweig Goldbaum — Tue, 26 Aug 2025 15:59:47 +0000

Great software isn't just written; it's engineered. Like any complex structure, it relies on the integrity of its smallest components. If a single brick is flawed, the entire wall is at risk. This handbook is about learning to forge perfect bricks, and was born from an internal need to have a one-stop shop for everything unit testing—the discipline of verifying each component in isolation so that we can confidently build large, reliable systems.

This is more than just a style guide—it's a practical framework for building quality and speed into our development process. I aimed to make this a comprehensive resource that benefits everyone, from developers writing their first unit tests to senior engineers looking to align on best practices. This handbook helps us create the safety net we need to refactor and innovate by establishing a common vocabulary, providing a clear path for new features and serving as a consistent standard for code reviews.

A few notes before we get started!

Perspective:
Like most things in software, this write-up is opinionated. I’ve done my best to gather feedback from various engineers before publishing to include multiple perspectives. However, it’s still filtered through my own experience and preferences.
Treat it as a guide, not gospel.

Platform Agnosticism:
While the code examples in this handbook are written in Kotlin and use common Android libraries, the
underlying principles of isolation, dependency injection, and
contract-based design are universal. Developers on any
platform—Backend, iOS, or Web—can apply these philosophies to build
more testable and maintainable software. An appendix is included at
the end of Part 3 to help translate platform-specific terms.

In this handbook, you will learn:

The Principle of Isolation and why it matters.
How to use interfaces for testable code.
The difference between Mocks, Stubs, and Fakes
Best practices for organizing your tests for maintainability and speed.

Part 1 (This Page): The Philosophy. We will explore our foundational principle—the Principle of Isolation—and the architectural mindset required to support it.
Part 2: From Theory to Practice(Show me the code!). We will cover the specific architectural patterns and testing techniques we use to build and verify isolated components.
Part 3: Standards and Troubleshooting. We will detail our concrete standards for naming, organization, and style, and provide guidance for common issues.

The Core Philosophy of Unit Testing: The Principle of Isolation(The “Why”)

Before we write a single line of test code, we must understand our guiding philosophy: The Principle of Isolation.

This principle states that a unit test must verify one "unit" of code—typically a single class—in complete isolation from its dependencies. Think of it as placing your code in a sterile laboratory environment. You control all the inputs and observe the outputs, ensuring that the test result is influenced only by the logic of the unit under test.

Why is this non-negotiable?

Pinpoint Bugs with Precision: When an isolated unit test fails, you know exactly where the bug is: in the logic of the component you are testing. This is its primary strength. Let's contrast this with an integration test, which serves a different, equally important purpose. An integration test might fire up a ViewModel, which calls a real Repository, which makes a real network call. If that test fails, the scope of the problem is broader: Is the ViewModel's logic wrong? Did the Repository fail to parse the JSON? Did the network request time out? Is the backend server down? You've started a broader debugging process to pinpoint the issue across several components. An isolated unit test eliminates this ambiguity for a single unit and dramatically reduces debugging time for that unit's specific logic.
Create a Fast and Reliable Test Suite: Real dependencies, like network clients or databases, are slow and can be unreliable. A network call involves latency and can fail for reasons outside our code's control. Mocking these dependencies makes our tests lightning-fast (running in milliseconds) and, crucially, deterministic—they produce the same result every single time. This is essential for a fast and stable CI/CD pipeline and a quick feedback loop for developers.
Enable Fearless and Safe Refactoring: When you have a comprehensive suite of isolated unit tests, you gain the confidence to make changes. You can refactor a component's internal logic, and as long as your tests still pass, you can be confident you haven't broken its behavior from the outside world's perspective.

To be clear, this is not a case against integration tests, but rather
a case for what a unit test should be and do. Integration tests are an
essential part of a comprehensive testing strategy and are not a
replacement for unit tests, or vice-versa. They are invaluable for
catching problems that unit tests, by design, cannot: deserialization
failures, API contract mismatches, and end-to-end logic errors. For
example, without integration tests leveraging in-memory databases,
it's difficult to verify persistence logic or query correctness prior
to deployment. The goal of this handbook is to define the specific,
distinct role of a unit test: to verify a single component’s logic
with surgical precision. This, in turn, makes the feedback from our
integration tests even more valuable.

In short, we isolate our units during testing to ensure our tests are precise, fast, and maintainable. This approach builds a foundation of trust in our code, allowing us to develop features more quickly and refactor with confidence.

The Contract of Trust

To achieve isolation, we operate on a "contract of trust." When we test a class, we trust that its dependencies will work as advertised because their correctness should also be validated in their own separate unit tests. This leads to a clear separation of concerns in our testing:

The ViewModel test asks: "When the UI requests data, does the ViewModel correctly call the repository and properly handle the success or error result that the repository says it will return?"
The Repository test asks: "When asked for data, does the repository correctly use its dependencies (like a Retrofit service) to fetch it from the network/database?"

Extending the Contract: Trusting Third-Party Code

This contract of trust extends beyond our own codebase. We also inherently trust the frameworks, libraries, and even the language's standard library that we use.

It is not our job to verify that third-party code works. For example:

We don't need to write a test to confirm that Retrofit successfully makes an HTTP request when we call apiService.someNetworkRequest(). We trust the Retrofit team has already tested this thoroughly. Our test should simply verify that our code calls the apiService.someNetworkRequest() method.
We don't need to write a test that String.trim() actually removes whitespace. We trust that the language developers have validated this basic functionality.

Trusting the API Contract

Our most important external dependency is our own backend. Our unit tests operate under a strict assumption: the backend will adhere to its established API contract (e.g., as defined in OpenAPI/Swagger/Your slack thread…).

What We Test: Our responsibility is to verify that the client correctly handles all documented success and error states from the API. Including edge cases, for example: dealing with an unknown/default enum parsing.
What We Don't Test: We do not write tests for hypothetical scenarios where the backend violates the contract (e.g., sending an Int for a field that should be a String).

This approach has two powerful benefits:

Faster Debugging: If a production issue occurs and all our client-side tests are passing, it gives us high confidence that the root cause is not in the client application. This allows us to more quickly identify the problem as a likely backend or environmental issue. On the flip side, if the issue turns out to be on our end and our test suite failed to catch the issue, we have a chance to improve our own testing suite. Perfection doesn’t exist; it’s about continuous improvement.
Enabling API Evolution: Our test suite acts as a "consumer contract" for the API. If the backend team needs to make a change, we can simulate the change on the client. If all tests pass, it provides high confidence that the change is backward-compatible and won't break existing clients in production. If something does fail, we probably need to add some versioning or create a new endpoint.

Our responsibility is to test the logic we write—the code that glues these trusted components together. We test our business logic, our state transformations, and our interactions with dependencies, but not the dependencies themselves. This focus keeps our test suite lean, relevant, and centred on the value we are adding.

When each component is rigorously tested in isolation, it becomes a trusted, reliable building block—like a Lego brick. We can then combine these "bricks" to construct complex features, confident that each individual piece will behave exactly as expected. This compounding trust is what allows us to build large, stable systems with confidence.

We’ve laid the philosophical groundwork for our testing strategy and know why we forge each "Lego brick" in isolation. Now, it's time to see how those bricks are made. The next section will move from theory to practice, detailing the architectural patterns and tools we use to build testable, trustworthy components.
On to Part 2 ->

Part 2: From Theory to Practice (Show me the code!)

Gil Goldzweig Goldbaum — Tue, 26 Aug 2025 15:56:51 +0000

Welcome to Part 2. In the previous section, we established our core philosophy: testing units in complete isolation. Now, we'll dive into the "how"—the specific architectural patterns and testing techniques we use to build and verify our isolated components.

Key Concepts Covered in Part 2:

Architecting with interfaces for dependency injection and testability.
Using sealed classes for robust error handling tests.
The practical differences between Mocks, Fakes, and Spies.
Strategies for testing asynchronous code and business logic layers.

How to Architect for Testable Code

Theory is grand, but how do we build a feature that can be tested in isolation? It starts with our architecture.

To illustrate, let's use a running example for the rest of this guide.

User Story: The Profile Screen As a user, when I open the profile screen, I want to see a loading indicator. Once the data is loaded, I want to see my name and profile picture. If there is a server error, I want to see a generic error message. If there is no internet connection, I want to see a specific 'No Internet' error with an option to retry.

This simple feature involves a UI, a component to hold the display logic (which could be a ViewModel, Controller, or Presenter), and a Repository for the data layer. We will design them to be perfectly isolated.

Defining Testable Contracts with Interfaces

Our single most important technique is "Program to an Interface, not an Implementation." This means our components depend on abstract contracts (interface or abstract class), not on concrete classes.

In our example, to handle state management, we use a simple State sealed class and a MutableStatefulFlow to handle emissions to the UI.

// State.kt
/**
 * Wrapper class that is able to handle different state
 *
 * @param <T> data to wrap</T>
 * */
sealed class State<T> {
    var observed: AtomicBoolean = AtomicBoolean(false)

    class Created<T> : State<T>()
    class Loading<T> : State<T>()
    data class Success<T>(val data: T) : State<T>()
    data class Error<T>(val error: Throwable) : State<T>()
    class Completed<T> : State<T>()
}

typealias StateFlow<T> = Flow<State<T>>

// MutableStatefulFlow.kt
open class MutableStatefulFlow<T> : Flow<State<T>> {
    private val stateFlow = MutableStateFlow<State<T>>(State.Created())

    val currentState: State<T>
        get() = stateFlow.value

    fun emitCreated() {
        stateFlow.value = State.Created()
    }

    fun emitLoading() {
        stateFlow.value = State.Loading()
    }

    fun emitError(throwable: Throwable) {
        stateFlow.value = State.Error(throwable)
    }

    fun emitSuccess(data: T) {
        stateFlow.value = State.Success(data)
    }

    fun emitCompleted() {
        stateFlow.value = State.Completed()
    }

    override suspend fun collect(collector: FlowCollector<State<T>>) {
        stateFlow.collect(collector)
    }
}

Now, we define the specific contracts for our feature using these standard types.

// The data contract: What can a UserRepository do?
interface IUserRepository {
    suspend fun fetchUserProfile(): Result<User>
}

// The UI logic contract.
abstract class IProfileViewModel : ViewModel() {
    abstract val profileStateFlow: StateFlow<User>
    abstract fun fetchProfile()
}

Note: We use IProfileViewModel here as an example. In other architectural patterns like MVC or MVP, this component might be named IProfileController or IProfilePresenter. The name is less important than the principle: it is an interface that defines the contract for the component responsible for UI logic.

Building Ironclad Contracts

The IUserRepository interface is a formal, written agreement between different parts of our software. It's a contract that says:

"Any class that claims to be an IUserRepository must provide a way to fetchUserProfile(). I don't care how you do it—whether you get the data from a network, a database, or a text file—but you must fulfill this promise."

This allows our ProfileViewModel to depend on the idea of a repository (IUserRepository) rather than a specific, concrete implementation (UserRepositoryImpl).

However, the Result.failure(error: Throwable) part of this contract is a good start, but relying on a generic Throwable is vague. It's like a legal agreement that doesn't define its terms—it leaves too much open to interpretation and creates ambiguity. To make our contract ironclad, we must explicitly describe every possible failure to cover all our bases, ensuring no surprises exist for the components that rely on it.

We achieve this by creating a sealed class that extends Throwable. This approach allows us to define a closed, exhaustive set of specific, well-defined error types that our data layer can produce, making our error handling fully deterministic.

We extend Throwable because it allows us to have a stacktrace if needed.

For example, when reporting to Firebase or DataDog, we can use the stacktrace to know who called our function.

/**
 * Models the exhaustive set of well-defined errors that can originate from our repositories.
 * This sealed hierarchy ensures that all possible error cases must be handled by the caller.
 */
sealed class RepositoryError(override val message: String) : Throwable(message) {
    /** The request failed due to a network connectivity issue. */
    data class NetworkError(val originalError: IOException) : RepositoryError("Network connection error")

    /** The server responded with a non-2xx status code. */
    data class ServerError(val code: Int) : RepositoryError("Server error with code: $code")

    /** The data received from the server could not be parsed. */
    object DeserializationError : RepositoryError("Failed to parse data")

    /** An unknown or unexpected error occurred. */
    data class UnknownError(val originalError: Throwable) : RepositoryError("An unknown or unexpected error occurred")
}

Now, the implicit contract of IUserRepository is that if fetchUserProfile() returns a Result.failure, the associated Throwable will be an instance of RepositoryError. This makes our business logic and our tests far more robust and expressive. This pattern does more than make tests robust; it fundamentally makes our code easier to read, understand, and maintain. By defining an explicit set of possible failures, we reduce the number of unknowns, which is a massive benefit for any developer, especially someone new to the project.

Controlling Dependencies for Testability

To reliably test asynchronous code and other external dependencies, we must be able to control them from outside the class being tested. Hardcoding dependencies like Dispatchers.IO or concrete service classes makes this very difficult. The solution is to use Dependency Injection, where we define interfaces for our dependencies and provide them through a class's constructor. For example, to manage coroutine execution, we can define a simple IAppDispatchers interface.

interface IAppDispatchers {
    val io: CoroutineDispatcher
    val main: CoroutineDispatcher
}

class AppDispatchers : IAppDispatchers {
    override val io: CoroutineDispatcher = Dispatchers.IO
    override val main: CoroutineDispatcher = Dispatchers.Main
}

In our production code, we inject the standard AppDispatchers. For our tests, however, we can create a TestAppDispatchers implementation that gives us full control over coroutine execution.

class TestAppDispatchers(private val testDispatcher: TestDispatcher) : IAppDispatchers {
    override val io: CoroutineDispatcher = testDispatcher
    override val main: CoroutineDispatcher = testDispatcher
}

From Contracts to Concrete Code

Fulfilling the Contracts with Implementations

The following code shows how these interfaces are implemented within common architectural patterns like MVC, MVP, or MVVM.

// The real implementation that talks to a network service
class UserRepositoryImpl(
    private val apiService: ProfileApiService,
    private val dispatchers: IAppDispatchers
) : IUserRepository {
    override suspend fun fetchUserProfile(): Result<User> =
        withContext(dispatchers.io) {
            // ... complex logic to call a remote service, handle errors, parse JSON,
            // and map them to our specific RepositoryError types.
        }
}

// The real implementation that talks to a network service
class UserRepositoryImpl(
    private val apiService: ProfileApiService,
    private val dispatchers: IAppDispatchers
) : IUserRepository {
    override suspend fun fetchUserProfile(): Result<User> =
        withContext(dispatchers.io) {
            // ... complex logic to call Retrofit, handle errors, parse JSON,
            // and map them to our specific RepositoryError types.
        }
}

// The real implementation with the business logic
class ProfileViewModelImpl(
    private val userRepository: IUserRepository,
    private val dispatchers: IAppDispatchers
) : IProfileViewModel() {
    override val profileStateFlow = MutableStatefulFlow<User>() // Downcast to `StateFlow` automatically

    // Public function to be called from the UI on initial load or retry
    override fun fetchProfile() {
        // By default, `viewModelScope.launch` uses `dispatchers.main`.
        // It's important to make sure that either your ViewModel or your Repository handles context switching!
        viewModelScope.launch {
            profileStateFlow.emitLoading()

            // The repository's suspend function handles its own context switching (to IO).
            // Once it completes, the coroutine resumes on the original dispatcher (main) to handle the result.
            userRepository.fetchUserProfile().fold(
                onSuccess = { user -> profileStateFlow.emitSuccess(user) },
                onFailure = { error ->
                    // The error is a RepositoryError, which our UI can use to show specific messages.
                    profileStateFlow.emitError(error)
                }
            )
        }
    }
}

Notice ProfileViewModelImpl depends on IUserRepository, not UserRepositoryImpl. This is the key that unlocks testability.

A Note on Private Functions and Abstractions

You might notice that ProfileViewModelImpl is simple enough not to need any internal helper functions. As logic grows, a common instinct is to create private functions to break up the work. However, when building on abstractions, we should favour internal or public functions.

When a consumer holds a reference to IProfileViewModel, they can only see the methods defined in that interface. Any other public or internal methods in the implementation are effectively hidden from that consumer, providing the same encapsulation as private would. The benefit of avoiding private is testability. It allows a test module to access helper functions without forcing us to use spies or other complex testing patterns.

Connecting the Pieces with a DI Framework

Finally, how do we connect our concrete implementations in the real app? With a Dependency Injection framework. Our team uses Koin, but this can easily be translated to any other DI solution like Dagger, Hilt, or Spring.

// In your DI module
val profileModule = module {
    // Assume IAppDispatchers is provided in another module (e.g., a core app module)
    single<IUserRepository> { UserRepositoryImpl(get(), get()) }
    factory<IProfileViewModel> { ProfileViewModelImpl(get(), get()) }
}

Handling State in the UI

The power of using a sealed class for state becomes apparent in the UI layer, where it can deterministically change its presentation.

// Hypothetical UI rendering logic
fun renderProfileScreen(viewModel: IProfileViewModel) {
    // Observe the state flow from the view model
    viewModel.profileStateFlow.collect { state ->
        when (state) {
            is State.Loading -> {
                showLoadingSpinner()
            }
            is State.Success -> {
                showUserProfile(state.data)
            }
            is State.Error -> {
                when (val error = state.error) {
                    is RepositoryError.NetworkError -> {
                        showNoInternetErrorView(onRetry = { viewModel.fetchProfile() })
                    }
                    is RepositoryError.ServerError -> {
                        showServerErrorView(errorCode = error.code)
                    }
                    else -> {
                        showGenericErrorView()
                    }
                }
            }
            is State.Created -> { /* Render initial empty state */ }
        }
    }
}

This creates a much better user (and developer!) experience than showing a single, generic error message for every possible failure.

Writing the Tests: Our Toolkit in Practice

Now that we have a testable architecture, let's finally write the tests.

The Anatomy of a Test: Given, When, Then

We follow the Given-When-Then pattern to keep our tests organized, readable, and consistent.

Given: Set up the initial state and preconditions. This is where you instantiate your class under test and prepare any mock dependencies.
When: Execute the action or method you want to test.
Then: Assert the expected outcome. Verify the final state or check that interactions with mocks happened correctly.

Test Doubles: Mocks, Fakes, and Spies

To test a unit in isolation, we must replace its real dependencies with "test doubles." The three main types we use are Mocks, Fakes, and Spies, each with a specific purpose. When choosing a test double, it's helpful to consider what you're trying to assert. Are you testing an interaction or a state change?

1. Mocks: For Verifying Interactions

A mock is a "dummy" object with no logic of its own; it only does what we tell it to for a specific test. Mocks are primarily used for stubbing (defining a specific return value for a function call) and verification (checking if a method on the dependency was called). They are ideal when you want to answer the question, "Did my code ask its dependency to do the right thing?"

// We use `mockk`, but the concept applies to Mockito, Jest, etc.
val mockRepository: IUserRepository = `mockk`()

// Stubbing: "When fetchUserProfile() is called, return this fake user"
coEvery { mockRepository.fetchUserProfile() } returns Result.success(fakeUser)

// Verification: "After my code runs, was fetchUserProfile() called exactly once?"
coVerify(exactly = 1) { mockRepository.fetchUserProfile() }

A key consideration with mocks is strictness. A strict mock (the default in mockk) will fail a test if any method is called that wasn't explicitly stubbed, which is safe. A relaxed mock (mockk(relaxed = true)) will return default empty values instead (e.g., Unit, 0, null, false), which can be convenient but may hide unexpected behaviour.

2. Fakes: For Asserting State Changes

A Fake is a lightweight, working implementation of a dependency that emulates its functionality with a simple alternative, like an in-memory List instead of a real database. Fakes are best when you need to assert the consequences of an action. They help answer the question, "After my code ran, did the state of a dependency change in the way I expected?" This is particularly useful for dependencies with complex internal logic or when you want to create reusable assertion logic. For example, a fake analytics tracker allows us to verify that a specific event was tracked with the correct data, which is much cleaner than just verifying that a trackEvent method was called.

First, we define the contract for our tracker:

interface AnalyticsTracker {
    fun trackEvent(eventName: String, attributes: Map<String, String>)
}

Next, we create the Fake for our tests. Notice that it contains its own verification methods, which makes our tests more expressive and readable.

class FakeAnalyticsTracker : AnalyticsTracker {
    private val trackedEvents = mutableListOf<Pair<String, Map<String, String>>>()

    override fun trackEvent(eventName: String, attributes: Map<String, String>) {
        trackedEvents.add(eventName to attributes)
    }

    // Reusable assertion logic lives inside the Fake
    fun verifyEventTracked(eventName: String, expectedAttributes: Map<String, String>) {
        val event = trackedEvents.find { it.first == eventName }
        assertNotNull(event, "Event '$eventName' was not tracked.")
        assertEquals(expectedAttributes, event.second, "Attributes for event '$eventName' did not match.")
    }

    fun verifyNoEventsTracked() {
        assertTrue(trackedEvents.isEmpty(), "Expected no events to be tracked, but found ${trackedEvents.size}.")
    }
}

Finally, we can use this Fake to write cleaner assertions in a test.

@Test
fun `fetchProfile should track success event when repository returns success`() {
    // Given
    val fakeAnalytics = FakeAnalyticsTracker()
    val mockRepo: IUserRepository = `mockk`() // Your other dependencies can still be mocks
    coEvery { mockRepo.fetchUserProfile() } returns Result.success(User(id = "user-123", ...))
    val viewModel = ProfileViewModelImpl(mockRepo, fakeAnalytics)

    // When
    viewModel.fetchProfile()

    // Then
    // The test is now much more readable by using the Fake's verification method
    fakeAnalytics.verifyEventTracked(
        eventName = "profile_load_success",
        expectedAttributes = mapOf("user_id" to "user-123")
    )
}

3. Spies: For Verifying Internal Logic (Use with Caution)

A Spy is a powerful but dangerous test double. It offers a hybrid approach by wrapping a real object, allowing its actual methods to be executed by default while still giving us the power to override or verify specific ones. This power comes with a significant trade-off: it breaks our Principle of Isolation and should be used with extreme caution.

The most legitimate use case for a spy is to verify that one public method on an object calls another method on the same object. This can often be a sign that a class has too many responsibilities and should be refactored, but it can be a valid testing scenario.

// Class to be tested
class DataProcessor(private val logger: Logger) {
    fun process(data: String): String {
        val formattedData = formatData(data) // Internal call we want to verify
        logger.log(formattedData)
        return formattedData
    }

    internal fun formatData(data: String): String {
        return "Processed: $data"
    }
}

// Test with a Spy
@Test
fun `process should call formatData`() {
    // Given
    val mockLogger: Logger = `mockk`(relaxed = true)
    val processorSpy = spyk(DataProcessor(mockLogger)) // Create a spy on the REAL object

    // When
    processorSpy.process("MyData")

    // Then
    // Verify that the internal 'formatData' method was called
    verify { processorSpy.formatData("MyData") }
}

However, it's critical to understand when not to use a spy. A common anti-pattern is using a spy to fake a dependency's behaviour. This turns a unit test into a slow and flaky integration test because it relies on the real implementation of other components.

// Anti-Pattern: Do NOT do this
@Test
fun `fetchProfile should call repository - BAD EXAMPLE`() {
    // Given
    // Spying on the ViewModel to fake one of its dependencies
    val spiedViewModel = spyk(ProfileViewModelImpl(UserRepositoryImpl(FakeApiService())))

    // Faking what the repository does by stubbing the spy
    coEvery { spiedViewModel.userRepository.fetchUserProfile() } returns Result.success(User("Test", ""))

    // When...
    // ...
}

In this bad example, the test is no longer isolated because it instantiates a real UserRepositoryImpl. The correct approach is to mock the IUserRepository dependency directly. As a rule, always prefer mocking external dependencies over spying on the class under test.

Unit Testing in Layers: Repositories and ViewModels

Recalling our Lego analogy from Part 1, we verify each "brick" in isolation. Once we're confident that each “layer” works correctly as a standalone unit, we can test how they're assembled.

We'll start with the Repository—our data-providing brick—before moving on to the ViewModel, which orchestrates the logic.

Testing the Repository Layer

Following our "Contract of Trust," it's time to test our UserRepositoryImpl. Here, we mock its dependency (the ProfileApiService) and verify that our repository correctly maps the network response and handles different outcomes. We assume the remote service will give us a Response or throw an IOException, and we test that our code handles those outcomes correctly.

class UserRepositoryImplTest {

    private val mockApiService: ProfileApiService = `mockk`()
    // The test dispatchers would be injected here as well
    private val testDispatchers = TestAppDispatchers(UnconfinedTestDispatcher())


    @Test
    fun `fetchUserProfile should return mapped User on successful network response`() = runTest {
        // Given: A successful response with a data transfer object (DTO)
        val userDto = UserDto(fullName = "John Doe", avatarUrl = "[http://example.com/avatar.png](http://example.com/avatar.png)")
        val successfulResponse = Response.success(userDto)
        val repository = UserRepositoryImpl(mockApiService, testDispatchers)
        coEvery { mockApiService.fetchUserProfile() } returns successfulResponse

        // When
        val result = repository.fetchUserProfile()

        // Then: Assert the result is success and the DTO was mapped to our domain model
        assertTrue(result.isSuccess)
        val user = result.getOrNull()
        assertNotNull(user)
        assertEquals("John Doe", user.name)
        assertEquals("[http://example.com/avatar.png](http://example.com/avatar.png)", user.avatar)

        // Verify we called the dependency
        coVerify { mockApiService.fetchUserProfile() }
    }

    @Test
    fun `fetchUserProfile should return ServerError on non-2xx network response`() = runTest {
        // Given: An error response from the server
        val errorBody = "Not Found".toResponseBody("text/plain".toMediaTypeOrNull())
        val errorResponse = Response.error<UserDto>(404, errorBody)
        val repository = UserRepositoryImpl(mockApiService, testDispatchers)
        coEvery { mockApiService.fetchUserProfile() } returns errorResponse

        // When
        val result = repository.fetchUserProfile()

        // Then: Assert the result is a failure and is our specific ServerError
        assertTrue(result.isFailure)
        val exception = result.exceptionOrNull()
        assertTrue(exception is RepositoryError.ServerError)
        assertEquals(404, exception.code)
    }

    @Test
    fun `fetchUserProfile should return NetworkError when api service throws IOException`() = runTest {
        // Given: The network call itself fails
        val networkException = IOException("No internet")
        val repository = UserRepositoryImpl(mockApiService, testDispatchers)
        coEvery { mockApiService.fetchUserProfile() } throws networkException

        // When
        val result = repository.fetchUserProfile()

        // Then: Assert the result is a failure and is our specific NetworkError
        assertTrue(result.isFailure)
        val exception = result.exceptionOrNull()
        assertTrue(exception is RepositoryError.NetworkError)
        assertEquals(networkException, exception.originalError)
    }
}

Testing the ViewModel Layer

Now that we have confidently tested our Repository brick, we can test the ProfileViewModelImpl. The goal here is not to re-test the Repository's logic but to verify that the ViewModel handles all of its internal logic, and every known output the Repository might throw at us. The more scenarios you have tests for, the higher your “coverage” is.

class ProfileViewModelImplTest {

    private val mockUserRepository: IUserRepository = `mockk`()
    private lateinit var testDispatchers: TestAppDispatchers
    private lateinit var viewModel: ProfileViewModelImpl

    // Helper to set up the ViewModel before each test
    private fun setupViewModel(testDispatcher: TestDispatcher) {
        testDispatchers = TestAppDispatchers(testDispatcher)
        viewModel = ProfileViewModelImpl(mockUserRepository, testDispatchers)
    }

    @Test
    fun `fetchProfile should emit Success when repository returns success`() = runTest {
        // Given
        setupViewModel(this.testScheduler) // Use the scheduler from runTest
        val fakeUser = User("Jane Doe", "jane.jpg")
        coEvery { mockUserRepository.fetchUserProfile() } returns Result.success(fakeUser)

        // When
        viewModel.fetchProfile()

        // Then
        viewModel.profileStateFlow.test {
            assertTrue(awaitItem() is State.Created)
            assertTrue(awaitItem() is State.Loading)
            val successState = awaitItem()
            assertTrue(successState is State.Success)
            assertEquals(fakeUser, successState.data)
            cancelAndIgnoreRemainingEvents()
        }
        coVerify(exactly = 1) { mockUserRepository.fetchUserProfile() }
    }

    @Test
    fun `fetchProfile should emit Error when repository returns a ServerError`() = runTest {
        // Given
        setupViewModel(this.testScheduler)
        val specificError = RepositoryError.ServerError(404)
        coEvery { mockUserRepository.fetchUserProfile() } returns Result.failure(specificError)

        // When
        viewModel.fetchProfile()

        // Then
        viewModel.profileStateFlow.test {
            assertTrue(awaitItem() is State.Created)
            assertTrue(awaitItem() is State.Loading)
            val errorState = awaitItem()
            assertTrue(errorState is State.Error)
            assertEquals(specificError, errorState.error)
            cancelAndIgnoreRemainingEvents()
        }
        coVerify(exactly = 1) { mockUserRepository.fetchUserProfile() }
    }

    @Test
    fun `fetchProfile should emit Error when repository returns a NetworkError`() = runTest {
        // Given
        setupViewModel(this.testScheduler)
        val specificError = RepositoryError.NetworkError(IOException("No connection"))
        coEvery { mockUserRepository.fetchUserProfile() } returns Result.failure(specificError)

        // When
        viewModel.fetchProfile()

        // Then
        viewModel.profileStateFlow.test {
            assertTrue(awaitItem() is State.Created)
            assertTrue(awaitItem() is State.Loading)
            val errorState = awaitItem()
            assertTrue(errorState is State.Error)
            assertEquals(specificError, errorState.error)
            cancelAndIgnoreRemainingEvents()
        }
        coVerify(exactly = 1) { mockUserRepository.fetchUserProfile() }
    }
}

By using our RepositoryError sealed class, our failure test no longer just checks "did it fail?"—it's checking "did it fail for the exact reason we expected?" This makes our tests incredibly precise.

Handling Asynchronicity in Tests

Effective asynchronous programming and concurrency testing is crucial for modern applications. While our examples use Kotlin Coroutines, the principles apply to Promises, Futures, or async/await as well. The key is to use libraries that give you control over the execution of asynchronous tasks.

runTest: This is the modern, standard tool for testing coroutines. It creates a special TestScope that runs your test code in a virtual time environment, making your async tests both extremely fast and deterministic.
Turbine: This is a small, invaluable library for testing Flows. As shown in the example above, flow.test { ... } provides a simple, structured way to assert each emission from a Flow in the correct order.

Case Study: Testing Complex Methods

Real-world methods often have more than one responsibility. For example, a method might fetch data, map it for the UI, and also map it for an analytics event.

Scenario: The ProfileViewModel needs to track an analytics event when the profile is loaded successfully.

Approach 1: Testing the Monolithic Method

First, look at the less ideal, 'monolithic' approach where the ViewModel does everything.

The Code:

class ProfileViewModel(
    private val userRepository: IUserRepository,
    private val analyticsTracker: AnalyticsTracker,
    private val dispatchers: IAppDispatchers
) {
    fun fetchProfileAndTrack() {
        //...
        userRepository.fetchUserProfile().onSuccess { user ->
            // Responsibility 1: Update UI State
            _uiState.emitSuccess(user)

            // Responsibility 2: Map data for analytics
            val attributes = mapOf(
                "user_id" to user.id,
                "user_name_length" to user.name.length.toString()
            )

            // Responsibility 3: Track the event
            analyticsTracker.trackEvent("profile_loaded", attributes)
        }
    }
}

The Test: This test is now responsible for verifying the UI state and the exact structure of the analytics event.

@Test
fun `fetchProfileAndTrack should emit Success and track event`() {
    // Given
    val user = User(id = "user-123", name = "Jane Doe")
    coEvery { mockUserRepository.fetchUserProfile() } returns Result.success(user)

    // When
    viewModel.fetchProfileAndTrack()

    // Then
    // 1. Verify the analytics call with the exact, hardcoded map
    val expectedAttributes = mapOf(
        "user_id" to "user-123",
        "user_name_length" to "8"
    )
    verify { mockAnalyticsTracker.trackEvent("profile_loaded", expectedAttributes) }

    // 2. Verify the UI state
    // ...
}

This test works, but it's brittle. This ViewModel test will break if the analytics requirements change, even though the UI state logic is unchanged, thus giving the test too many reasons to fail.

Approach 2: Refactoring for Testability (The Recommended Way)

The better approach is isolating the mapping logic into a small, testable unit.

The Refactored Code: Create a dedicated, single-responsibility mapper.

// A new, easily testable unit
class UserAnalyticsMapper {
    fun map(user: User): Map<String, String> {
        return mapOf(
            "user_id" to user.id,
            "user_name_length" to user.name.length.toString()
        )
    }
}

// The ViewModel now delegates the mapping
class ProfileViewModel(
    private val userRepository: IUserRepository,
    private val analyticsTracker: AnalyticsTracker,
    private val mapper: UserAnalyticsMapper, // New dependency
    private val dispatchers: IAppDispatchers
) {
    fun fetchProfileAndTrack() {
        //...
        userRepository.fetchUserProfile().onSuccess { user ->
            _uiState.emitSuccess(user)
            val attributes = mapper.map(user) // Just call the mapper
            analyticsTracker.trackEvent("profile_loaded", attributes)
        }
    }
}

The New, Simpler Tests:

First, we write a highly-focused test for our new mapper. It has no mocks and is extremely simple.

// Test for the mapper
class UserAnalyticsMapperTest {
    @Test
    fun `map should correctly transform user to analytics attributes`() {
        // Given
        val mapper = UserAnalyticsMapper()
        val user = User(id = "user-123", name = "Jane Doe")

        // When
        val attributes = mapper.map(user)

        // Then
        assertEquals(2, attributes.size)
        assertEquals("user-123", attributes["user_id"])
        assertEquals("8", attributes["user_name_length"])
    }
}

Now, the ViewModel test can be simpler. It no longer needs to know how the mapping is done; it only needs to verify that the components are called in the correct order.

// Simplified ViewModel test
// Assume mockMapper is created via 'val mockMapper: UserAnalyticsMapper = `mockk`(relaxed = true)'
@Test
fun `fetchProfileAndTrack should call mapper and track event on success`() {
    // Given
    val user = User(id = "user-123", name = "Jane Doe")
    coEvery { mockUserRepository.fetchUserProfile() } returns Result.success(user)
    // Note: Because mockMapper can be a relaxed mock, we don't need to stub
    // its 'map' function. It will return a default empty map, which is fine
    // for this test since we use any() in the trackEvent verification.

    // When
    viewModel.fetchProfileAndTrack()

    // Then
    // We only verify that our components were called correctly.
    // The test for the exact mapping logic lives in UserAnalyticsMapperTest.
    verify { mockMapper.map(user) }
    verify { mockAnalyticsTracker.trackEvent("profile_loaded", any()) }
}

By refactoring, we created two simpler, more focused tests that are more resilient to change and easier to understand. This is a core tenet of writing maintainable, long-lasting tests.

We've now seen how to architect our code for isolation and use test doubles to verify its behaviour. With these techniques, we can build robust components. The final part of this handbook will cover our specific team standards for ensuring consistency, readability, and long-term maintainability across our entire test suite.

On to Part 3 ->

Part 3: Standards, Style, and Troubleshooting

Gil Goldzweig Goldbaum — Tue, 26 Aug 2025 15:53:33 +0000

Welcome to the final part of our testing handbook. Having covered the "why" (our philosophy) and the "how" (our techniques), this section serves as a practical style guide. It outlines the specific standards we adhere to for naming, organization, and writing valuable tests, as well as how to solve common problems.

5 Qualities of a High-Value Unit Test

A test is only valuable if it increases our confidence in the code's correctness. Before diving into specific rules, remember that a good unit test has the following characteristics:

It Tests Behavior, Not Implementation: We test the what, not the how. A test should not care if you used a for loop or a forEach to iterate a list. It should only care that the final, observable outcome is correct. This makes tests resilient to refactoring.
It Has Clear Inputs and Outputs: A test provides a known set of inputs (the "Given" state, including mock responses) and asserts a known, predictable output (the "Then" state).
It Tests One Thing: Each test method should focus on a single scenario or logical path through the code. One test for the success case, another for the network error case, another for the server error case, etc. This makes it immediately obvious what broke when a test fails.
It is Fast and Deterministic: It must run quickly and produce the same result every single time. This is a direct result of following the Principle of Isolation.
It Values Quality Over Quantity: Coverage isn’t everything. While having many tests is good, they are only helpful if they can be trusted. Flaky or non-deterministic tests may increase coverage metrics, but they erode our confidence in the test suite and should be avoided or fixed immediately. A suite of 50 trusted tests is infinitely more valuable than 100 flaky ones.

The Style Guide: Writing Readable and Consistent Tests

To ensure our test suite is easy to navigate and understand, we adhere to the following style conventions.

Naming Conventions

The name of a test should clearly and concisely describe what it's testing. We follow a methodName_should_doSomething_when_conditionIsMet structure. Using backticks (`) in Kotlin allows us to write these descriptive, sentence-like function names.

Good Examples:

@Test
fun `fetchProfile should emit Success when repository returns success`() { ... }

@Test
fun `login should make one attempt and return AuthenticationError when credentials are invalid`() { ... }

Bad Examples:

@Test
fun testProfileLoading() { ... } // Too vague. What about it? Success? Failure?

@Test
fun profileSuccess() { ... } // Not a sentence. What action is being tested? What is the condition?

Test File Organization

To keep our project navigable, the location of test files must be consistent and predictable. The standard is to mirror the production code's package structure within the test source set.

If your production code is located at:
src/main/java/ca/skipthedishes/customer/profile/ProfileViewModelImpl.kt

The corresponding test class should be located at:
src/test/java/ca/skipthedishes/customer/profile/ProfileViewModelImplTest.kt

This simple rule makes it trivial to locate the tests for any given class and to see which classes might be missing tests.

Structuring Tests with JUnit: Best Practices for Organization

We use a standard set of tools to structure, organize, and execute our tests.

Structuring a Single Test Class

Within a single test class, we use annotations to reduce boilerplate and improve readability.

@Before: Marks a function that will run before each @Test method in the class. This is perfect for setting up common objects that every test needs, preventing code duplication.
@After: Marks a function that will run after each @Test method. This is useful for cleanup tasks, such as clearing mocks or closing resources, ensuring no state leaks between tests.
@Rule: A more powerful way to add reusable behaviour to every test, such as the InstantTaskExecutorRule for LiveData.

Example: Refactoring ProfileViewModelImplTest with @Before

class ProfileViewModelImplTest {

    private lateinit var viewModel: ProfileViewModelImpl
    private val mockUserRepository: IUserRepository = mockk()

    @Before
    fun setUp() {
        // This code runs before each test, providing a fresh instance
        viewModel = ProfileViewModelImpl(mockUserRepository)
    }

    @After
    fun tearDown() {
        // This runs after each test. Good for cleanup.
        unmockkAll() // Clears all mock states and recorded calls.
    }

    @Test
    fun `loadProfile should emit Success...`() = runTest {
        // Given
        coEvery { mockUserRepository.fetchUserProfile() } returns Result.success(...)

        // When - viewModel is already initialized!
        viewModel.loadProfile()

        // Then...
    }
}

This structure is cleaner, less repetitive, and clearly separates the setup (@Before), execution (@Test), and tear down (@After) phases of our tests.

Organizing Multiple Test Classes and Types

As our project grows, we need ways to group related tests.

@Suite for Grouping by Feature: To run all tests related to a single feature (e.g., "Authentication"), we can group them into a test suite. This is the preferred way to create logical groups over complex inheritance structures. You create an empty placeholder class and annotate it.

Example: Creating a Feature Test Suite

import org.junit.runner.RunWith
import org.junit.runners.Suite

@RunWith(Suite::class) // 1. Specify the Suite runner
@Suite.SuiteClasses( // 2. List all the test classes to include in this suite
    LoginViewModelTest::class,
    LogoutUseCaseTest::class,
    PasswordValidatorTest::class,
    TokenRepositoryTest::class
)
class AuthenticationFeatureTestSuite

Now, running AuthenticationFeatureTestSuite will execute all the tests from the listed classes.

@Category for Grouping by Type: The @Category annotation allows us to tag tests, which is extremely useful for separating fast unit tests from slow integration tests. This allows our CI pipeline to run them at different stages.

First, define marker interfaces for your categories:

interface FastTest
interface SlowTest

Then, apply these categories to your test classes or individual methods:

import org.junit.experimental.categories.Category

@Category(SlowTest::class)
class UserDatabaseTest {
    @Test
    fun `test something that hits a real database`() { ... }
}

class ProfileViewModelImplTest {
    @Test
    @Category(FastTest::class)
    fun `loadProfile should emit Success...`() { ... }
}

With this setup, we can configure our build system (e.g., Gradle) to run only tests marked with @Category(FastTest::class) on every pull request, and run the SlowTest suite nightly.

Advanced Topics and Troubleshooting

Ensuring Parallel Execution

For our CI/CD pipeline to be fast and efficient, tests must be able to run in parallel without interfering with each other. This requires that tests be completely independent and stateless. The most common source of flaky, non-parallelizable tests is shared mutable state, often found in companion objects.

Example: A Test that CANNOT Run in Parallel

// The problematic class with shared state
class UnstableAnalyticsTracker {
    companion object {
        var eventCount = 0
    }

    fun trackEvent() {
        eventCount++
    }
}

// The flaky tests
class UnstableAnalyticsTrackerTest {
    @Test
    fun `tracking one event should increment count to 1`() {
        val tracker = UnstableAnalyticsTracker()
        UnstableAnalyticsTracker.eventCount = 0 // Resetting state
        tracker.trackEvent()
        assertEquals(1, UnstableAnalyticsTracker.eventCount)
    }

    @Test
    fun `tracking two events should increment count to 2`() {
        val tracker = UnstableAnalyticsTracker()
        UnstableAnalyticsTracker.eventCount = 0 // Resetting state
        tracker.trackEvent()
        tracker.trackEvent()
        assertEquals(2, UnstableAnalyticsTracker.eventCount)
    }
}

If these two tests run in parallel, they will create a "race condition." Both tests try to modify eventCount at the same time, and the final result will be unpredictable. One test will interfere with the other.

Example: A Test that CAN Run in Parallel

The solution is to remove the shared state and use instances and dependency injection.

// The fixed, stable class
class StableAnalyticsTracker {
    var eventCount = 0 // State is now part of the instance

    fun trackEvent() {
        eventCount++
    }
}

// The robust tests
class StableAnalyticsTrackerTest {
    @Test
    fun `tracking one event should increment count to 1`() {
        val tracker = StableAnalyticsTracker() // A fresh instance for this test
        tracker.trackEvent()
        assertEquals(1, tracker.eventCount)
    }

    @Test
    fun `tracking two events should increment count to 2`() {
        val tracker = StableAnalyticsTracker() // A different fresh instance for this test
        tracker.trackEvent()
        tracker.trackEvent()
        assertEquals(2, tracker.eventCount)
    }
}

Because each test creates its own StableAnalyticsTracker instance, they are completely isolated and can run in parallel without issue. Our standard architecture of injecting dependencies achieves this goal by default.

Debugging Unit Tests: A Q&A

Here are solutions to some of the most common problems encountered when writing unit tests.

Q: Why is my test flaky (sometimes passes, sometimes fails)?

A: This is likely due to a race condition or unhandled asynchronicity. Ensure you are using runTest for any test involving coroutines. Check for any shared mutable state (companion object properties or module-level variables) that could be modified by multiple tests running in parallel.

Q: Why is my test setup so complicated?

A: A complex setup is often a "code smell" indicating that the class under test has too many responsibilities (violating the Single Responsibility Principle). Consider if the class can be refactored into smaller, more focused units, each with its own simple test. Review the "Case Study: Testing Complex Methods" section in Part 2 for an example of how to do this.

Q: Why is my test so slow?

A: You might be accidentally using a real dependency (like a real database or network call) instead of a mock or fake. Using Thread.sleep() is also an anti-pattern that causes slowness and flakiness. Double-check that all external dependencies are replaced with test doubles and use tools like runTest, which handle delays in virtual time. If the test must be slow (e.g., an integration test), categorize it with @Category(SlowTest::class) so it can be run separately from your fast unit tests.

Summary: Do's and Don'ts with Examples

To summarize the principles from this handbook, here is a quick reference to best practices and common anti-patterns to avoid when writing your unit tests.

✅ Do: Test public API behaviour.

@Test
fun `loadProfile should emit Success state with parsed User`() {
    // This is robust. It only cares about the final, observable state.
    // We can refactor the internals of ProfileViewModelImpl freely.
    coEvery { mockRepo.fetchUserProfile() } returns Result.success(...)

    viewModel.loadProfile()

    viewModel.uiState.test {
        // ... assert the final state is State.Success with the correct user data.
    }
}

❌ Don't: Test private implementation details. Testing private implementation is brittle; if the implementation changes, the test breaks even if the behaviour is correct.

@Test
fun `loadProfile should call private method 'parseUser'`() {
    // This is brittle. If we rename or remove parseUser, the test breaks
    // even if the final UI state is still correct.
    val viewModel = ...
    val spiedViewModel = spyk(viewModel)

    spiedViewModel.loadProfile()

    verify { spiedViewModel["parseUser"](any()) }
}

✅ Do: Mock all external dependencies.

@Test
fun `test with mocked repository`() {
    // This is fast, deterministic, and isolated.
    val mockRepository: IUserRepository = mockk()
    val viewModel = ProfileViewModelImpl(mockRepository)
    // ...
}

❌ Don't: Instantiate real dependencies in a unit test. Instantiating real dependencies makes tests slow, flaky, and not true unit tests.

@Test
fun `test with real repository`() {
    // This test now depends on a real ApiService, making it slow,
    // flaky (network might fail), and not a true unit test.
    val realRepository = UserRepositoryImpl(FakeApiService())
    val viewModel = ProfileViewModelImpl(realRepository)
    // ...
}

✅ Do: Use deterministic error types.

@Test
fun `should fail with specific error type`() {
    val specificError = RepositoryError.NetworkError(IOException())
    coEvery { mockRepo.fetchUserProfile() } returns Result.failure(specificError)

    // ...
    val errorState = awaitItem() as State.Error
    assertEquals(specificError, errorState.error) // ROBUST!
}

❌ Don't: Rely on Throwable.message strings. Checking for string literals is extremely brittle and will fail if the message is changed.

@Test
fun `should fail with specific message`() {
    coEvery { mockRepo.fetchUserProfile() } returns Result.failure(Exception("Network connection error"))

    // ...
    val errorState = awaitItem() as State.Error
    assertEquals("Network connection error", errorState.error.message) // BRITTLE!
}

Appendix: Platform-Specific Terminology

To help developers from other platforms, here’s a quick guide to some of the Android-specific terms and libraries used in this handbook and their common equivalents.

Coroutines (Kotlin)
- What it is: A language feature in Kotlin for managing long-running tasks concurrently in a non-blocking way.
- Platform Equivalents: async/await in C# and JavaScript, Promises in JavaScript, Futures in Scala, or Grand Central Dispatch in Swift.
ViewModel (Android Jetpack)
- What it is: A class designed to store and manage UI-related data in a lifecycle-conscious way, surviving configuration changes like screen rotations.
- Platform Equivalents: The concept is similar to a Presenter in MVP, a Controller in MVC, or a state management object in declarative UI frameworks like React or SwiftUI.
Compose (Android Jetpack)
- What it is: Android's modern, declarative UI toolkit for building native user interfaces.
- Platform Equivalents: SwiftUI (iOS), React/Vue/Angular (Web), Flutter.
Retrofit
- What it is: A type-safe HTTP client for Android and Java, used to make network requests.
- Platform Equivalents: Alamofire (iOS), Axios (Web/JS), HttpClient in .NET, or other standard HTTP clients in backend frameworks.
Mockk
- What it is: A mocking library for Kotlin, used to create test doubles (mocks, fakes, spies).
- Platform Equivalents: Mockito (Java/Kotlin), XCTest mocking features (iOS), Jest/Sinon.JS (Web/JS), Moq (.NET).

Conclusion

Writing good unit tests is an investment in quality and confidence. It's a discipline that pays for itself many times over in reduced bugs, easier maintenance, and the ability to evolve our application fearlessly. By embracing the Principle of Isolation as our core philosophy and adhering to these standards, we empower ourselves to build better software.

Key Takeaways:

Test in Isolation: This is our guiding star. It leads to fast, reliable tests that pinpoint bugs with precision.
Define Contracts: Program to interfaces. This is the architectural key that unlocks isolation and testability.
Create Deterministic Errors: Use sealed classes for your Throwable types to make error-state testing robust and specific.
Use Dependency Injection: Use DI to connect your components in the app and substitute mocks in your tests.
Be Structured: Use "Given, When, Then" and JUnit annotations like @Before, @Suite, and @Category to organize your tests effectively.
Know Your Toolkit: Master mockk for creating test doubles and runTest/Turbine for handling asynchronous code.

Happy testing!

How to perfect android animations using MotionLayout

Gil Goldzweig Goldbaum — Mon, 25 Aug 2025 18:05:59 +0000

Animations are fantastic. They make our apps feel interactive, increase engagement, and make our designers happy. But until recently, animations were a real pain point, which made it hard to deliver good looking animations, especially if we had a tight deadline.

Thankfully not anymore.

Google introduced a tool called MotionLayout, which makes it easy to create beautiful animations with a high level of flexibility.

So how can we use MotionLayout?

MotionLayout inherit from ConstraintLayout, which means we have all the power of constraints to define our states.

MotionLayout calculates the difference between our layout at the beginning and at the end to create our animation.

But just like any useful tool, we have the power to decide how things morph in between, and we can define what the trigger to our animations is.

Now I don't know what about you; I find the best way to learn something is with examples, so let's create one.

That's what we'll achieve — created using Android Studio 4.0 with the new MotionEditor.

What changes are we seeing?

The height of the toolbar and the color of the navigation icons adjust based on our scroll.
The size of our SearchView change to fit the new constraints between our images.
The title moves up and goes out of the screen.

Let's begin by creating our layout file.

I'll name our layout file "sample_collapsing_animation." We use MotionLayout as our root tag. Your's should look similar to this:

The attribute app:layoutDescription is used to attach our motion scene file, which we will create later.

Inside our layout, I want to define a Guideline. This will help us by acting as a natural singular point to change the height of our views.

To build our Toolbar, we're not going to use the component of Toolbar.
We are substituting it with a View to form the illusion of a Toolbar.

Doing that will result in us having a flat layout with all of the views exposed. Thus providing us the option to gain access to our title and morph it out of the screen, and the SearchView, later on, can use the icons as constraints.

Our SearchView has nothing special going on with it

Our final piece of the puzzle is our RecyclerView; it will act as a trigger for the animation.
Every time we scroll, the animation will update accordingly.

Our entire layout looks like this:

Cool. Once we have our layout file ready, we can start work on our animation or our MotionScene file.

To do that, we create an XML file and place it within the res/xml folder.

I'll call mine sample_collapsing_animation_scene.xml.

We use MotionScene as our root tag.

Inside the file, we define three things.

"constraintSetStart" which means how the animation looks at the
start (0%)
"constraintSetEnd" which means how the animation looks at the end
(100%)
Trigger or duration

Start state

For us to define how a view will behave in a ConstraintSet, we use the Constraint tag.

In our start constraint, we want the SearchView to have the following attributes.

Our title:

Our icons:

Currently, we need to create a CustomAttribute with the name of ColorFilter for us to change the tint of an image. It might change in the future, but for now, that's how we do it.

The entire start ConstraintSet:

End state

In our end constraint, our SearchView should now be.

Side constrained to our icons.
Top constrained to the top of the screen.

Our title moves above our toolbar.

For the entire movement, we change the layout_constraintGuide_begin of our Guideline.

The only thing we change in our icons is the color from black to white.

The entire end ConstraintSet:

Binding it all together

The last step of the puzzle is to create our transition.

Inside our Transition, we add the OnSwipe to set our RecyclerView's scroll as our trigger.

The entire file looks like this:

To finish our sample, I've filled the RecyclerView with some dummy list data, and this is our final result.

For conclusion,
MotionLayout is an excellent tool. It gives us the power to create great experiences, beautiful animations, and enjoy the process thanks to the Android Studio team that created the MotionEditor.

Big thanks Sivakumar Chellamuthu for letting me use your creation as an example; you can check out his project here

The code for the sample is on my GitHub, and you can check them out here.
While you're there, you can also take a look at some of my other projects.