Refactor SystemContext to use interfaces instead of open classes

Constructor parameters in open classes forced test subclasses to provide
dummy dependencies (DataSource, Config) even when fakes never used them.
This became a real problem as repositories evolved to need more dependencies.

Changes:
- SystemContext: Use interfaces with anonymous objects for dependency groups
- SystemTestContext: Implement typed test pattern with dual access paths
- Tests updated to use testRepositories/testClients for fake-specific methods
- Documentation expanded to explain why open classes didn't work
- Skills README enhanced with detailed skill descriptions
- Parent README updated with skills section

Benefits:
- No constructor parameters to satisfy in tests
- No casting needed to access fake methods
- Type-safe dual access: repositories (interface) vs testRepositories (concrete)
- Production wiring stays in one place (anonymous objects)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: anderssv

README.md

@@ -32,6 +32,18 @@ But special thanks goes out to Asgaut Mjølne, Ola Hast, and Terje Heen for the
 
 If you're looking for the workshop, you can [find it here](doc/workshop/README.md).
 
+# Claude Code Skills
+
+This repository includes reusable [Claude Code skills](skills/README.md) that teach Claude the patterns and practices used here:
+
+- **kotlin-tdd** 🧪 - Test-Driven Development with fakes, object mothers, and Testing Through The Domain
+- **kotlin-context-di** 🔌 - Manual dependency injection using SystemContext and TestContext patterns
+
+Install them to teach Claude Code about the approaches in this codebase:
+```bash
+npx skills add anderssv/the-example/skills
+```
+
 # Using this code and building
 
 ## Prerequisites

doc/manual-dependency-injection.md

@@ -21,13 +21,89 @@ I usually do manual dependency injection. 🚀
 > ✅ You can see a dependency injection example in [SystemContext.kt](../src/main/kotlin/system/SystemContext.kt)
 and how to set up a separate context for testing in [SystemTestContext.kt](../src/test/kotlin/system/SystemTestContext.kt).
 
+## The Pattern: Interfaces with Anonymous Objects
 
-My reasons for this are:
+The core pattern uses **interfaces** for dependency grouping, implemented as **anonymous objects** inside the context:
+
+```kotlin
+interface Repositories {
+    val applicationRepo: ApplicationRepository
+}
+
+open val repositories: Repositories by lazy {
+    object : Repositories {
+        override val applicationRepo by lazy { ApplicationRepositoryImpl() }
+    }
+}
+```
+
+### Why Interfaces Instead of Open Classes?
+
+**The problem with open classes:**
+```kotlin
+// Don't do this
+open class Repositories(private val dataSource: DataSource) {
+    open val applicationRepo: ApplicationRepository = ApplicationRepositoryImpl(dataSource)
+}
+```
+
+When you use open classes with constructor parameters, test subclasses are forced to satisfy those parameters even when test fakes never use them:
+
+```kotlin
+// Test subclass is forced to provide a dataSource it doesn't need
+class TestRepositories : Repositories(DummyDataSource()) {  // <- Awkward!
+    override val applicationRepo = ApplicationRepositoryFake()  // Doesn't even use dataSource!
+}
+```
+
+This became a real problem in production code when repositories started needing database connections, configuration objects, or HTTP clients in their constructors. Test code had to create dummy instances of these just to satisfy the superclass constructor, even though fakes are in-memory and never touch databases or HTTP.
+
+**The interfaces solution:**
+- No constructor parameters
+- No dummy objects needed in tests
+- Test implementations must explicitly provide every dependency (no hidden inherited behavior)
+- Production wiring stays in one place (anonymous objects inside SystemContext)
+
+### Typed Test Implementations Pattern
+
+The test context provides **two access paths** using Kotlin's covariant return types:
+
+```kotlin
+class SystemTestContext : SystemContext() {
+    class TestRepositories : Repositories {
+        override val applicationRepo = ApplicationRepositoryFake()  // Concrete type!
+    }
+
+    val testRepositories = TestRepositories()
+    override val repositories: Repositories get() = testRepositories
+}
+```
+
+In tests:
+- `repositories.applicationRepo` - typed as `ApplicationRepository` (interface, used by production code)
+- `testRepositories.applicationRepo` - typed as `ApplicationRepositoryFake` (concrete, for test assertions)
+
+No casting needed:
+```kotlin
+with(SystemTestContext()) {
+    applicationService.registerApplication(app)
+
+    // Access fake-specific methods directly - no casting!
+    assertThat(testRepositories.applicationRepo.getAllApplications())
+        .contains(app)
+}
+```
+
+## Benefits of Manual DI
+
+My reasons for this approach:
 - I spend less time on Google figuring out which annotation or XML/JSON/YAML element to specify.
 - It shows the different places I am injecting each object/service/repo/client.
 - It makes it possible to inject whatever I want, whenever I want. Think Test Doubles like Fakes. Or even once in a while Mocks.
