ユニットテスト
このガイドでは、Koin を使用して JVM ユニットテストを作成する方法を説明します。テストごとのコンテナの起動と停止、インスタンスの取得、定義のオーバーライド、依存関係のモックへの置き換えなどを扱います。本ガイドはあらゆるテスト手法のリファレンスとなります。各プラットフォームのページ(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 はモックライブラリに依存していないため、Mockito、MockK、またはその他の任意のライブラリをプラグインとして組み込めます(declareMock によるモック作成を参照)。
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 は、startKoin によって作成されるグローバルな Koin コンテキストで動作します。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 ルールおよび機能拡張(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"))
}
}ラムダ式は通常の KoinApplication 宣言です。startKoin { } に記述するすべてのものがここで動作します。アノテーションを使用している場合は、withConfiguration<MyApp>() でアプリを読み込みます。
import org.koin.plugin.module.dsl.withConfiguration
@get:Rule
val koinTestRule = KoinTestRule.create {
withConfiguration<MyApp>()
}テストの開始時に Koin コンテナがすでに実行されている場合、ルールはまずそれを閉じます。起動されたインスタンスは 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"))
}
}また、このエクステンションはテスト関数のパラメータとして 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() } のようなラムダ定義はすべてのスタイルで機能するため、アプリがコンパイラプラグイン DSL やアノテーションを使用していても、この方法でテストモジュールを記述できます。
アプリが allowOverride(false) で Koin を起動している場合は、各テスト定義に .override() を指定してください。オーバーライドのルールは定義で説明されています。
declareMock によるモック作成
declareMock<T>() は T のモックを作成し、既存の定義の代わりに実行中のコンテナに登録して、それを返します。これ以降、T に依存するすべての定義はモックを受け取ります。
Koin 自体はモックを作成しません。まずモックプロバイダを登録します。
// 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)
}次に、オプションのスタブブロックを付けてテスト内でモックを宣言します。
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: 修飾子付き(qualified)の定義を置き換えます(例:declareMock<Database>(named("local")))。secondaryTypes: モックを他の型にもバインドします(例:declareMock<UserRepositoryImpl>(secondaryTypes = listOf(UserRepository::class)))。
モックはルートスコープ内の単一インスタンスとして保持されます。スコープ内の定義をモック化するには、そのスコープに対して declareMock を呼び出します(scope.declareMock<CartState>())。
WARNING
モックは、それを使用するクラスが最初に解決される前に宣言してください。すでに作成されている single は、受け取った依存関係を保持し続けます。
declare によるインスタンスの宣言
モックの代わりに実際の実装や手動で作成したインスタンスが必要な場合は、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 内で並列実行できません。並列テストには、分離されたコンテキスト(isolated context)を使用してください。getKoin()をオーバーライドしない限り、KoinTestのget()およびinject()はグローバルコンテキストを読み取ります。 - モックプロバイダ:
MockProviderRuleまたはMockProviderExtensionが登録されていない場合、declareMockは失敗します。 - オーバーライドはテスト全体で有効: テストモジュール、
declareMock、またはdeclareで置き換えられた定義は、Koin が停止したときにのみリセットされます。
関連情報
- 設定の検証:
verify()とコンパイル時の安全性との関係。 - Android 計測テスト:
Applicationが Koin を起動するテスト。 - Composable のテスト: Compose UI テストとプレビュー。
- Ktor のテスト: Koin を使用した
testApplication。 - コンテキストの分離: ライブラリおよび並列テスト用のプライベート Koin コンテナ。
- JUnit テスト クイックスタート: 完全なサンプルプロジェクト。
