feat(testkit): add test harness and kernel provider overrides (#218)

## Type

- [x] `feat` — New feature
- [ ] `fix` — Bug fix
- [ ] `refactor` — Code restructure (no behavior change)
- [x] `docs` — Documentation only
- [x] `test` — Test coverage
- [ ] `chore` — Build, CI, tooling
- [ ] `perf` — Performance improvement

## Summary

Add a first-class `modkit/testkit` package for module-level tests and
extend kernel bootstrap with explicit provider override options. This
reduces test boilerplate while preserving visibility, deterministic
bootstrap behavior, and cleanup lifecycle guarantees.

## Changes

- Add `kernel.BootstrapWithOptions` and `WithProviderOverrides` with
strict override validation and typed errors
- Introduce `modkit/testkit` (`Harness`, override helpers, typed
`Get`/`Controller` helpers, close lifecycle + error types)
- Add kernel and testkit coverage for parity, override semantics,
duplicate/unknown/visibility checks, nil-option/build guards, and close
cancellation retry behavior
- Update testing guide and API reference for TestKit usage and
override-vs-test-module guidance
- Add focused TestKit usage in `examples/hello-simple` and realistic
override usage in `examples/hello-mysql` auth tests
- Update README package table to include `modkit/testkit`

## Breaking Changes

None

## Validation

```bash
make fmt && make lint && make vuln && make test && make test-coverage
make cli-smoke-build && make cli-smoke-scaffold
```

## Checklist

- [x] Code follows project style (`make fmt` passes)
- [x] Linter passes (`make lint`)
- [x] Vulnerability scan passes (`make vuln`)
- [x] Tests pass (`make test`)
- [x] Coverage tests pass (`make test-coverage`)
- [x] CLI smoke checks pass (`make cli-smoke-build && make
cli-smoke-scaffold`)
- [x] Tests added/updated for new functionality
- [x] Documentation updated (if applicable)
- [x] Commit messages follow [Conventional
Commits](https://www.conventionalcommits.org/)

## Notes

No issue hierarchy is linked for this change set.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* TestKit: a test harness for bootstrapping apps with provider
overrides, lifecycle/cleanup management, and typed accessors for
dependencies and controllers.
* Bootstrap customization: option-driven provider overrides during
initialization.
  * HTTP router API exposed for request handling.

* **Documentation**
* New testing guide with TestKit examples and best practices; API
reference and package listing updated to include TestKit and
bootstrap/router docs; README updated.

* **Tests**
* Extensive tests for TestKit, bootstrap options, overrides, error
cases, visibility rules, and cleanup behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: aryeko

README.md

@@ -169,6 +169,7 @@ The CLI automatically registers providers and controllers in your module's `Defi
 | `modkit/kernel` | Graph builder, visibility enforcer, bootstrap |
 | `modkit/http` | HTTP adapter for chi router |
 | `modkit/logging` | Logging interface with slog adapter |
+| `modkit/testkit` | Test harness for bootstrap, overrides, and typed test helpers |
 
 ## Architecture
 

docs/guides/testing.md

@@ -166,6 +166,34 @@ func TestIntegration(t *testing.T) {
 }
 ```
 
+## Using TestKit
+
+Use `modkit/testkit` when you want less boilerplate for bootstrap, typed retrieval, and provider overrides.
+
+```go
+func TestAuthModule_WithTestKit(t *testing.T) {
+    h := testkit.New(t,
+        auth.NewModule(auth.Options{}),
+        testkit.WithOverrides(
+            testkit.OverrideValue(configmodule.TokenAuthUsername, "demo"),
+            testkit.OverrideValue(configmodule.TokenAuthPassword, "demo"),
+        ),
+    )
+
+    handler := testkit.Get[*auth.Handler](t, h, auth.TokenHandler)
+    if handler == nil {
+        t.Fatal("expected handler")
+    }
+}
+```
+
+Decision guidance:
+
+- Use test module replacement when changing module wiring semantics.
+- Use TestKit override when isolating dependency behavior without changing graph shape.
+
+`testkit.New` registers cleanup with `t.Cleanup` by default. Use `testkit.WithoutAutoClose()` only when you need explicit close timing.
+
 ## Smoke Tests with Testcontainers
 
 For full integration tests, use testcontainers:

docs/reference/api.md

@@ -11,6 +11,7 @@ This is a quick reference for modkit's core types. For full documentation, see [
 | `kernel` | `github.com/go-modkit/modkit/modkit/kernel` | Graph builder, bootstrap |
 | `http` | `github.com/go-modkit/modkit/modkit/http` | HTTP adapter |
 | `logging` | `github.com/go-modkit/modkit/modkit/logging` | Logging interface |
+| `testkit` | `github.com/go-modkit/modkit/modkit/testkit` | Testing harness and overrides |
 
 ---
 
@@ -116,6 +117,24 @@ func (a *App) Resolver() Resolver
 
 Returns a root-scoped resolver that enforces module visibility.
 
+### BootstrapWithOptions
+
+```go
+func BootstrapWithOptions(root module.Module, opts ...BootstrapOption) (*App, error)
+```
+
+Bootstraps with explicit options. Use `WithProviderOverrides` to replace provider implementations, typically for testing.
+
+```go
+type ProviderOverride struct {
+    Token   module.Token
+    Build   func(module.Resolver) (any, error)
+    Cleanup func(context.Context) error  // Optional; called when harness is closed
+}
+
+func WithProviderOverrides(overrides ...ProviderOverride) BootstrapOption
+```
+
 ### Errors
 
 | Type | When |
@@ -129,6 +148,10 @@ Returns a root-scoped resolver that enforces module visibility.
 | `ProviderCycleError` | Provider depends on itself |
 | `ProviderBuildError` | Provider's `Build` function failed |
 | `ControllerBuildError` | Controller's `Build` function failed |
+| `DuplicateOverrideTokenError` | Override list contains duplicate token |
+| `OverrideTokenNotFoundError` | Override targets missing provider token |
+| `OverrideTokenNotVisibleFromRootError` | Override token not visible from root |
+| `BootstrapOptionConflictError` | Multiple options mutate same token |
 
 ---
 
@@ -188,6 +211,59 @@ Starts an HTTP server with graceful shutdown on SIGINT/SIGTERM.
 
 ---
 
+## testkit
+
+### New / NewE
+
+```go
+func New(tb testkit.TB, root module.Module, opts ...testkit.Option) *testkit.Harness
+func NewE(tb testkit.TB, root module.Module, opts ...testkit.Option) (*testkit.Harness, error)
+```
+
+Bootstraps a test harness. `New` fails the test on bootstrap error. `NewE` returns the error.
+
+### Harness lifecycle
+
+```go
+func (h *Harness) App() *kernel.App
+func (h *Harness) Close() error
+func (h *Harness) CloseContext(ctx context.Context) error
+```
+
+`Close` runs provider cleanup hooks first and then app closers.
+
+### Overrides
+
+```go
+func WithOverrides(overrides ...Override) Option
+func OverrideValue(token module.Token, value any) Override
+func OverrideBuild(token module.Token, build func(module.Resolver) (any, error)) Override
+func WithoutAutoClose() Option
+```
+
+Applies token-level provider overrides while preserving graph and visibility semantics.
+
+### Typed Helpers
+
+```go
+func Get[T any](tb testkit.TB, h *testkit.Harness, token module.Token) T
+func GetE[T any](h *testkit.Harness, token module.Token) (T, error)
+func Controller[T any](tb testkit.TB, h *testkit.Harness, moduleName, controllerName string) T
+func ControllerE[T any](h *testkit.Harness, moduleName, controllerName string) (T, error)
+```
+
+Typed wrappers for provider and controller retrieval in tests.
+
+### Key errors
+
+| Type | When |
+|------|------|
+| `ControllerNotFoundError` | Controller key was not found in harness app |
+| `TypeAssertionError` | Typed helper could not assert expected type |
+| `HarnessCloseError` | Hook close and/or app close returned errors |
+
+---
+
 ## logging
 
 ### Logger Interface

examples/hello-mysql/internal/modules/auth/module_test.go

@@ -4,9 +4,11 @@ import (
 	"errors"
 	"testing"
 
+	configmodule "github.com/go-modkit/modkit/examples/hello-mysql/internal/modules/config"
 	"github.com/go-modkit/modkit/examples/hello-mysql/internal/modules/database"
 	"github.com/go-modkit/modkit/modkit/kernel"
 	"github.com/go-modkit/modkit/modkit/module"
+	"github.com/go-modkit/modkit/modkit/testkit"
 )
 
 func TestModule_Bootstrap(t *testing.T) {
@@ -73,3 +75,21 @@ func TestAuthAndDatabase_DefaultConfigComposition(t *testing.T) {
 		t.Fatalf("bootstrap failed: %v", err)
 	}
 }
+
+func TestModule_TestKitOverrideConfigTokens(t *testing.T) {
+	h := testkit.New(t,
+		NewModule(Options{}),
+		testkit.WithOverrides(
+			testkit.OverrideValue(configmodule.TokenAuthUsername, "override-user"),
+			testkit.OverrideValue(configmodule.TokenAuthPassword, "override-pass"),
+		),
+	)
+
+	handler := testkit.Get[*Handler](t, h, TokenHandler)
+	if handler.cfg.Username != "override-user" {
+		t.Fatalf("username = %q", handler.cfg.Username)
+	}
+	if handler.cfg.Password != "override-pass" {
+		t.Fatalf("password = %q", handler.cfg.Password)
+	}
+}

examples/hello-simple/main_test.go

@@ -6,6 +6,7 @@ import (
 	"testing"
 
 	"github.com/go-modkit/modkit/modkit/module"
+	"github.com/go-modkit/modkit/modkit/testkit"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/mock"
 )
@@ -95,3 +96,13 @@ func TestAppModule_Providers(t *testing.T) {
 		assert.IsType(t, &Counter{}, val)
 	})
 }
+
+func TestAppModule_TestKitOverrideGreeting(t *testing.T) {
+	h := testkit.New(t,
+		NewAppModule("real"),
+		testkit.WithOverrides(testkit.OverrideValue(TokenGreeting, "fake")),
+	)
+
+	controller := testkit.Controller[*GreetingController](t, h, "app", "GreetingController")
+	assert.Equal(t, "fake", controller.message)
+}

modkit/kernel/bootstrap.go

@@ -5,11 +5,68 @@ import (
 	"context"
 	"errors"
 	"io"
+	"slices"
+	"strconv"
 	"sync/atomic"
 
 	"github.com/go-modkit/modkit/modkit/module"
 )
 
+type bootstrapConfig struct {
+	providerOverrides []ProviderOverride
+	firstOptionByTok  map[module.Token]int
+	optionNames       map[module.Token][]string
+	currentOptionIdx  int
+	err               error
+}
+
+func newBootstrapConfig() bootstrapConfig {
+	return bootstrapConfig{
+		providerOverrides: make([]ProviderOverride, 0),
+		firstOptionByTok:  make(map[module.Token]int),
+		optionNames:       make(map[module.Token][]string),
+	}
+}
+
+func (c *bootstrapConfig) setCurrentOption(index int) {
+	c.currentOptionIdx = index
+}
+
+func (c *bootstrapConfig) addProviderOverrides(overrides []ProviderOverride) {
+	if c.err != nil {
+		return
+	}
+
+	seenInThisOption := make(map[module.Token]bool)
+	optionName := c.providerOverrideOptionName(c.currentOptionIdx)
+	for _, override := range overrides {
+		if override.Build == nil {
+			c.err = &OverrideBuildNilError{Token: override.Token}
+			return
+		}
+
+		if seenInThisOption[override.Token] {
+			c.err = &DuplicateOverrideTokenError{Token: override.Token}
+			return
+		}
+		seenInThisOption[override.Token] = true
+
+		if firstIdx, ok := c.firstOptionByTok[override.Token]; ok && firstIdx != c.currentOptionIdx {
+			names := append(slices.Clone(c.optionNames[override.Token]), optionName)
+			c.err = &BootstrapOptionConflictError{Token: override.Token, Options: names}
+			return
+		}
+
+		c.firstOptionByTok[override.Token] = c.currentOptionIdx
+		c.optionNames[override.Token] = append(c.optionNames[override.Token], optionName)
+		c.providerOverrides = append(c.providerOverrides, override)
+	}
+}
+
+func (c *bootstrapConfig) providerOverrideOptionName(index int) string {
+	return "WithProviderOverrides#" + strconv.Itoa(index+1)
+}
+
 // App represents a bootstrapped modkit application with its dependency graph,
 // container, and instantiated controllers.
 type App struct {
@@ -28,6 +85,11 @@ func controllerKey(moduleName, controllerName string) string {
 // It builds the module graph, validates dependencies, creates the DI container,
 // and instantiates all controllers.
 func Bootstrap(root module.Module) (*App, error) {
+	return BootstrapWithOptions(root)
+}
+
+// BootstrapWithOptions constructs a modkit application from a root module and explicit bootstrap options.
+func BootstrapWithOptions(root module.Module, opts ...BootstrapOption) (*App, error) {
 	graph, err := BuildGraph(root)
 	if err != nil {
 		return nil, err
@@ -38,11 +100,38 @@ func Bootstrap(root module.Module) (*App, error) {
 		return nil, err
 	}
 
-	container, err := newContainer(graph, visibility)
+	cfg := newBootstrapConfig()
+	for idx, opt := range opts {
+		if opt == nil {
+			return nil, &NilBootstrapOptionError{Index: idx}
+		}
+		cfg.setCurrentOption(idx)
+		opt.apply(&cfg)
+		if cfg.err != nil {
+			return nil, cfg.err
+		}
+	}
+
+	providers, err := providerEntriesFromGraph(graph)
 	if err != nil {
 		return nil, err
 	}
 
+	for _, override := range cfg.providerOverrides {
+		entry, ok := providers[override.Token]
+		if !ok {
+			return nil, &OverrideTokenNotFoundError{Token: override.Token}
+		}
+		if !visibility[graph.Root][override.Token] {
+			return nil, &OverrideTokenNotVisibleFromRootError{Root: graph.Root, Token: override.Token}
+		}
+		entry.build = override.Build
+		entry.cleanup = override.Cleanup
+		providers[override.Token] = entry
+	}
+
+	container := newContainerWithProviders(providers, visibility)
+
 	controllers := make(map[string]any)
 	perModule := make(map[string]map[string]bool)
 	for i := range graph.Modules {

modkit/kernel/bootstrap_options.go

@@ -0,0 +1,34 @@
+package kernel
+
+import (
+	"context"
+
+	"github.com/go-modkit/modkit/modkit/module"
+)
+
+// ProviderOverride replaces provider build/cleanup behavior for a token at bootstrap time.
+type ProviderOverride struct {
+	Token   module.Token
+	Build   func(module.Resolver) (any, error)
+	Cleanup func(context.Context) error
+}
+
+// BootstrapOption configures advanced bootstrap behavior.
+type BootstrapOption interface {
+	apply(*bootstrapConfig)
+}
+
+type providerOverridesOption struct {
+	overrides []ProviderOverride
+}
+
+func (o providerOverridesOption) apply(cfg *bootstrapConfig) {
+	cfg.addProviderOverrides(o.overrides)
+}
+
+// WithProviderOverrides applies token-level provider overrides for bootstrap.
+func WithProviderOverrides(overrides ...ProviderOverride) BootstrapOption {
+	cloned := make([]ProviderOverride, len(overrides))
+	copy(cloned, overrides)
+	return providerOverridesOption{overrides: cloned}
+}