Hilt Android Testing: Dependency Injection in Unit and Instrumented Tests

Hilt Android Testing: Dependency Injection in Unit and Instrumented Tests

Hilt is Android's recommended dependency injection framework. Testing with Hilt requires understanding how to inject test doubles (fakes/mocks) instead of real implementations, how to replace production modules in specific tests, and how to set up the test runner correctly for instrumented tests.

This guide covers Hilt testing patterns for both unit tests (JVM) and instrumented tests (device/emulator).

Setup

// app/build.gradle.kts
dependencies {
    // Hilt runtime
    implementation("com.google.dagger:hilt-android:2.51")
    kapt("com.google.dagger:hilt-android-compiler:2.51")

    // Hilt testing
    testImplementation("com.google.dagger:hilt-android-testing:2.51")
    kaptTest("com.google.dagger:hilt-android-compiler:2.51")
    androidTestImplementation("com.google.dagger:hilt-android-testing:2.51")
    kaptAndroidTest("com.google.dagger:hilt-android-compiler:2.51")

    // Fragment testing (for Hilt Fragment tests)
    debugImplementation("androidx.fragment:fragment-testing:1.7.0")
}

Instrumented Tests with @HiltAndroidTest

Test Runner Configuration

// app/src/androidTest/java/com/example/CustomTestRunner.kt
class CustomTestRunner : AndroidJUnitRunner() {
    override fun newApplication(cl: ClassLoader?, name: String?, context: Context?): Application {
        return super.newApplication(cl, HiltTestApplication::class.java.name, context)
    }
}
// app/build.gradle.kts
android {
    defaultConfig {
        testInstrumentationRunner = "com.example.CustomTestRunner"
    }
}

Basic @HiltAndroidTest

@HiltAndroidTest
class OrderRepositoryTest {

    @get:Rule
    var hiltRule = HiltAndroidRule(this)

    @Inject
    lateinit var orderRepository: OrderRepository

    @Before
    fun init() {
        hiltRule.inject()
    }

    @Test
    fun getOrder_returnsCorrectOrder() {
        val order = orderRepository.getOrder("ORD-123")
        assertThat(order).isNotNull()
        assertThat(order?.id).isEqualTo("ORD-123")
    }
}

HiltAndroidRule manages the test component lifecycle. Call hiltRule.inject() before accessing injected fields.

Replacing Modules with @TestInstallIn

The most important pattern: replace a production module with a test module that provides fakes.

Production Module

@Module
@InstallIn(SingletonComponent::class)
object NetworkModule {
    @Provides
    @Singleton
    fun provideApiService(): OrderApiService {
        return Retrofit.Builder()
            .baseUrl("https://api.example.com")
            .build()
            .create(OrderApiService::class.java)
    }
}

Test Module Replacement

// src/androidTest/java/com/example/FakeNetworkModule.kt
@Module
@TestInstallIn(
    components = [SingletonComponent::class],
    replaces = [NetworkModule::class]  // replaces the production module
)
object FakeNetworkModule {
    @Provides
    @Singleton
    fun provideApiService(): OrderApiService {
        return FakeOrderApiService()  // returns fake for all tests in this module
    }
}
class FakeOrderApiService : OrderApiService {
    private val orders = mutableMapOf<String, Order>()

    fun addOrder(order: Order) {
        orders[order.id] = order
    }

    override suspend fun getOrder(id: String): OrderResponse {
        return orders[id]?.toResponse()
            ?: throw HttpException(Response.error<OrderResponse>(404, "".toResponseBody()))
    }

    override suspend fun createOrder(request: CreateOrderRequest): OrderResponse {
        val order = Order(
            id = "ORD-${System.currentTimeMillis()}",
            amount = request.amount,
            status = OrderStatus.PENDING
        )
        orders[order.id] = order
        return order.toResponse()
    }
}

Per-Test Module Override with @BindValue

For replacing individual bindings without a full module:

@HiltAndroidTest
class CheckoutViewModelTest {

    @get:Rule
    var hiltRule = HiltAndroidRule(this)

    // Replace a specific binding just for this test class
    @BindValue
    @JvmField
    val paymentService: PaymentService = FakePaymentService()

    @BindValue
    @JvmField
    val analyticsTracker: AnalyticsTracker = NoOpAnalyticsTracker()

    @Inject
    lateinit var viewModel: CheckoutViewModel

    @Before
    fun setUp() {
        hiltRule.inject()
    }

    @Test
    fun checkout_success_updatesState() {
        (paymentService as FakePaymentService).setPaymentResult(PaymentResult.Success)

        viewModel.checkout(cartId = "CART-1", amount = 49.99)

        assertThat(viewModel.state.value).isEqualTo(CheckoutState.Success)
    }

