單元測試
本指南說明如何使用 Koin 編寫 JVM 單元測試:在每個測試中啟動與停止容器、檢索執行個體、覆寫定義,以及使用 Mock 取代相依性。這是各項測試技術的參考指引;特定平台頁面(Android 檢測測試、Compose、Ktor)僅涵蓋該平台特有的內容。你應該先了解如何啟動 Koin 以及宣告定義。
相依性
將 koin-test 以及對應你 JUnit 版本的構件新增至測試相依性中:
dependencies {
testImplementation("io.insert-koin:koin-test")
// 擇一使用
testImplementation("io.insert-koin:koin-test-junit4")
testImplementation("io.insert-koin:koin-test-junit5")
}版本資訊來自 Koin BOM,請參閱 Gradle 設定。koin-test 不相依於任何 Mock 程式庫:你可以直接插入 Mockito、MockK 或任何其他程式庫(請參閱使用 declareMock 進行 Mock)。
KoinTest
在你的測試類別中實作 KoinTest。這會讓該類別成為一個 KoinComponent,因此 get() 和 by inject() 可以直接在測試中使用:
import org.koin.test.KoinTest
import org.koin.test.get
import org.koin.test.inject
class UserServiceTest : KoinTest {
// 首次存取時解析
private val userService: UserService by inject()
@Test
fun `finds a known user`() {
startKoin { modules(appModule) }
val repository = get<UserRepository>()
assertNotNull(userService.findUser("alice"))
assertSame(repository, userService.repository)
stopKoin()
}
}KoinTest 使用全域 Koin 上下文(由 startKoin 建立的上下文)。它不適用於由 Application 類別啟動 Koin 的 Android 檢測測試:請參閱 Android 檢測測試。
為每個測試啟動與停止 Koin
每個測試都應該啟動自己的容器,並在結束時停止它。若容器保持執行狀態,會導致下一次呼叫 startKoin 時拋出 KoinApplicationAlreadyStartedException 失敗,並在測試之間洩漏執行個體。
載入與你的應用程式相同的配置:
class UserServiceTest : KoinTest {
@Before
fun before() {
startKoin { modules(appModule) }
}
@After
fun after() {
stopKoin()
}
}使用型別化 API 啟動應用程式的 @KoinApplication 類別:
import org.koin.plugin.module.dsl.startKoin
class UserServiceTest : KoinTest {
@Before
fun before() {
startKoin<MyApp>()
}
@After
fun after() {
stopKoin()
}
}若只要載入部分模組,可在一般的 startKoin { } 內使用 module<DataModule>() 或 modules(DataModule::class, CacheModule::class)。
class UserServiceTest : KoinTest {
@Before
fun before() {
startKoin { modules(appModule) }
}
@After
fun after() {
stopKoin()
}
}若要在不編寫 @After 的情況下停止 Koin,可以繼承 AutoCloseKoinTest 或實作 ClosingKoinTest。兩者都會在每個測試結束後呼叫 stopKoin()。JUnit 5 版本位於 org.koin.test.junit5 中。
下方的 JUnit Rule 與 Extension 可以替你處理啟動與停止,是更簡短的選擇。
JUnit 4:KoinTestRule
KoinTestRule(來自 koin-test-junit4)會在每個測試之前啟動 Koin,並在測試後停止它:
import org.koin.test.KoinTestRule
class UserServiceTest : KoinTest {
@get:Rule
val koinTestRule = KoinTestRule.create {
printLogger()
modules(appModule)
}
private val userService: UserService by inject()
@Test
fun `finds a known user`() {
assertNotNull(userService.findUser("alice"))
}
}該 Lambda 運算式是一般的 KoinApplication 宣告:你在 startKoin { } 中編寫的所有內容都可以在這裡使用。搭配註解時,請使用 withConfiguration<MyApp>() 載入你的應用程式:
import org.koin.plugin.module.dsl.withConfiguration
@get:Rule
val koinTestRule = KoinTestRule.create {
withConfiguration<MyApp>()
}如果在測試開始時已有 Koin 容器正在執行,該 Rule 會先關閉它。已啟動的執行個體可透過 koinTestRule.koin 取得。
JUnit 5:KoinTestExtension
KoinTestExtension(來自 koin-test-junit5)針對 JUnit 5 提供了相同的功能。請使用 @JvmField 和 @RegisterExtension 註冊它:
import org.koin.test.junit5.KoinTestExtension
class UserServiceTest : KoinTest {
@JvmField
@RegisterExtension
val koinTestExtension = KoinTestExtension.create {
modules(appModule)
}
private val userService: UserService by inject()
@Test
fun `finds a known user`() {
assertNotNull(userService.findUser("alice"))
}
}該 Extension 也可以將 Koin 執行個體作為測試函式參數傳入:
@Test
fun `resolves from the test container`(koin: Koin) {
assertNotNull(koin.get<UserRepository>())
}覆寫測試的定義
若要替換生產環境的定義,請在生產模組之後載入測試模組。最後載入的模組優先權最高:
val testModule = module {
single<ApiService> { FakeApiService() }
}
@get:Rule
val koinTestRule = KoinTestRule.create {
modules(appModule, testModule)
}像 single<ApiService> { FakeApiService() } 這樣的 Lambda 定義適用於所有風格,因此即使你的應用程式使用編譯器外掛程式 DSL 或註解,你也可以用這種方式編寫測試模組。
如果你的應用程式啟動 Koin 時設定了 allowOverride(false),請為每個測試定義標註 .override()。覆寫規則請參閱定義。
使用 declareMock 進行 Mock
declareMock<T>() 會建立 T 的 Mock,將其註冊到執行中的容器以取代既有定義,並將其傳回。所有相依於 T 的定義隨後都會接收到該 Mock。
Koin 本身不會建立 Mock。請先註冊一個 Mock 提供者:
// JUnit 4, Mockito
@get:Rule
val mockProvider = MockProviderRule.create { clazz ->
Mockito.mock(clazz.java)
}
// JUnit 4, MockK
@get:Rule
val mockProvider = MockProviderRule.create { clazz ->
mockkClass(clazz)
}
// JUnit 5
@JvmField
@RegisterExtension
val mockProvider = MockProviderExtension.create { clazz ->
mockkClass(clazz)
}然後在測試中宣告 Mock,並可選擇性傳入 Stub 區塊:
import org.koin.test.mock.declareMock
class UserServiceTest : KoinTest {
@get:Rule
val koinTestRule = KoinTestRule.create {
modules(appModule)
}
@get:Rule
val mockProvider = MockProviderRule.create { clazz -> mockkClass(clazz) }
private val userService: UserService by inject()
@Test
fun `returns the user from the repository`() {
val repository = declareMock<UserRepository> {
every { findUser("alice") } returns User("alice")
}
assertEquals("alice", userService.findUser("alice")?.name)
verify { repository.findUser("alice") }
}
}declareMock 接受與一般定義相同的選項:
qualifier:替換具備限定詞的定義,例如declareMock<Database>(named("local"))。secondaryTypes:同時將 Mock 繫結至其他型別,例如declareMock<UserRepositoryImpl>(secondaryTypes = listOf(UserRepository::class))。
Mock 會作為單一執行個體保存在根作用域中。若要在特定作用域內 Mock 定義,請在該作用域上呼叫 declareMock:scope.declareMock<CartState>()。
WARNING
請在使用該 Mock 的類別首次解析之前宣告 Mock。已建立的 single 會保留其先前接收到的相依性。
使用 declare 宣告執行個體
當你需要真實或手寫的執行個體而非 Mock 時,declare 會將其註冊到執行中的容器內:
import org.koin.test.mock.declare
@Test
fun `uses a fixed clock`() {
declare<Clock> { FixedClock(at = "2026-01-01T00:00:00Z") }
assertEquals(2026, get<ReportService>().currentYear())
}declare 會覆寫該型別的任何現有定義、接受 qualifier,並傳回所宣告的執行個體。它使用的是全域上下文,因此請在 Koin 啟動後再呼叫它。
測試作用域定義
自行建立作用域、從中解析,然後關閉它:
@Test
fun `cart state lives in its scope`() {
val scope = getKoin().createScope<CheckoutSession>("checkout-1")
val state = scope.get<CartState>()
assertSame(state, scope.get<CartState>())
scope.close()
}有關作用域 API,請參閱作用域。在 Android 上,繫結至 Activity 或 Fragment 的作用域會與組件本身一起測試:請參閱 Android 檢測測試。
檢查你的配置
單元測試用於驗證行為。若要檢查每個定義的每個相依性是否都已宣告,請在建置時使用 Koin 編譯器外掛程式,或是使用 verify() 測試 API:請參閱驗證你的配置。
限制
- 全域上下文:
startKoin、KoinTestRule和KoinTestExtension都使用單一全域上下文。啟動 Koin 的測試無法在同一個 JVM 中平行執行。對於平行測試,請使用隔離上下文。除非覆寫getKoin(),否則KoinTest的get()和inject()會讀取全域上下文。 - Mock 提供者:如果未註冊
MockProviderRule或MockProviderExtension,declareMock將會失敗。 - 覆寫會在整個測試期間保持生效:使用測試模組、
declareMock或declare替換的定義僅會在 Koin 停止時被重設。
相關內容
- 驗證你的配置:
verify()及其與編譯期安全性的關聯。 - Android 檢測測試:由
Application啟動 Koin 的測試。 - 測試 Composable:Compose UI 測試與預覽。
- Ktor 測試:結合 Koin 的
testApplication。 - 上下文隔離:適用於程式庫與平行測試的獨立 Koin 容器。
- JUnit 測試快速入門:完整的範例專案。
