[CLD-518]: fix(anvil): fix nil pointer when T is not provided (#313)

Because anvil provider can be used outside of testing, the testing.T is
not available, however currently , when it is not provided, the code
returns nil pointer error during the call to
testcontainers.CleanupContainer, this fix handles that scenario and
provide a dedicated method for cleaning up container.

```
// Usage in production/non-test contexts with manual cleanup:
//
//	func main() {
//		var once sync.Once
//		config := CTFAnvilChainProviderConfig{
//			Once:           &once,
//			ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
//			Port:           "8545", // T not required when Port is provided
//		}
//
//		provider := NewCTFAnvilChainProvider(chainSelector, config)
//		blockchain, err := provider.Initialize(context.Background())
//		if err != nil {
//			log.Fatal(err)
//		}
//
//		// Use the blockchain...
//
//		// Important: Clean up the container when done
//		defer func() {
//			if err := provider.Cleanup(context.Background()); err != nil {
//				log.Printf("Failed to cleanup container: %v", err)
//			}
//		}()
//	}

```

When used in testing environment (passing in testing.T), container will
be auto cleaned up.

JIRA: https://smartcontract-it.atlassian.net/browse/CLD-518

Author: graham-chainlink

.changeset/tricky-trams-sin.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": patch
+---
+
+fix(anvil): fix nil pointer when T is not provided

chain/evm/provider/ctf_anvil_provider.go

@@ -148,6 +148,32 @@
 //		// Chain ID is automatically derived from the chainSelector
 //	}
 //
+// Usage in production/non-test contexts with manual cleanup:
+//
+//	func main() {
+//		var once sync.Once
+//		config := CTFAnvilChainProviderConfig{
+//			Once:           &once,
+//			ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
+//			Port:           "8545", // T not required when Port is provided
+//		}
+//
+//		provider := NewCTFAnvilChainProvider(chainSelector, config)
+//		blockchain, err := provider.Initialize(context.Background())
+//		if err != nil {
+//			log.Fatal(err)
+//		}
+//
+//		// Use the blockchain...
+//
+//		// Important: Clean up the container when done
+//		defer func() {
+//			if err := provider.Cleanup(context.Background()); err != nil {
+//				log.Printf("Failed to cleanup container: %v", err)
+//			}
+//		}()
+//	}
+//
 // # Chain Selectors
 //
 // Common chain selectors for Anvil testing:
@@ -308,8 +334,9 @@ type CTFAnvilChainProvider struct {
 	selector uint64
 	config   CTFAnvilChainProviderConfig
 
-	chain   *evm.Chain
-	httpURL string
+	chain     *evm.Chain
+	httpURL   string
+	container testcontainers.Container
 }
 
 // NewCTFAnvilChainProvider creates a new CTFAnvilChainProvider with the given selector and
@@ -474,6 +501,28 @@ func (p *CTFAnvilChainProvider) GetNodeHTTPURL() string {
 	return p.httpURL
 }
 
+// Cleanup terminates the Anvil container and cleans up associated resources.
+//
+// This method provides explicit control over container lifecycle, which is especially
+// important when the provider is used outside of test contexts where automatic cleanup
+// via testcontainers.CleanupContainer is not available.
+//
+// It's safe to call this method multiple times - subsequent calls will be no-ops if
+// the container has already been terminated.
+//
+// Returns an error if the container termination fails.
+func (p *CTFAnvilChainProvider) Cleanup(ctx context.Context) error {
+	if p.container != nil {
+		err := p.container.Terminate(ctx)
+		if err != nil {
+			return fmt.Errorf("failed to terminate Anvil container: %w", err)
+		}
+		p.container = nil // Clear the reference after successful termination
+	}
+
+	return nil
+}
+
 // startContainer starts a CTF container for the Anvil EVM returning the HTTP URL of the node.
 //
 // This method handles the Docker container lifecycle including:
@@ -534,7 +583,13 @@ func (p *CTFAnvilChainProvider) startContainer(ctx context.Context, chainID stri
 			return "", fmt.Errorf("failed to create Anvil container: %w", rerr)
 		}
 
-		testcontainers.CleanupContainer(p.config.T, output.Container)
+		// Store container reference for manual cleanup
+		p.container = output.Container
+
+		// Only register cleanup if T is available (for test cleanup)
+		if p.config.T != nil {
+			testcontainers.CleanupContainer(p.config.T, output.Container)
+		}
 
 		return output.Nodes[0].ExternalHTTPUrl, nil
 	},

chain/evm/provider/ctf_anvil_provider_test.go