-- I TDD a lot more. Because I control how much is being loaded and when, I only load what’s necessary and it’s fast. I can decide to make the feedback loop efficient even if I am writing automated tests that do actual HTTP and database calls.
+- I TDD a lot more. Because I control how much is being loaded and when, I only load what's necessary and it's fast. I can decide to make the feedback loop efficient even if I am writing automated tests that do actual HTTP and database calls.
 - I re-factor more. Sometimes when I re-factor, the specific patterns of the framework get in the way. Without framework annoyances, it is easier and more fun to do refactorings.
+- No casting needed in tests (typed test implementations give you concrete fake types)
+- Test contexts are lightweight - fresh context per test prevents state leakage
 
 # Related Reading
 - [Rolling your own dependency injection](https://anderssv.medium.com/rolling-your-own-dependency-injection-7045f8b64403)

skills/README.md

@@ -1,3 +1,71 @@
-Skills :-)
+# Claude Skills for The Example
 
-    npx skills add https://github.com/anderssv/the-example/skills
+This directory contains reusable Claude Code skills that teach Claude Code patterns and practices used in this project.
+
+## Installation
+
+Add these skills to your Claude Code installation:
+
+```bash
+npx skills add anderssv/the-example/skills
+```
+
+## Available Skills
+
+### 🧪 kotlin-tdd
+
+Kotlin Test-Driven Development with fakes, object mothers, and Testing Through The Domain.
+
+**Location:** `testing/kotlin-tdd/`
+
+**What it teaches:**
+- Three pillars: Test Setup, Fakes, and Testing Through The Domain (TTTD)
+- Extension functions for test data with sensible defaults
+- HashMap-based fakes instead of mocking frameworks
+- SystemTestContext pattern with dependency injection
+- TestClock for time control in tests
+- Parallel-safe assertions for concurrent test execution
+- Test tagging (unit, integration, database, e2e)
+- When to use real implementations vs fakes
+- When mocks are appropriate (HTTP protocol testing)
+
+**Use when:**
+- Writing Kotlin tests
+- Setting up test infrastructure
+- Need guidance on fakes vs mocks
+- Testing time-dependent code
+- Writing parallel-safe tests
+
+### 🔌 kotlin-context-di
+
+Manual dependency injection using SystemContext (production) and TestContext (test doubles) patterns.
+
+**Location:** `practices/kotlin-context-di/`
+
+**What it teaches:**
+- SystemContext pattern for type-safe DI without frameworks
+- TestContext pattern for test doubles
+- Using interfaces for dependency grouping
+- Anonymous objects for production wiring
+- Typed test implementations to avoid casting
+- Fresh context per test pattern
+- Lazy vs direct initialization strategies
+- Nullable-to-non-nullable narrowing in tests
+
+**Use when:**
+- Structuring service dependencies
+- Wiring application components
+- Creating test contexts
+- Need alternative to framework-based DI
+- Want full control over initialization
+
+## Why These Skills?
+
+These skills codify the patterns and practices demonstrated throughout this repository. They help Claude Code understand:
+- How to write tests using the approaches shown in `/doc/tdd.md`, `/doc/fakes.md`, and `/doc/tttd.md`
+- How to structure applications using the patterns in `/doc/manual-dependency-injection.md`
+- The specific idioms and conventions used in this codebase
+
+## Contributing
+
+These skills are extracted from real working code in this repository. If you find improvements or want to add new skills, please open an issue or PR.

src/main/kotlin/system/SystemContext.kt

