STARTER_CHARACTER = 🔌

Manual Dependency Injection with SystemContext and TestContext

Structure Kotlin applications using manual DI with SystemContext (production) and TestContext (test) patterns. This approach provides type-safe dependency management, full control over initialization, and excellent testability without framework overhead.

Core Pattern: SystemContext

Create an open class that holds all application dependencies. Use interfaces to group related components, and implement them as anonymous objects inside the context.

kotlin

open class SystemContext {
    interface Repositories {
        val customerRepo: CustomerRepository
        val orderRepo: OrderRepository
    }
    
    open val repositories: Repositories by lazy {
        object : Repositories {
            override val customerRepo by lazy { CustomerRepositoryImpl(dataSource) }
            override val orderRepo by lazy { OrderRepositoryImpl(dataSource) }
        }
    }
    
    open val customerService by lazy { 
        CustomerService(repositories.customerRepo) 
    }
    
    open val orderService by lazy {
        OrderService(repositories.orderRepo, customerService)
    }
}

Key characteristics:

Group related dependencies using interfaces (not open classes — see rationale below)
Implement production wiring as anonymous objects inside the context
Services reference repositories and other services directly
Use
```
lazy
```
for initialization that depends on other context properties or is expensive
Use direct instantiation when initialization is trivial and has no dependencies

Why interfaces instead of open classes:

Open classes with constructor parameters force test subclasses to satisfy those parameters, even when test fakes never use them (e.g., creating a dummy
```
DataSource
```
just to satisfy a constructor)
Open classes carry implicit coupling: test subclasses inherit production defaults, which can mask test setup errors
Interfaces have no constructors and no inherited behavior — test implementations must explicitly provide every dependency

Why anonymous objects for production wiring:

Production wiring stays in one place (
```
SystemContext
```
)
Implementation details are private to the context
The anonymous object naturally captures
```
dataSource
```
and other context properties from the enclosing scope
No need for constructor parameters on the grouping interface

Test Pattern: TestContext with Typed Test Implementations

Extend SystemContext and override dependency groups with typed test implementations. Use concrete types in test implementations to avoid casting.

kotlin

class SystemTestContext : SystemContext() {
    class TestRepositories : Repositories {
        override val customerRepo = CustomerRepositoryFake()   // concrete type!
        override val orderRepo = OrderRepositoryFake()         // concrete type!
    }
    
    val testRepositories = TestRepositories()
    override val repositories: Repositories get() = testRepositories
}

This exploits Kotlin's covariant return types:

TestRepositories.customerRepo

has type

CustomerRepositoryFake

(concrete), while still satisfying the interface contract

CustomerRepository

(abstract).

Two access paths exist in tests:

repositories.customerRepo

— typed as

CustomerRepository

(used by production code)

testRepositories.customerRepo

— typed as

CustomerRepositoryFake

(for test assertions and setup)

In tests — create a fresh context per test:

kotlin

@Test
fun testOrderCreation() {
    with(SystemTestContext()) {
        // Arrange - use service methods to set up state
        customerService.registerCustomer(Customer.valid())
        
        // Act
        val order = orderService.createOrder(customerId, items)
        
        // Assert — direct access to fake methods, no casting needed
        assertThat(testRepositories.orderRepo.getSavedOrders())
            .contains(order)
    }
}

The

with(SystemTestContext()) { ... }

pattern creates a fresh context per test, provides clean access to all services and repositories, and prevents state leakage between tests.

Type Safety Benefits

Compile-time checking:

Typos caught immediately
Refactoring tools work perfectly (rename, move, find usages)
Missing dependencies fail at compile time, not runtime

IDE support:

Full autocomplete for all dependencies
Jump to definition works seamlessly
No string-based lookups or reflection

Clear dependency graph:

Constructor parameters show exact dependencies
Easy to trace where any component is used
No hidden framework magic

Initialization Control

Direct instantiation (default):

kotlin

open val customerService = CustomerService(repositories.customerRepo)

Use when initialization is cheap and there are no circular dependencies.

Lazy initialization:

kotlin

open val customerService by lazy {
    CustomerService(repositories.customerRepo)
}

Use when:

Circular dependencies exist (A needs B, B needs A)
Initialization is expensive (database connections, HTTP clients)
Component may not be used in all test scenarios
The value depends on other context properties that may be overridden

When in doubt, start with direct instantiation. Add

lazy

only when needed.

Grouping Dependencies

Organize dependencies by layer or concern using interfaces:

kotlin

open class SystemContext(private val config: Config) {
    // Data layer
    interface Repositories {
        val userRepo: UserRepository
        val productRepo: ProductRepository
    }
    