@@ -2,10 +2,12 @@ package provider
 
 import (
 	"context"
+	"strconv"
 	"sync"
 	"testing"
 	"time"
 
+	"github.com/smartcontractkit/freeport"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
@@ -33,7 +35,7 @@ func TestCTFAnvilChainProvider_Initialize(t *testing.T) {
 	assert.Equal(t, selector, provider.ChainSelector())
 	assert.Equal(t, "Anvil EVM CTF Chain Provider", provider.Name())
 
-	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+	ctx, cancel := context.WithTimeout(t.Context(), 5*time.Minute)
 	defer cancel()
 
 	// Initialize the provider
@@ -281,7 +283,7 @@ func TestCTFAnvilChainProvider_InitializeErrors(t *testing.T) {
 
 			provider := NewCTFAnvilChainProvider(tt.selector, tt.config)
 
-			ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+			ctx, cancel := context.WithTimeout(t.Context(), 30*time.Second)
 			defer cancel()
 
 			_, err := provider.Initialize(ctx)
@@ -311,7 +313,7 @@ func TestCTFAnvilChainProvider_SignerIntegration(t *testing.T) {
 		selector := uint64(13264668187771770619) // Chain ID 31337
 		provider := NewCTFAnvilChainProvider(selector, config)
 
-		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+		ctx, cancel := context.WithTimeout(t.Context(), 5*time.Minute)
 		defer cancel()
 
 		blockchain, err := provider.Initialize(ctx)
@@ -350,7 +352,7 @@ func TestCTFAnvilChainProvider_SignerIntegration(t *testing.T) {
 		selector := uint64(13264668187771770619) // Chain ID 31337
 		provider := NewCTFAnvilChainProvider(selector, config)
 
-		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+		ctx, cancel := context.WithTimeout(t.Context(), 5*time.Minute)
 		defer cancel()
 
 		blockchain, err := provider.Initialize(ctx)
@@ -388,7 +390,7 @@ func TestCTFAnvilChainProvider_SignerIntegration(t *testing.T) {
 		selector := uint64(13264668187771770619) // Chain ID 31337
 		provider := NewCTFAnvilChainProvider(selector, config)
 
-		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+		ctx, cancel := context.WithTimeout(t.Context(), 5*time.Minute)
 		defer cancel()
 
 		blockchain, err := provider.Initialize(ctx)
@@ -427,7 +429,7 @@ func TestCTFAnvilChainProvider_SignerIntegration(t *testing.T) {
 		selector := uint64(13264668187771770619) // Chain ID 31337
 		provider := NewCTFAnvilChainProvider(selector, config)
 
-		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+		ctx, cancel := context.WithTimeout(t.Context(), 5*time.Minute)
 		defer cancel()
 
 		blockchain, err := provider.Initialize(ctx)
@@ -462,7 +464,7 @@ func TestCTFAnvilChainProvider_SignerIntegration(t *testing.T) {
 		selector := uint64(13264668187771770619) // Chain ID 31337
 		provider := NewCTFAnvilChainProvider(selector, config)
 
-		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+		ctx, cancel := context.WithTimeout(t.Context(), 5*time.Minute)
 		defer cancel()
 
 		blockchain, err := provider.Initialize(ctx)
@@ -473,3 +475,165 @@ func TestCTFAnvilChainProvider_SignerIntegration(t *testing.T) {
 		assert.True(t, clientOptsCalled, "ClientOpts should have been called during initialization")
 	})
 }
+
+func TestCTFAnvilChainProvider_Cleanup(t *testing.T) {
+	t.Parallel()
+
+	t.Run("cleanup after initialization with T provided", func(t *testing.T) {
+		t.Parallel()
+
+		var once sync.Once
+		config := CTFAnvilChainProviderConfig{
+			Once:           &once,
+			ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
+			T:              t,
+		}
+
+		selector := uint64(13264668187771770619) // Chain ID 31337
+		provider := NewCTFAnvilChainProvider(selector, config)
+
+		ctx, cancel := context.WithTimeout(t.Context(), 5*time.Minute)
+		defer cancel()
+
+		blockchain, err := provider.Initialize(ctx)
+		require.NoError(t, err)
+		require.NotNil(t, blockchain)
+
+		assert.NotNil(t, provider.container, "Container reference should be stored after initialization")
+
+		err = provider.Cleanup(ctx)
+		require.NoError(t, err, "Cleanup should succeed")
+
+		assert.Nil(t, provider.container, "Container reference should be cleared after cleanup")
+	})
+
+	t.Run("cleanup after initialization with fixed port (T=nil)", func(t *testing.T) {
+		t.Parallel()
+
+		// Allocate a free port for this test
+		port := freeport.GetOne(t)
+		defer freeport.Return([]int{port})
+
+		var once sync.Once
+		config := CTFAnvilChainProviderConfig{
+			Once:           &once,
+			ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
+			Port:           strconv.Itoa(port), // Use allocated port to avoid conflicts
+			T:              nil,                // No T provided - simulates production usage
+		}
+
+		selector := uint64(13264668187771770619) // Chain ID 31337
+		provider := NewCTFAnvilChainProvider(selector, config)
+
+		ctx, cancel := context.WithTimeout(t.Context(), 5*time.Minute)
+		defer cancel()
+
+		blockchain, err := provider.Initialize(ctx)
+		require.NoError(t, err)
+		require.NotNil(t, blockchain)
+
+		assert.NotNil(t, provider.container, "Container reference should be stored after initialization")
+
+		err = provider.Cleanup(ctx)
+		require.NoError(t, err, "Cleanup should succeed even when T is nil")
+
+		assert.Nil(t, provider.container, "Container reference should be cleared after cleanup")
+	})
+
+	t.Run("cleanup before initialization", func(t *testing.T) {
+		t.Parallel()
+
+		var once sync.Once
+		config := CTFAnvilChainProviderConfig{
+			Once:           &once,
+			ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
+			T:              t,
+		}
+
+		selector := uint64(13264668187771770619) // Chain ID 31337
+		provider := NewCTFAnvilChainProvider(selector, config)
+
+		ctx, cancel := context.WithTimeout(t.Context(), 30*time.Second)
+		defer cancel()
+
+		// Test cleanup before initialization - should be a no-op
+		err := provider.Cleanup(ctx)
+		require.NoError(t, err, "Cleanup should succeed even when no container exists")
+
+		// Verify container is still nil
+		assert.Nil(t, provider.container, "Container reference should remain nil")
+	})
+
+	t.Run("multiple cleanup calls", func(t *testing.T) {
+		t.Parallel()
+
+		var once sync.Once
+		config := CTFAnvilChainProviderConfig{
+			Once:           &once,
+			ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
+			T:              t,
+		}
+
+		selector := uint64(13264668187771770619) // Chain ID 31337
+		provider := NewCTFAnvilChainProvider(selector, config)
+
+		ctx, cancel := context.WithTimeout(t.Context(), 5*time.Minute)
+		defer cancel()
+
+		blockchain, err := provider.Initialize(ctx)
+		require.NoError(t, err)
+		require.NotNil(t, blockchain)
+
+		// First cleanup
+		err = provider.Cleanup(ctx)
+		require.NoError(t, err, "First cleanup should succeed")
+		assert.Nil(t, provider.container, "Container reference should be cleared after first cleanup")
+
+		// Second cleanup - should be a no-op
+		err = provider.Cleanup(ctx)
+		require.NoError(t, err, "Second cleanup should succeed (no-op)")
+		assert.Nil(t, provider.container, "Container reference should remain nil after second cleanup")
+
+		// Third cleanup - should still be a no-op
+		err = provider.Cleanup(ctx)
+		require.NoError(t, err, "Third cleanup should succeed (no-op)")
+		assert.Nil(t, provider.container, "Container reference should remain nil after third cleanup")
+	})
+
+	t.Run("cleanup with cancelled context", func(t *testing.T) {
+		t.Parallel()
+
+		var once sync.Once
+		config := CTFAnvilChainProviderConfig{
+			Once:           &once,
+			ConfirmFunctor: ConfirmFuncGeth(2 * time.Minute),
+			T:              t,
+		}
+
+		selector := uint64(13264668187771770619) // Chain ID 31337
+		provider := NewCTFAnvilChainProvider(selector, config)
+
+		ctx, cancel := context.WithTimeout(t.Context(), 5*time.Minute)
+		defer cancel()
+
+		blockchain, err := provider.Initialize(ctx)
+		require.NoError(t, err)
+		require.NotNil(t, blockchain)
+
+		cancelledCtx, cancelFunc := context.WithCancel(t.Context())
+		cancelFunc() // Cancel immediately
+
+		// Test cleanup with cancelled context - should return an error
+		err = provider.Cleanup(cancelledCtx)
+		require.Error(t, err, "Cleanup should fail with cancelled context")
+		assert.Contains(t, err.Error(), "failed to terminate Anvil container", "Error should mention container termination failure")
+
+		// Container reference should still exist since cleanup failed
+		assert.NotNil(t, provider.container, "Container reference should remain when cleanup fails")
+
+		// Cleanup with proper context should still work
+		err = provider.Cleanup(ctx)
+		require.NoError(t, err, "Cleanup with valid context should succeed after previous failure")
+		assert.Nil(t, provider.container, "Container reference should be cleared after successful cleanup")
+	})
+}