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 stagingCommon 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.