    @Test
    fun checkout_failure_showsError() {
        (paymentService as FakePaymentService).setPaymentResult(
            PaymentResult.Failure("Card declined")
        )

        viewModel.checkout(cartId = "CART-1", amount = 49.99)

        assertThat(viewModel.state.value).isInstanceOf(CheckoutState.Error::class.java)
        assertThat((viewModel.state.value as CheckoutState.Error).message)
            .contains("Card declined")
    }
}

Testing ViewModels with Hilt

ViewModel with Hilt Injection

@HiltViewModel
class OrderListViewModel @Inject constructor(
    private val orderRepository: OrderRepository,
    private val analyticsTracker: AnalyticsTracker
) : ViewModel() {

    private val _orders = MutableStateFlow<List<Order>>(emptyList())
    val orders: StateFlow<List<Order>> = _orders.asStateFlow()

    private val _isLoading = MutableStateFlow(false)
    val isLoading: StateFlow<Boolean> = _isLoading.asStateFlow()

    fun loadOrders() {
        viewModelScope.launch {
            _isLoading.value = true
            try {
                _orders.value = orderRepository.getAllOrders()
                analyticsTracker.track("orders_loaded", mapOf("count" to _orders.value.size))
            } finally {
                _isLoading.value = false
            }
        }
    }
}

ViewModel Unit Test (no Hilt, just constructor injection)

For fast JVM unit tests, don't use Hilt at all — just construct the ViewModel directly:

// src/test/java/com/example/OrderListViewModelTest.kt
class OrderListViewModelTest {

    @get:Rule
    val mainDispatcherRule = MainDispatcherRule()

    private val fakeRepository = FakeOrderRepository()
    private val fakeTracker = FakeAnalyticsTracker()
    private lateinit var viewModel: OrderListViewModel

    @Before
    fun setUp() {
        viewModel = OrderListViewModel(fakeRepository, fakeTracker)
    }

    @Test
    fun loadOrders_success_updatesOrders() = runTest {
        val expectedOrders = listOf(
            Order("ORD-1", amount = 50.0, status = OrderStatus.COMPLETED),
            Order("ORD-2", amount = 30.0, status = OrderStatus.PENDING),
        )
        fakeRepository.setOrders(expectedOrders)

        viewModel.loadOrders()

        assertThat(viewModel.orders.value).isEqualTo(expectedOrders)
        assertThat(viewModel.isLoading.value).isFalse()
    }

    @Test
    fun loadOrders_tracksAnalytics() = runTest {
        fakeRepository.setOrders(listOf(Order("ORD-1", amount = 10.0, status = OrderStatus.COMPLETED)))

        viewModel.loadOrders()

        assertThat(fakeTracker.trackedEvents).containsKey("orders_loaded")
        assertThat(fakeTracker.trackedEvents["orders_loaded"]?.get("count")).isEqualTo(1)
    }
}
// TestDispatchers.kt
class MainDispatcherRule(
    private val testDispatcher: TestDispatcher = UnconfinedTestDispatcher()
) : TestWatcher() {
    override fun starting(description: Description?) {
        Dispatchers.setMain(testDispatcher)
    }
    override fun finished(description: Description?) {
        Dispatchers.resetMain()
    }
}

Testing Fragments with Hilt

@HiltAndroidTest
class OrderListFragmentTest {

    @get:Rule(order = 0)
    var hiltRule = HiltAndroidRule(this)

    @get:Rule(order = 1)
    var activityRule = ActivityScenarioRule(HiltTestActivity::class.java)

    @BindValue
    @JvmField
    val viewModel: OrderListViewModel = mockk(relaxed = true)

    @Before
    fun setUp() {
        hiltRule.inject()
    }

    @Test
    fun orderList_displaysOrders() {
        val orders = listOf(
            Order("ORD-1", amount = 50.0, status = OrderStatus.COMPLETED),
            Order("ORD-2", amount = 30.0, status = OrderStatus.PENDING),
        )
        every { viewModel.orders } returns MutableStateFlow(orders)
        every { viewModel.isLoading } returns MutableStateFlow(false)

        launchFragmentInHiltContainer<OrderListFragment>()

        onView(withText("ORD-1")).check(matches(isDisplayed()))
        onView(withText("ORD-2")).check(matches(isDisplayed()))
    }

