Unit Testing with JUnit, Mockito, MockK and Robolectric

The test pyramid is a way of allocating testing effort across tiers that trade off speed, isolation and confidence. Cheap, fast, narrowly scoped tests should vastly outnumber expensive, slow, broadly scoped ones, because a suite dominated by slow tests is a suite nobody runs often:

Android’s own testing guidance calls the bottom two tiers local tests (they run entirely on the JVM that runs Gradle, whether that is a developer’s laptop or a CI runner) and the top tier instrumented tests (they run inside an Android process, on a device or emulator, driven by adb). Local tests are one to two orders of magnitude faster to start and run because there is no APK to install and no device to boot; the trade-off is that plain local tests (the second tier) cannot touch anything that only exists in the real Android framework — Context, Looper, resources, SharedPreferences, a live View hierarchy — because the android.jar that JVM tests compile and run against contains only method stubs that throw RuntimeException("Stub!") if called. Robolectric (the third tier) removes that restriction by providing working, JVM-hosted implementations of the framework classes, at the cost of being slower and less faithful than a real device. This page’s structure follows the pyramid bottom-up: fakes and mocks and pure JVM tests first, Robolectric last.

Every Gradle Android module has two parallel test source sets, chosen by where the class under test needs to run:

src/test/ dependencies are declared with testImplementation; src/androidTest/ dependencies use androidTestImplementation. TrailMate’s module-level build.gradle.kts declares the unit-testing dependencies this page covers:

See Android Developers — Test apps on Android. Mockito on the JVM test source set needs no extra runner because it operates purely through bytecode manipulation; it only becomes mockito-android (a separate artifact whose mock maker generates subclasses with ByteBuddy’s Android support, since the JVM’s instrumentation agent isn’t available on ART) when mocking classes from androidTestImplementation instrumented tests. This page never needs mockito-android because Robolectric tests are still src/test/, plain-JVM tests — Mockito’s default inline mock maker (described below) is sufficient there too.

Android’s default local-test runner is still JUnit 4, and Robolectric, androidx.test, and most third-party Android test libraries are built against it. A JUnit 4 test class is a plain class whose test methods are annotated @Test; @Before/@After run around each test, @BeforeClass/@AfterClass run once per class:

See Android Developers — Fundamentals of testing. JUnit 4 test classes on Android normally run under the default JUnit4 runner (implicit) or, for framework-touching tests, @RunWith(AndroidJUnit4::class) from androidx.test.ext.junit.runners, which dispatches to Robolectric automatically when the test is running under src/test/ with the Robolectric Gradle plugin applied, or to the on-device instrumentation runner under src/androidTest/.

JUnit 5 (Jupiter) is supported on Android only through the third-party de.mannodermaus.android-junit5 Gradle plugin, because AGP’s built-in unit-test task still expects a JUnit 4-shaped runner:

See android-junit5 — Android JUnit 5 Gradle plugin.

See android-junit5 — Android JUnit 5 Gradle plugin.

JUnit 5’s parameterized tests, nested test classes (@Nested) and extension model (@ExtendWith) are genuinely nicer than JUnit 4’s @RunWith(Parameterized::class) and TestRule, but Robolectric’s official JUnit 5 support is younger and less battle-tested than its JUnit 4 support, and most Android sample code, androidx.test rules and library test-fixtures still assume JUnit 4. For TrailMate, plain unit tests with no framework dependency (model logic, mappers, use cases) are reasonable candidates for JUnit 5; anything using Robolectric or androidx.test rules stays on JUnit 4 for compatibility. See GitHub — android-junit5.

A test double is any object substituted for a real collaborator in a test. Two kinds cover almost every case in TrailMate:

TrailMate uses a hand-written fake, FakeTrailRepository, for most TrailListViewModel tests, because the ViewModel cares about the shape and evolution of Flow<List<Trail>> over time — something a fake’s real MutableStateFlow expresses naturally and a mock’s stubbed single return value does not:

See Android Developers — Test doubles. OfflineFirstTrailRepositoryTest itself, one layer down, tests the real repository, so it fakes or mocks TrailDao and TrailApi instead — TrailDao is small enough to fake with an in-memory list, while TrailApi (a Retrofit interface with a single suspend method per endpoint) is easiest to mock, since the test only cares that the repository called it with the right arguments and handled its result or its exception.

Mockito generates a mock at runtime for any interface or open class and lets a test stub its methods and verify how it was called. Plain Mockito’s Java-oriented API (Mockito.mock(Foo::class.java), Mockito.`when(foo.bar()).thenReturn(…​)) is awkward in Kotlin — `when is a keyword, and Mockito’s Java API cannot stub methods returning platform types cleanly. mockito-kotlin wraps the same engine in idiomatic Kotlin extension functions:

See Mockito — mockito-kotlin API documentation.

mock() creates the mock; whenever(…​).thenReturn(…​) is mockito-kotlin’s Kotlin-friendly replacement for `Mockito.when. doReturn(…​).whenever(mock).method() (and doThrow/doAnswer) exist as an alternative stubbing order for the rare case where the real whenever(mock.method()) call itself would throw — for example stubbing a spy() of a real object whose method has side effects, or a final method that a stricter mock maker would otherwise reject before the stub is even installed. Because refresh is a suspend function, both whenever and doThrow work on it unchanged: Mockito treats a Kotlin suspend function as an ordinary function taking a hidden Continuation parameter, and mockito-kotlin’s stubbing functions are themselves marked `suspend where needed so the call composes naturally inside runTest.

MockK is a mocking library written for Kotlin from the start, and is the more natural fit for suspend functions, object`s and extension functions than retrofitting Mockito. TrailMate’s tests may use either consistently within a module; mixing both in the same test class is possible but adds noise for no benefit. The MockK equivalent of the `OfflineFirstTrailRepositoryTest above:

See MockK — Mocking library for Kotlin.

coEvery/coVerify are MockK’s suspend-aware equivalents of every/verify; plain every/verify only work on non-suspend functions. A relaxed mock (mockk<T>(relaxed = true), or relaxUnitFun = true for a mock whose Unit-returning functions alone should auto-answer) returns sensible defaults (empty collections, zero, false, another relaxed mock) for every unstubbed call instead of throwing, which trims boilerplate for collaborators like trailDao where a test only cares about one or two specific calls. mockkStatic and mockkObject extend mocking to Kotlin object`s and top-level/extension functions that neither Mockito nor a constructor-injected fake can reach — for example stubbing a top-level `Clock.now()-style function used directly inside RecordHikeService:

See MockK — Mocking library for Kotlin.

Reaching for mockkStatic is a signal worth noticing: a dependency that can only be swapped by intercepting a static/top-level call was not injected in the first place, and a constructor parameter or Hilt binding (see Dependency Injection with Hilt, Dagger and Koin) is usually the better long-term fix. See MockK.

TrailListViewModel and OfflineFirstTrailRepository are built on coroutines and Flow (Coroutines Basics, Flows), so testing them means controlling virtual time rather than sleeping the test thread. kotlinx-coroutines-test’s `runTest { } builder runs its body in a TestScope backed by a TestCoroutineScheduler, skips delay() calls in virtual time for every coroutine that runs on a TestDispatcher sharing that scheduler, and fails the test if a launched child coroutine is still active when the block ends — catching the leaked-coroutine bugs a plain runBlocking test would silently hide. It does not replace Dispatchers.Default or Dispatchers.IO: work that code under test moves there with withContext(Dispatchers.IO) runs on real threads, and its delays are real. That is why TrailMate’s repositories and use cases take a CoroutineDispatcher constructor parameter, which a test sets to a StandardTestDispatcher(testScheduler):

See kotlinx.coroutines — runTest.

runTest defaults to a StandardTestDispatcher: coroutines it launches are queued, not run, and runTest does not idle between statements. Queued work runs only when the test body suspends (for example on join(), awaitItem() or a delay()), when it calls advanceUntilIdle(), advanceTimeBy(…​) or runCurrent() explicitly, or when the body finishes. This matches how a real dispatcher behaves — work is scheduled, not run inline — and is the right default for asserting intermediate states (a loading state before a result arrives). An UnconfinedTestDispatcher instead runs a launched coroutine eagerly, up to its first suspension point, before the launching call even returns; it trades that realism for less boilerplate when a test only cares about the final state and would otherwise need an extra advanceUntilIdle() after every viewModel.load() call.

TrailListViewModel launches work in viewModelScope, which is hard-wired to Dispatchers.Main. A test needs Dispatchers.setMain(…​) before creating the ViewModel and Dispatchers.resetMain() afterwards, wrapped in a reusable TestRule so every ViewModel test gets it automatically and cannot forget to reset it:

See Android Developers — Testing Kotlin coroutines on Android.

Robolectric provides shadow implementations of framework classes — Activity, Context, View, SharedPreferences, Looper, and hundreds more — that run inside the same JVM process as the test, giving src/test/ tests access to real (if simplified) framework behaviour without booting an emulator. This is the pyramid’s second tier: still much faster than an instrumented test, at the cost of being slower than a plain unit test and occasionally diverging from real-device behaviour on framework edge cases.

OfflineFirstTrailRepository ultimately depends on TrailApi, a Retrofit interface (Networking with Retrofit, OkHttp and Ktor). Mocking TrailApi directly (as in the Mockito and MockK sections above) verifies the repository’s own logic in isolation, but never exercises the real Retrofit/OkHttp/JSON-parsing stack. mockwebserver3, from the same OkHttp project, runs a real local HTTP server the test controls, so a TrailApiTest can point a real Retrofit instance at it and assert on the resulting requests and parsed responses end-to-end:

See okhttp — MockWebServer.

server.takeRequest() hands back the actual RecordedRequest the server received, so a test can assert on the path, headers, method and body sent — catching a wrong query-parameter name or a missing Content-Type that a mocked TrailApi would never surface. MockResponse.Builder queues one canned response per enqueue(…​) call (OkHttp 5’s builder API; mockwebserver3 is the mockwebserver artifact rewritten in Kotlin for OkHttp 4+, with a small API shift from the older MockResponse().setResponseCode(…​) mutation style). See GitHub — OkHttp MockWebServer.

JaCoCo instruments compiled bytecode to record which lines and branches a test run actually exercised, then renders that as an HTML/XML report. AGP wires JaCoCo into the testDebugUnitTest task automatically once enabled:

See Android Developers — View code coverage reports.

With enableUnitTestCoverage = true, AGP registers create<Variant>UnitTestCoverageReport (here createDebugUnitTestCoverageReport), which writes its report to build/reports/coverage/test/debug/, and it records the unit-test execution data at build/outputs/unit_test_code_coverage/debugUnitTest/testDebugUnitTest.exec — the file the custom task above, or a jacococli.jar report step in CI, reads. The directory arguments use layout.buildDirectory.dir(…​)/.file(…​) providers rather than a string built from buildDirectory, so the paths resolve against the real build directory (a literal ${…​} inside a Kotlin string would not be expanded and would leave the report empty).

Only the two JVM tiers of the pyramid — plain unit tests and Robolectric tests, both run by testDebugUnitTest — contribute to this report by default; instrumented tests write their own .ec execution data under connectedDebugAndroidTest and need a separate merge step to combine both into one coverage number, which is why coverage percentages quoted from CI are usually the unit-test figure alone unless the pipeline explicitly merges both. A coverage percentage is a proxy for "this code ran during a test", not for "this code is correct" — a test with no assertions still counts as full coverage of the lines it executes — so JaCoCo numbers are best used to find untested code (a class or branch at 0%) rather than as a quality target to chase past a reasonable threshold. irurueta-android-glutils’s own CI pipeline (.github/workflows/main.yml`) runs ./gradlew clean test connectedAndroidTest and converts the resulting JaCoCo execution data with a jacococli.jar from a JaCoCo 0.8.13 distribution it keeps committed in the repository (jacoco-0.8.13/) for its SonarQube scan, the same shape of pipeline TrailMate’s own CI would use — covered in full on CI/CD with GitHub Actions.