refactor: replace Managed* wrappers with interfaces (#655)

* refactor: replace Managed* wrappers with interfaces

Replace the concrete ManagedResource, ManagedPool, and ManagedNetwork
wrapper structs with Go interfaces. The *T variants now return the
restricted interface (Resource, Pool, Network) while the non-T variants
return the closable interface (ClosableResource, ClosablePool,
ClosableNetwork).

Key changes:
- Define Resource/ClosableResource, Network/ClosableNetwork,
  Pool/ClosablePool interfaces
- Unexport Pool struct → pool, Network struct → dockerNetwork
- Remove ~115 lines of manual delegation boilerplate
- ConnectToNetwork/DisconnectFromNetwork/GetIPInNetwork now accept the
  Network interface directly, removing the ManagedNetwork.Network()
  escape hatch
- Add NewResource constructor for external unit tests
- Convert examples/cleanup/main.go to TestExplicitCleanup test

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

* docs: fix three inaccuracies in UPGRADE.md

- var pool *dockertest.Pool → var pool dockertest.ClosablePool
  (pointer-to-interface is meaningless; NewPool returns ClosablePool)
- CloseT example: RunT returns Resource (no CloseT); use Run to get
  ClosableResource when explicit teardown is needed
- Registry function signatures: add return types (error, bool, slice)

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

* chore: apply formatting

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

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: aeneasr

README.md

@@ -239,14 +239,10 @@ resource := pool.RunT(t, "postgres",
 
 ### Container reuse
 
-> [!WARNING]
->
-> Do not use `resource.Cleanup(t)` on reused containers. Because reused
-> containers are shared across tests, cleaning up one reference will remove the
-> container for all other tests that depend on it. Only use `pool.Close(ctx)` in
-> `TestMain` to clean up reused containers after all tests have finished.
-
-Containers are automatically reused based on `repository:tag`:
+Containers are automatically reused based on `repository:tag`. Reuse is
+reference-counted: each `Run`/`RunT` call increments the ref count, and each
+`Close`/cleanup decrements it. The container is only removed from Docker when
+the last reference is released.
 
 ```go
 // First test creates container
@@ -402,39 +398,38 @@ net, err := pool.CreateNetwork(ctx, "my-network", &dockertest.NetworkCreateOptio
 
 ### Cleanup
 
-> [!WARNING]
->
-> Do not use `resource.Cleanup(t)` or `resource.CloseT(t)` on **reused**
-> containers. Because reused containers are shared across tests, cleaning up one
-> reference removes the container for all other tests. Use `pool.Close(ctx)` in
-> `TestMain` to clean up reused containers after all tests finish.
-
-Use `Cleanup(t)` for **non-reused** containers — it registers `t.Cleanup` and
-logs errors without failing the test:
+**`NewPoolT` + `RunT` (recommended):** Cleanup is fully automatic. `RunT`
+registers cleanup via `t.Cleanup`, and the pool is closed when the test
+finishes. Nothing to do.
 
 ```go
-resource := pool.RunT(t, "postgres",
-    dockertest.WithTag("14"),
-    dockertest.WithoutReuse(),
-)
-resource.Cleanup(t) // removed when t finishes
+func TestDB(t *testing.T) {
+    pool := dockertest.NewPoolT(t, "")
+    resource := pool.RunT(t, "postgres", dockertest.WithTag("14"))
+    // Use resource... cleanup happens automatically when t finishes.
+}
 ```
 
-Use `CloseT(t)` when you need **immediate** cleanup and want a hard failure on
-error (calls `t.Fatalf`):
+**`NewPool` + `Run`:** Call `resource.Close(ctx)` to release individual
+containers, or `pool.Close(ctx)` to release everything:
 
 ```go
-resource.CloseT(t) // removes now, fails test on error
-```
-
-Use `Close(ctx)` in non-test code for manual cleanup:
+ctx := context.Background()
+pool, err := dockertest.NewPool(ctx, "")
+if err != nil {
+    panic(err)
+}
+defer pool.Close(ctx) // releases all tracked containers and networks
 
-```go
-err := resource.Close(ctx)
+resource, err := pool.Run(ctx, "postgres", dockertest.WithTag("14"))
+if err != nil {
+    panic(err)
+}
+defer resource.Close(ctx) // or let pool.Close handle it
 ```
 
-Use `pool.Close(ctx)` to clean up **all** resources (reused and non-reused),
-typically in `TestMain`:
+**Advanced: shared pool in `TestMain`:** Use this when you need a single pool
+shared across all tests in a package:
 
 ```go
 func TestMain(m *testing.M) {

UPGRADE.md

@@ -57,11 +57,11 @@ intended due to Docker API limitations.
 v4 offers two pool creation patterns for tests. **Choose A or B per package, do
 not mix them** — mixing causes double-close or resource leaks.
 
-**Option A: `NewPoolT` (recommended for most tests)**
+**Option A: `NewPoolT` (recommended for most tests — no `TestMain` needed)**
 
 `NewPoolT` registers cleanup automatically via `t.Cleanup`. All tracked
-containers and networks are removed when the test finishes. No `TestMain`
-needed.
+containers and networks are removed when the test finishes. Self-contained: no
+`TestMain` needed.
 
 ```go
 // v4 — cleanup is automatic
@@ -70,14 +70,14 @@ pool := dockertest.NewPoolT(t, "",
 )
 ```
 
-**Option B: `NewPool` + `TestMain` (for shared pools across tests)**
+**Option B: `NewPool` + `TestMain` (for shared pools — advanced)**
 
 Use this when you want a single pool shared across all tests in a package. You
 must call `pool.Close(ctx)` explicitly.
 
 ```go
 // v4 — shared pool, manual cleanup
-var pool *dockertest.Pool
+var pool dockertest.ClosablePool
 
 func TestMain(m *testing.M) {
     ctx := context.Background()
@@ -254,8 +254,8 @@ Available sentinel errors: `ErrImagePullFailed`, `ErrContainerCreateFailed`,
    - `pool.Purge(resource)` → automatic via `NewPoolT`, or `pool.Close(ctx)` in
      `TestMain`
    - `pool.Retry(fn)` → `pool.Retry(ctx, timeout, fn)`
-   - For non-reused containers needing per-test cleanup: `WithoutReuse()` +
-     `resource.Cleanup(t)`
+   - For non-reused containers: use `WithoutReuse()` (cleanup is automatic with
+     `RunT`, or call `resource.Close(ctx)` with `Run`)
    - See [Breaking Changes](#breaking-changes) for full patterns.
 
 4. **Test:** Run `go test ./...` to verify the migration.
@@ -315,14 +315,6 @@ cache := pool.RunT(t, "redis", dockertest.WithTag("7"))
 > containers that share an image but differ in configuration (see
 > [Custom Reuse ID](#custom-reuse-id-different-configs) below).
 
-> [!WARNING]
->
-> Do not use `resource.Cleanup(t)` on reused containers. Because reused
-> containers are shared across tests, cleaning up one reference will remove the
-> container for all other tests that depend on it. Only use `pool.Close(ctx)`
-> (automatic with `NewPoolT`) to clean up reused containers after all tests have
-> finished.
-
 v4 automatically reuses containers with the same `repo:tag` across tests. Each
 `NewPoolT` call creates a separate pool, but containers are still shared because
 default pools use a common reuse scope:
@@ -346,7 +338,7 @@ resource := pool.RunT(t, "postgres",
     dockertest.WithTag("14"),
     dockertest.WithoutReuse(),
 )
-resource.Cleanup(t) // Safe — this container is not shared
+// Cleanup is automatic via RunT
 ```
 
 ### Custom Reuse ID (Different Configs)
@@ -437,9 +429,11 @@ v4 maintains a global in-memory registry for container reuse. You typically do
 not need these functions directly — `Pool.Run` and `Pool.RunT` use them
 automatically. They are useful for custom cleanup or inspection:
 
-- `Register(reuseID, resource)` — stores a resource (idempotent; keeps existing)
-- `Get(reuseID)` — retrieves a resource by reuse ID
-- `GetAll()` — returns all registered resources
+- `Register(reuseID string, r ClosableResource) error` — stores a resource
+  (idempotent; keeps existing)
+- `Get(reuseID string) (ClosableResource, bool)` — retrieves a resource by reuse
+  ID
+- `GetAll() []ClosableResource` — returns all registered resources
 - `ResetRegistry()` — clears the registry (does **not** stop containers)
 
 ### Immediate Cleanup with `CloseT`
@@ -449,7 +443,10 @@ and calls `t.Fatalf` on error. Use this when you need teardown at a specific
 point rather than relying on pool-scoped cleanup:
 
 ```go
-resource := pool.RunT(t, "postgres", dockertest.WithTag("14"), dockertest.WithoutReuse())
+resource, err := pool.Run(t.Context(), "postgres", dockertest.WithTag("14"), dockertest.WithoutReuse())
+if err != nil {
+    t.Fatal(err)
+}
 // ... use resource ...
 resource.CloseT(t) // immediate removal
 ```

build.go

@@ -74,7 +74,7 @@ type BuildOptions struct {
 //		panic(err)
 //	}
 //	defer resource.Close(ctx)
-func (p *Pool) BuildAndRun(ctx context.Context, name string, buildOpts *BuildOptions, runOpts ...RunOption) (*Resource, error) {
+func (p *pool) BuildAndRun(ctx context.Context, name string, buildOpts *BuildOptions, runOpts ...RunOption) (ClosableResource, error) {
 	if buildOpts == nil {
 		return nil, fmt.Errorf("buildOpts cannot be nil")
 	}
@@ -160,14 +160,18 @@ func (p *Pool) BuildAndRun(ctx context.Context, name string, buildOpts *BuildOpt
 }
 
 // BuildAndRunT is a test helper that uses t.Context() and calls t.Fatalf on error.
-func (p *Pool) BuildAndRunT(t TestingTB, name string, buildOpts *BuildOptions, runOpts ...RunOption) *Resource {
+// The returned ManagedResource does not expose Close, CloseT, or Cleanup;
+// the resource is automatically cleaned up when the test finishes.
+func (p *pool) BuildAndRunT(t TestingTB, name string, buildOpts *BuildOptions, runOpts ...RunOption) Resource {
 	t.Helper()
 
 	r, err := p.BuildAndRun(t.Context(), name, buildOpts, runOpts...)
 	if err != nil {
 		t.Fatalf("BuildAndRunT failed: %v", err)
 	}
 
+	r.Cleanup(t)
+
 	return r
 }
 

build_test.go

@@ -54,8 +54,6 @@ CMD ["sleep", "300"]
 		t.Fatal("Resource has empty container ID")
 	}
 
-	// Cleanup
-	r.CloseT(t)
 }
 
 func TestBuildAndRunWithBuildArgs(t *testing.T) {
@@ -93,7 +91,6 @@ CMD ["sh", "-c", "echo TEST_ENV=$TEST_ENV && sleep 300"]
 	}
 
 	r := pool.BuildAndRunT(t, "test-build-args", buildOpts)
-	t.Cleanup(func() { r.Close(t.Context()) })
 
 	// Verify build arg was applied by checking container env via logs
 	var logs string
@@ -146,7 +143,6 @@ CMD ["sh", "-c", "echo $TEST_VAR && sleep 300"]
 	r := pool.BuildAndRunT(t, "test-build-env", buildOpts,
 		dockertest.WithEnv([]string{"TEST_VAR=hello"}),
 	)
-	t.Cleanup(func() { r.Close(t.Context()) })
 
 	// Verify env var took effect via logs
 	var logs string
@@ -213,8 +209,6 @@ func TestBuildAndRunWithBuildContext(t *testing.T) {
 		t.Fatalf("Expected logs to contain 'Hello, World!', got: %s (error: %v)", logs, err)
 	}
 
-	// Cleanup
-	r.CloseT(t)
 }
 
 func TestBuildAndRunWithTaggedName(t *testing.T) {
@@ -244,11 +238,9 @@ CMD ["sleep", "300"]
 		ContextDir: tmpDir,
 	})
 
-	if r.Container.Config.Image != imageRef {
-		t.Fatalf("container image = %q, want %q", r.Container.Config.Image, imageRef)
+	if r.Container().Config.Image != imageRef {
+		t.Fatalf("container image = %q, want %q", r.Container().Config.Image, imageRef)
 	}
-
-	r.CloseT(t)
 }
 
 func TestRunUsesLocalImageWithoutPull(t *testing.T) {
@@ -275,15 +267,13 @@ CMD ["sleep", "300"]
 	// If Run attempts a pull, this registry will fail DNS resolution.
 	repository := "example.invalid/dockertest-local-skip-pull"
 
-	first := pool.BuildAndRunT(t, repository, &dockertest.BuildOptions{
+	pool.BuildAndRunT(t, repository, &dockertest.BuildOptions{
 		Dockerfile: "Dockerfile",
 		ContextDir: tmpDir,
 	}, dockertest.WithoutReuse())
-	first.CloseT(t)
 
-	second := pool.RunT(t, repository,
+	pool.RunT(t, repository,
 		dockertest.WithTag("latest"),
 		dockertest.WithoutReuse(),
 	)
-	second.CloseT(t)
 }