    // External services
    interface Clients {
        val paymentClient: PaymentClient
        val emailClient: EmailClient
    }
    
    // Infrastructure
    interface Infrastructure {
        val database: Database
        val cache: Cache
    }
    
    open val infrastructure: Infrastructure by lazy {
        object : Infrastructure {
            override val database by lazy { DatabaseImpl(config.dbUrl) }
            override val cache by lazy { RedisCache(config.redisUrl) }
        }
    }
    
    open val repositories: Repositories by lazy {
        object : Repositories {
            override val userRepo by lazy { UserRepositoryImpl(infrastructure.database) }
            override val productRepo by lazy { ProductRepositoryImpl(infrastructure.database) }
        }
    }
    
    open val clients: Clients by lazy {
        object : Clients {
            override val paymentClient by lazy { PaymentClientImpl(config.paymentApiKey) }
            override val emailClient by lazy { EmailClientImpl(config.smtpConfig) }
        }
    }
    
    // Business logic
    open val userService by lazy { UserService(repositories.userRepo) }
    open val orderService by lazy {
        OrderService(
            repositories.productRepo,
            clients.paymentClient,
            clients.emailClient
        )
    }
}

This structure:

Makes test overriding straightforward (override entire groups)
Clarifies architectural layers
Keeps production wiring in one place
Anonymous objects capture config and other context properties from the enclosing scope

Test Context: Full Example

kotlin

class SystemTestContext : SystemContext(Config.test()) {
    class TestRepositories : Repositories {
        override val userRepo = UserRepositoryFake()        // concrete type
        override val productRepo = ProductRepositoryFake()  // concrete type
    }
    
    class TestClients : Clients {
        override val paymentClient = PaymentClientFake()    // concrete type
        override val emailClient = EmailClientFake()        // concrete type
    }
    
    val testRepositories = TestRepositories()
    override val repositories: Repositories get() = testRepositories
    
    val testClients = TestClients()
    override val clients: Clients get() = testClients
}

In tests — no casting needed:

kotlin

@Test
fun testEmailSent() {
    with(SystemTestContext()) {
        orderService.completeOrder(orderId)
        
        // Direct access to fake methods via testClients — no casting
        assertThat(testClients.emailClient.sentEmails).hasSize(1)
        assertThat(testClients.emailClient.sentEmails[0].subject)
            .contains("Order Confirmed")
    }
}

@Test
fun testPaymentFailure() {
    with(SystemTestContext()) {
        // Configure fake behavior — no casting
        testClients.paymentClient.failOnNextCharge()
        
        val result = orderService.createOrder(request)
        
        assertThat(result.status).isEqualTo(OrderStatus.PAYMENT_FAILED)
    }
}

Fresh Context Per Test

Create a fresh context per test when fakes are stateful (the common case):

kotlin

@Test
fun `should save order`() {
    with(SystemTestContext()) {
        // Fresh fakes with no accumulated state
        orderService.createOrder(request)
        assertThat(testRepositories.orderRepo.getSavedOrders()).hasSize(1)
    }
}

@Test
fun `should not save order when payment fails`() {
    with(SystemTestContext()) {
        // Independent from the test above
        testClients.paymentClient.failOnNextCharge()
        orderService.createOrder(request)
        assertThat(testRepositories.orderRepo.getSavedOrders()).isEmpty()
    }
}

Why: Fakes are stateful —

OrderRepositoryFake

accumulates saved orders,

EmailClientFake

accumulates sent emails. Sharing a context across tests causes state from one test to leak into the next, leading to order-dependent failures and flaky tests.

The

with(SystemTestContext()) { ... }

pattern is idiomatic, cheap (no real I/O), and prevents test pollution.

Share a context only when fakes are truly stateless or when you have explicit reset logic — this is uncommon.

Nullable-to-Non-nullable Narrowing in Tests

When production interfaces have nullable dependencies (because configuration may be absent), test implementations can narrow them to non-nullable:

kotlin

// Production interface — nullable because config may not exist
interface Clients {
    val authClient: AuthClient?
    val notificationClient: NotificationClient?
}

// Test implementation — non-nullable
class TestClients : Clients {
    override val authClient = AuthClientStub()            // non-nullable!
    override val notificationClient = NotificationClientStub()  // non-nullable!
}

This is valid Kotlin because non-nullable types are subtypes of nullable types. Tests never need null checks when accessing test clients, even though production code handles the nullable case. This is a significant ergonomic win — test code stays clean and focused on behavior.

Integration with Test Doubles

TestContext typically contains Fakes (in-memory implementations of interfaces):

kotlin

class CustomerRepositoryFake : CustomerRepository {
    private val db = mutableMapOf<String, Customer>()
    