    @Test
    fun orderList_showsLoadingIndicator_whileLoading() {
        every { viewModel.orders } returns MutableStateFlow(emptyList())
        every { viewModel.isLoading } returns MutableStateFlow(true)

        launchFragmentInHiltContainer<OrderListFragment>()

        onView(withId(R.id.progress_indicator)).check(matches(isDisplayed()))
    }
}
// Test utilities for launching fragments in Hilt
inline fun <reified T : Fragment> launchFragmentInHiltContainer(
    fragmentArgs: Bundle? = null,
    crossinline action: Fragment.() -> Unit = {}
) {
    val startActivityIntent = Intent.makeMainActivity(
        ComponentName(ApplicationProvider.getApplicationContext(),
            HiltTestActivity::class.java)
    )

    ActivityScenario.launch<HiltTestActivity>(startActivityIntent).onActivity { activity ->
        val fragment = activity.supportFragmentManager.fragmentFactory.instantiate(
            Preconditions.checkNotNull(T::class.java.classLoader),
            T::class.java.name
        )
        fragment.arguments = fragmentArgs
        activity.supportFragmentManager.beginTransaction()
            .add(android.R.id.content, fragment, "")
            .commitNow()
        fragment.action()
    }
}

Testing Room Database with Hilt

@Module
@TestInstallIn(
    components = [SingletonComponent::class],
    replaces = [DatabaseModule::class]
)
@InstallIn(SingletonComponent::class)
object TestDatabaseModule {
    @Provides
    @Singleton
    fun provideInMemoryDatabase(@ApplicationContext context: Context): AppDatabase {
        return Room.inMemoryDatabaseBuilder(context, AppDatabase::class.java)
            .allowMainThreadQueries()  // for tests only
            .build()
    }

    @Provides
    fun provideOrderDao(database: AppDatabase): OrderDao {
        return database.orderDao()
    }
}
@HiltAndroidTest
@SmallTest
class OrderDaoTest {

    @get:Rule
    var hiltRule = HiltAndroidRule(this)

    @Inject
    lateinit var database: AppDatabase

    @Inject
    lateinit var orderDao: OrderDao

    @Before
    fun setUp() {
        hiltRule.inject()
    }

    @After
    fun tearDown() {
        database.close()
    }

    @Test
    fun insertAndRetrieveOrder() = runTest {
        val order = OrderEntity(id = "ORD-1", amount = 50.0, status = "completed")
        orderDao.insert(order)

        val retrieved = orderDao.getById("ORD-1")
        assertThat(retrieved).isEqualTo(order)
    }

    @Test
    fun getAll_returnsAllOrders() = runTest {
        val orders = (1..5).map { i ->
            OrderEntity(id = "ORD-$i", amount = i * 10.0, status = "completed")
        }
        orders.forEach { orderDao.insert(it) }

        val all = orderDao.getAll()
        assertThat(all).hasSize(5)
    }
}

Fake vs Mock for Hilt Tests

Use fakes (hand-written implementations) for repositories and services that need stateful behavior:

class FakeOrderRepository : OrderRepository {
    private val orders = mutableListOf<Order>()

    fun addOrder(order: Order) { orders.add(order) }
    fun clear() { orders.clear() }

    override suspend fun getAllOrders() = orders.toList()
    override suspend fun getOrder(id: String) = orders.find { it.id == id }
}

Use MockK for simpler collaborators where you just need to verify calls:

@BindValue
@JvmField
val analyticsTracker: AnalyticsTracker = mockk(relaxed = true)

// Verify interaction in test:
verify { analyticsTracker.track("checkout_started", any()) }

CI Test Pyramid for Hilt

Structure tests to keep CI fast:

Unit tests (JVM, no Hilt)         — run on every PR, < 1 min
  ViewModels, repositories, business logic
  Use constructor injection directly
  
Component tests (Hilt, emulator)  — run on every PR, 5-10 min
  DAO tests with in-memory Room
  Fragment tests with @BindValue mocks
  
E2E tests (Hilt, real dependencies) — run on merge to main, 20-30 min
  Full stack with real API endpoints
  Use @TestInstallIn to point at staging

Common Pitfalls

Order of rules: HiltAndroidRule must have order = 0 when combined with other rules like ActivityScenarioRule. Hilt setup must happen before Activity launch.

Forgetting hiltRule.inject(): Fields annotated @Inject are null until you call hiltRule.inject() in @Before. This is the most common Hilt test bug.

@TestInstallIn affects all tests in the module: If you use @TestInstallIn in androidTest, it replaces the module for every instrumented test. Use @BindValue for per-test overrides.

Main dispatcher in ViewModel tests: Always set the main dispatcher in unit tests. Without MainDispatcherRule, coroutines started in ViewModel don't complete synchronously and tests become flaky.

Summary

Hilt testing requires two different strategies: fast JVM unit tests that bypass Hilt entirely (construct with constructor injection), and instrumented tests that use @HiltAndroidTest + @BindValue/@TestInstallIn to inject fakes. Use @TestInstallIn to replace entire modules across all instrumented tests (database, network), and @BindValue when you need per-test control. The test pyramid: most tests should be JVM unit tests that never touch Hilt machinery, with a smaller number of instrumented tests that validate the Hilt wiring.

Read more

Start now free