@@ -12,37 +12,79 @@ import notifications.UserNotificationClientImpl
 import java.time.Clock
 
 /**
- * This represents the main DI context.
+ * Manual dependency injection using interfaces and anonymous objects.
  *
- * Using lazy for the implementations here as we don't want them to load if overridden.
- * This can be important for third party integrations and DBs.
- * If you know a better way, please let me know.
+ * This pattern uses interfaces for dependency grouping instead of open classes with constructor parameters.
+ * The reason: 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).
  *
- * See here for a subclass that overrides the relevant parts with fakes (in the test scope):
+ * Benefits of using interfaces:
+ * - No constructor parameters to satisfy in test subclasses
+ * - Test implementations can have concrete types (e.g., ApplicationRepositoryFake instead of ApplicationRepository)
+ * - No casting needed in tests to access fake-specific methods
+ * - Production wiring stays in one place (anonymous objects inside this context)
+ *
+ * See the test context that provides fakes:
  * https://github.com/anderssv/the-example/blob/main/src/test/kotlin/system/SystemTestContext.kt
  */
-@Suppress("LeakingThis")
-open class SystemContext { // You can pass things like config and DB in here, YMMV
-    // Just some namespacing
-    open class Repositories {
-        // Can be overridden in the subclass
-        open val applicationRepo: ApplicationRepository by lazy { ApplicationRepositoryImpl() }
+open class SystemContext { // You can pass things like config and DB in here
+    /**
+     * Interface for repository dependencies.
+     * Using an interface (not an open class) means:
+     * - No constructor parameters
+     * - Test implementations don't inherit production defaults
+     * - Tests must explicitly provide every dependency
+     */
+    interface Repositories {
+        val applicationRepo: ApplicationRepository
+    }
+
+    /**
+     * Interface for external client dependencies.
+     * Using an interface (not an open class) means:
+     * - No constructor parameters
+     * - Test implementations don't inherit production defaults
+     * - Tests must explicitly provide every dependency
+     */
+    interface Clients {
+        val customerRepository: CustomerRegisterClient
+        val userNotificationClient: UserNotificationClient
+        val brregClient: BrregClient
+    }
+
+    /**
+     * Production implementation of repositories using anonymous objects.
+     * The anonymous object captures context properties (like dataSource if we had one).
+     * Using lazy prevents initialization if overridden in test contexts.
+     */
+    open val repositories: Repositories by lazy {
+        object : Repositories {
+            override val applicationRepo: ApplicationRepository by lazy { ApplicationRepositoryImpl() }
+        }
     }
 
-    // Just some namespacing
-    open class Clients {
-        open val customerRepository: CustomerRegisterClient by lazy { CustomerRegisterClientImpl() }
-        open val userNotificationClient: UserNotificationClient by lazy { UserNotificationClientImpl() }
-        open val brregClient: BrregClient by lazy { BrregClientImpl() }
+    /**
+     * Production implementation of clients using anonymous objects.
+     * The anonymous object captures context properties (like config if we had one).
+     * Using lazy prevents initialization if overridden in test contexts.
+     */
+    open val clients: Clients by lazy {
+        object : Clients {
+            override val customerRepository: CustomerRegisterClient by lazy { CustomerRegisterClientImpl() }
+            override val userNotificationClient: UserNotificationClient by lazy { UserNotificationClientImpl() }
+            override val brregClient: BrregClient by lazy { BrregClientImpl() }
+        }
     }
 
-    // Open because they will be overridden with Fakes
-    open val repositories = Repositories()
-    open val clients = Clients()
+    /**
+     * Clock for time-based operations. Overridden with TestClock in tests.
+     */
     open val clock: Clock = Clock.systemDefaultZone()
 
-    // The main components using the IO stuff that can be faked
-    // Using lazy here to get the overridden values from the subclass that overrides clients and repos
+    /**
+     * The main application service using the IO dependencies.
+     * Using lazy here ensures we get the overridden values from test subclasses.
+     */
     val applicationService by lazy {
         ApplicationService(
             repositories.applicationRepo,

src/test/kotlin/application/ApplicationFakeTest.kt

@@ -70,15 +70,15 @@ class ApplicationFakeTest {
             applicationService.expireApplications()
 
             assertThat(applicationService.activeApplicationFor(application.name)).isEmpty()
-            clients.userNotificationClient.getNotificationForUser(application.name).also {
+            testClients.userNotificationClient.getNotificationForUser(application.name).also {
                 // Notice how this is a specific method in the Fake. In the case of something
                 // like e-mail, there is no way of fetching the actual messages after the fact.
                 // So this method is used to verify the outcome, which should be that notifications
                 // are sent to the user.
                 //
                 // Try to focus on verifying the system results, but sometimes you need to validate
                 // the interactions as well.
-                assertThat(it).isNotEmpty
+                assertThat(it).isNotEmpty()
                 assertThat(it).contains("Your application ${application.id} has expired")
             }
         }

src/test/kotlin/system/SystemTestContext.kt

@@ -6,29 +6,84 @@ import customer.CustomerRegisterClientFake
 import notifications.UserNotificationClientFake
 
 /**
- * Overrides the relevant properties to make them Fakes
+ * Test context with fakes using typed test implementations pattern.
  *
- * Notice that this Context only overrides the Repos/Clients with fakes.
- * The actual injection of Services (that I usually don't fake) is done in the superclass via the lazy construct.
+ * This pattern provides two access paths:
+ * 1. repositories.applicationRepo - typed as ApplicationRepository (interface type, used by services)
+ * 2. testRepositories.applicationRepo - typed as ApplicationRepositoryFake (concrete type, for test assertions)
  *
- * See here for the super class that this test context inherits/overrides:
+ * Benefits:
+ * - No casting needed to access fake-specific methods
+ * - Type safety: IDE autocomplete shows fake methods when using testRepositories
+ * - Clear separation: production code uses abstract interfaces, tests use concrete fakes
+ *
+ * Usage in tests:
+ * ```
+ * with(SystemTestContext()) {
+ *     // Arrange
+ *     applicationService.registerInitialApplication(customer, application)
+ *
+ *     // Assert - direct access to fake methods, no casting needed
+ *     assertThat(testRepositories.applicationRepo.getAllApplications())
+ *         .contains(application)
+ * }
+ * ```
+ *
+ * See the production context:
  * https://github.com/anderssv/the-example/blob/main/src/main/kotlin/system/SystemContext.kt
  *
- * To see usage, you can see here: https://github.com/anderssv/the-example/blob/main/src/test/kotlin/tttd/TestingThroughTheDomainTest.kt#L26
+ * See usage examples:
+ * https://github.com/anderssv/the-example/blob/main/src/test/kotlin/application/TestingThroughTheDomainTest.kt
  */
 class SystemTestContext : SystemContext() {
-    class Repositories : SystemContext.Repositories() {
+    /**
+     * Test implementation with concrete fake types.
+     * Properties are typed as ApplicationRepositoryFake (not ApplicationRepository),
+     * which allows accessing fake-specific methods without casting.
+     */
+    class TestRepositories : Repositories {
         override val applicationRepo = ApplicationRepositoryFake()
     }
 
-    class Clients : SystemContext.Clients() {
+    /**
+     * Test implementation with concrete fake types.
+     * Properties are typed as *ClientFake (not the interface),
+     * which allows accessing fake-specific methods without casting.
+     */
+    class TestClients : Clients {
         override val customerRepository = CustomerRegisterClientFake()
         override val userNotificationClient = UserNotificationClientFake()
         override val brregClient = BrregClientFake()
     }
 
-    // Override the contexts with Fakes
-    override val repositories = Repositories()
-    override val clients = Clients()
+    /**
+     * Typed test repositories - use this in test assertions to access fake-specific methods.
+     * Type: TestRepositories (concrete class with ApplicationRepositoryFake properties)
+     */
+    val testRepositories = TestRepositories()
+
+    /**
+     * Typed test clients - use this in test assertions to access fake-specific methods.
+     * Type: TestClients (concrete class with *ClientFake properties)
+     */
+    val testClients = TestClients()
+
+    /**
+     * Override abstract interface property with test implementation.
+     * Production code accesses this as Repositories (abstract interface).
+     * Type: Repositories (interface)
+     */
+    override val repositories: Repositories get() = testRepositories
+
+    /**
+     * Override abstract interface property with test implementation.
+     * Production code accesses this as Clients (abstract interface).
+     * Type: Clients (interface)
+     */
+    override val clients: Clients get() = testClients
+
+    /**
+     * Override clock with TestClock for time control in tests.
+     */
     override val clock = TestClock.now()
 }