    override fun save(customer: Customer) {
        db[customer.id] = customer
    }
    
    override fun findById(id: String): Customer? {
        return db[id]
    }
    
    // Test-specific methods (not in interface)
    fun getSavedCustomers(): List<Customer> = db.values.toList()
    fun failOnNextSave() { /* ... */ }
}

The TestContext wires these Fakes and exposes them with concrete types:

kotlin

class SystemTestContext : SystemContext() {
    class TestRepositories : Repositories {
        override val customerRepo = CustomerRepositoryFake()  // concrete type
    }
    
    val testRepositories = TestRepositories()
    override val repositories: Repositories get() = testRepositories
}

Now

customerService

uses

CustomerRepositoryFake

automatically because it references

repositories.customerRepo

, and tests access fake-specific methods via

testRepositories.customerRepo

without casting.

Application Wiring

Main entry point:

kotlin

fun main() {
    val context = SystemContext(Config.fromEnvironment())
    
    // Start application with context
    val app = Application(
        context.orderService,
        context.userService
    )
    
    app.start()
}

Web framework integration (Ktor example):

kotlin

fun Application.module() {
    val context = SystemContext(Config.fromEnvironment())
    
    routing {
        get("/orders/{id}") {
            val orderId = call.parameters["id"]!!
            val order = context.orderService.getOrder(orderId)
            call.respond(order)
        }
        
        post("/orders") {
            val request = call.receive<CreateOrderRequest>()
            val order = context.orderService.createOrder(request)
            call.respond(order)
        }
    }
}

Routes access services directly from the context. No framework-specific annotations or registrations needed.

Why This Pattern Works

Simplicity:

No annotations to learn
No configuration files
No classpath scanning or reflection
Plain Kotlin code

Debuggability:

Step through initialization in debugger
Set breakpoints in context creation
No framework magic hiding behavior

Readability:

Dependencies visible in one place
Constructor calls show exactly what's needed
No surprising behavior from framework lifecycle

Test control:

Full control over what gets loaded
Fast test startup (only load what you need)
Easy to inject test doubles
No special test runners or annotations
No casting needed to access test-specific methods

Flexibility:

Change initialization order easily
Add conditional logic (feature flags, environment checks)
Compose contexts (production + feature flags)

Scalability:

Pattern stays simple as project grows
More dependencies just mean more properties in context classes
No framework limitations or architectural constraints

Anti-patterns

Avoid using open classes for dependency grouping:

kotlin

// Don't do this — forces test subclasses to satisfy constructor parameters
open class Repositories(private val dataSource: DataSource) {
    open val customerRepo: CustomerRepository = CustomerRepositoryImpl(dataSource)
}

Use interfaces instead — they have no constructors and force explicit implementation.

Avoid casting to access test-specific methods:

kotlin

// Don't do this
val emailClient = clients.emailClient as EmailClientFake
assertThat(emailClient.sentEmails).hasSize(1)

Use typed test implementations with dual access (

testClients.emailClient

) instead.

Avoid making everything lazy:

kotlin

// Don't do this unless needed
open val customerService by lazy { CustomerService(...) }
open val orderService by lazy { OrderService(...) }
open val productService by lazy { ProductService(...) }

Lazy adds complexity. Use direct instantiation unless circular dependencies or expensive initialization require it.

Avoid deep context hierarchies:

kotlin

// Too complex
open class DatabaseContext : InfrastructureContext()
open class RepositoryContext : DatabaseContext()
open class ServiceContext : RepositoryContext()
open class SystemContext : ServiceContext()

Keep it flat: one SystemContext with nested interface groups for organization.

Don't mix with annotation-based DI:

kotlin

// Don't mix patterns
@Inject lateinit var customerService: CustomerService  // Framework DI
val orderService = OrderService(repositories.orderRepo)  // Manual DI

Choose one approach and stick with it.

Migration Path

Adding to existing project:

Create SystemContext with existing components
Wire main entry point to use context
Gradually move initialization logic into context
Create TestContext and migrate tests incrementally

From framework DI:

Create parallel SystemContext alongside framework
New code uses SystemContext
Gradually migrate existing code
Remove framework once migration complete

No big-bang rewrite required. Adopt incrementally.

kotlin-context-di

NPX Install

Tags

SKILL.md Content

Manual Dependency Injection with SystemContext and TestContext

Core Pattern: SystemContext

Test Pattern: TestContext with Typed Test Implementations

Type Safety Benefits

Initialization Control

Grouping Dependencies

Test Context: Full Example

Fresh Context Per Test

Nullable-to-Non-nullable Narrowing in Tests

Integration with Test Doubles

Application Wiring

Why This Pattern Works

Anti-patterns

Migration Path