Skip to content

단위 테스트 (Unit Testing) ​

이 가이드에서는 Koin을 사용하여 JVM 단위 테스트를 작성하는 방법을 보여줍니다. 테스트마다 컨테이너를 시작 및 중지하고, 인스턴스를 가져오고, 정의를 재정의(override)하며, 의존성을 모의 객체(mock)로 교체하는 방법을 다룹니다. 이 문서는 모든 테스트 기법에 대한 레퍼런스이며, 플랫폼별 페이지(Android 계측 테스트, Compose, Ktor)에서는 해당 플랫폼에 특화된 내용만 다룹니다. 읽기 전에 Koin 시작하기와 정의 선언 방법을 알고 있어야 합니다.

의존성 (Dependencies) ​

테스트 의존성에 koin-test와 사용하는 JUnit 버전에 맞는 아티팩트를 추가합니다:

kotlin
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는 모킹(mocking) 라이브러리에 대한 의존성이 없으므로 Mockito, MockK 또는 다른 라이브러리를 직접 연동하여 사용할 수 있습니다(declareMock으로 모킹하기 참조).

KoinTest ​

테스트 클래스에서 KoinTest를 구현합니다. 이를 통해 해당 클래스는 KoinComponent가 되므로, 테스트 내에서 get()과 by inject()를 직접 사용할 수 있습니다:

kotlin
import org.koin.test.KoinTest
import org.koin.test.get
import org.koin.test.inject

class UserServiceTest : KoinTest {

    // 최초 접근 시 해결(resolve)됨
    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 컨텍스트(global Koin context)와 함께 동작합니다. Application 클래스가 Koin을 시작하는 Android 계측 테스트에는 적용되지 않으므로, Android 계측 테스트를 참조하세요.

각 테스트마다 Koin 시작 및 중지 ​

각 테스트는 자체 컨테이너를 시작하고 테스트가 끝날 때 이를 중지해야 합니다. 컨테이너가 계속 실행 중인 상태로 남아 있으면 다음 startKoin 실행 시 KoinApplicationAlreadyStartedException과 함께 실패하며, 테스트 간에 인스턴스가 누수(leak)될 수 있습니다.

애플리케이션과 동일한 구성을 로드합니다:

kotlin
class UserServiceTest : KoinTest {

    @Before
    fun before() {
        startKoin { modules(appModule) }
    }

    @After
    fun after() {
        stopKoin()
    }
}

타입 지정 API를 사용하여 앱의 @KoinApplication 클래스를 시작합니다:

kotlin
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)를 사용하세요.

kotlin
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을 시작하고 테스트 후에 중지합니다:

kotlin
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>()으로 앱을 로드합니다:

kotlin
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을 사용하여 등록합니다:

kotlin
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 인스턴스를 테스트 함수의 파라미터로 전달받을 수도 있습니다:

kotlin
@Test
fun `resolves from the test container`(koin: Koin) {
    assertNotNull(koin.get<UserRepository>())
}

테스트를 위한 정의 재정의 (Override definitions for a test) ​

프로덕션 정의를 교체하려면 프로덕션 모듈 다음에 테스트 모듈을 로드합니다. 가장 마지막에 로드된 모듈이 우선 적용됩니다:

kotlin
val testModule = module {
    single<ApiService> { FakeApiService() }
}

@get:Rule
val koinTestRule = KoinTestRule.create {
    modules(appModule, testModule)
}

single<ApiService> { FakeApiService() }와 같은 람다 정의는 모든 스타일에 동작하므로, 앱에서 컴파일러 플러그인 DSL이나 어노테이션을 사용하더라도 이 방식으로 테스트 모듈을 작성할 수 있습니다.

앱이 allowOverride(false)로 Koin을 시작하는 경우 각 테스트 정의에 .override()를 명시하세요. 재정의 규칙은 정의에 설명되어 있습니다.

declareMock으로 모킹하기 (Mocking with declareMock) ​

declareMock<T>()는 T의 모의 객체(mock)를 생성하여 실행 중인 컨테이너에 기존 정의 대신 등록하고 이를 반환합니다. 그러면 T에 의존하는 모든 정의가 이 모의 객체를 주입받게 됩니다.

Koin은 자체적으로 모의 객체를 생성하지 않습니다. 먼저 모의 객체 제공자(mock provider)를 등록해야 합니다:

kotlin
// 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)
}

그런 다음 테스트 내에서 선택적인 스터빙(stubbing) 블록과 함께 모의 객체를 선언합니다:

kotlin
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: 한정자(qualifier)가 지정된 정의를 교체합니다(예: declareMock<Database>(named("local"))).
  • secondaryTypes: 모의 객체를 다른 타입에도 바인딩합니다(예: declareMock<UserRepositoryImpl>(secondaryTypes = listOf(UserRepository::class))).

모의 객체는 루트 스코프(root scope)에서 단일 인스턴스(single instance)로 유지됩니다. 특정 스코프 내부의 정의를 모킹하려면 해당 스코프에서 declareMock을 호출하세요: scope.declareMock<CartState>().

WARNING

모의 객체를 사용하는 클래스가 처음으로 해결(resolve)되기 전에 모의 객체를 선언해야 합니다. 이미 생성된 single 인스턴스는 이전에 받은 의존성을 그대로 유지합니다.

declare를 사용하여 인스턴스 선언하기 (Declare an instance with declare) ​

모의 객체 대신 실제 인스턴스나 직접 생성한 인스턴스가 필요한 경우, declare를 사용하여 실행 중인 컨테이너에 등록할 수 있습니다:

kotlin
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 scoped definitions) ​

스코프를 직접 생성하고, 해당 스코프에서 인스턴스를 해결(resolve)한 후 스코프를 닫습니다:

kotlin
@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에 대한 자세한 내용은 Scopes를 참조하세요. Android에서 Activity나 Fragment에 바인딩된 스코프는 컴포넌트 자체와 함께 테스트됩니다. 자세한 내용은 Android 계측 테스트를 참조하세요.

구성 검증 (Check your configuration) ​

단위 테스트는 동작을 검증합니다. 모든 정의의 모든 의존성이 제대로 선언되었는지 확인하려면 빌드 타임에 Koin 컴파일러 플러그인을 사용하거나 verify() 테스트 API를 사용하세요. 자세한 내용은 구성 검증하기를 참조하세요.

제한 사항 (Limits) ​

  • 전역 컨텍스트: startKoin, KoinTestRule, KoinTestExtension은 모두 단일 전역 컨텍스트를 사용합니다. 따라서 Koin을 시작하는 테스트는 동일한 JVM 내에서 병렬로 실행할 수 없습니다. 병렬 테스트를 수행하려면 격리된 컨텍스트(isolated context)를 사용하세요. KoinTest의 get() 및 inject()는 getKoin()을 오버라이드하지 않는 한 전역 컨텍스트를 읽습니다.
  • 모의 객체 제공자(Mock provider): MockProviderRule 또는 MockProviderExtension이 등록되어 있지 않으면 declareMock 호출이 실패합니다.
  • 재정의의 유효 범위는 테스트 전체: 테스트 모듈, declareMock, declare로 교체된 정의는 Koin이 중지될 때만 초기화(reset)됩니다.