feat: add WithReuseByName for modifying Generic Container Requests (#3064)

* added WithReuse and WithContainerName functions for modifying the
GenericContainerRequest

* Simplify API surface for WithReuse

* docs: document new option

* fix: lint

* chore: rename option to WithReuseByName

* chore: add test for the new option

* chore: simplify test assertions

---------

Co-authored-by: Manuel de la Peña <mdelapenya@gmail.com>

Author: jm96441n

docs/features/common_functional_options.md

@@ -302,3 +302,19 @@ The above example is updating the predefined command of the image, **appending**
 
 !!!info
     This can't be used to replace the command, only to append options.
+
+#### WithReuseByName
+
+- Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+This option marks a container to be reused if it exists or create a new one if it doesn't.
+With the current implementation, the container name must be provided to identify the container to be reused.
+
+```golang
+ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3", 
+    testcontainers.WithReuseByName("my-container-name"),
+)
+```
+
+!!!warning
+    Reusing a container is experimental and the API is subject to change for a more robust implementation that is not based on container names.

docs/modules/index.md

@@ -216,6 +216,7 @@ In order to simplify the creation of the container for a given module, `Testcont
 - `testcontainers.WithHostConfigModifier`: a function that sets the host config Docker type for the container request. Please see [Advanced Settings](../features/creating_container.md#advanced-settings) for more information.
 - `testcontainers.WithEndpointSettingsModifier`: a function that sets the endpoint settings Docker type for the container request. Please see [Advanced Settings](../features/creating_container.md#advanced-settings) for more information.
 - `testcontainers.CustomizeRequest`: a function that merges the default options with the ones provided by the user. Recommended for completely customizing the container request.
+- `testcontainers.WithReuseByName`: a function that marks a container to be reused if it exists or create a new one if it doesn't.
 
 ### Update Go dependencies in the modules
 

modules/ollama/ollama_test.go

@@ -71,6 +71,38 @@ func TestOllama(t *testing.T) {
 	})
 }
 
+func TestOllama_withReuse(t *testing.T) {
+	ctx := context.Background()
+
+	ctr, err := ollama.Run(ctx, "ollama/ollama:0.5.7", testcontainers.WithReuseByName("ollama-container"))
+	testcontainers.CleanupContainer(t, ctr)
+	require.NoError(t, err)
+
+	model := "all-minilm"
+
+	_, _, err = ctr.Exec(context.Background(), []string{"ollama", "pull", model})
+	require.NoError(t, err)
+
+	_, _, err = ctr.Exec(context.Background(), []string{"ollama", "run", model})
+	require.NoError(t, err)
+
+	assertLoadedModel(t, ctr)
+
+	t.Run("reuse-container", func(t *testing.T) {
+		ctr2, err := ollama.Run(ctx, "ollama/ollama:0.5.7", testcontainers.WithReuseByName("ollama-container"))
+		testcontainers.CleanupContainer(t, ctr2)
+		require.NoError(t, err)
+
+		_, _, err = ctr2.Exec(context.Background(), []string{"ollama", "pull", model})
+		require.NoError(t, err)
+
+		_, _, err = ctr2.Exec(context.Background(), []string{"ollama", "run", model})
+		require.NoError(t, err)
+
+		assertLoadedModel(t, ctr2)
+	})
+}
+
 // assertLoadedModel checks if the model is loaded in the container.
 // For that, it checks if the response of the /api/tags endpoint
 // contains the model name.

options.go

@@ -2,6 +2,7 @@ package testcontainers
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"net/url"
 	"time"
@@ -105,6 +106,19 @@ func WithHostPortAccess(ports ...int) CustomizeRequestOption {
 	}
 }
 
+// WithReuseByName will mark a container to be reused if it exists or create a new one if it doesn't.
+// A container name must be provided to identify the container to be reused.
+func WithReuseByName(containerName string) CustomizeRequestOption {
+	return func(req *GenericContainerRequest) error {
+		if containerName == "" {
+			return errors.New("container name must be provided for reuse")
+		}
+		req.Name = containerName
+		req.Reuse = true
+		return nil
+	}
+}
+
 // WithImage sets the image for a container
 func WithImage(image string) CustomizeRequestOption {
 	return func(req *GenericContainerRequest) error {

options_test.go

@@ -551,3 +551,28 @@ func TestWithDockerfile(t *testing.T) {
 	require.Equal(t, "latest", req.Tag)
 	require.Equal(t, map[string]*string{"ARG1": nil, "ARG2": nil}, req.BuildArgs)
 }
+
+func TestWithReuseByName_Succeeds(t *testing.T) {
+	t.Parallel()
+	req := &testcontainers.GenericContainerRequest{}
+	containerName := "pg-test"
+
+	opt := testcontainers.WithReuseByName(containerName)
+	err := opt.Customize(req)
+
+	require.NoError(t, err)
+	require.True(t, req.Reuse)
+	require.Equal(t, containerName, req.Name)
+}
+
+func TestWithReuseByName_ErrorsWithoutContainerNameProvided(t *testing.T) {
+	t.Parallel()
+	req := &testcontainers.GenericContainerRequest{}
+
+	opt := testcontainers.WithReuseByName("")
+	err := opt.Customize(req)
+
+	require.ErrorContains(t, err, "container name must be provided for reuse")
+	require.False(t, req.Reuse)
+	require.Empty(t, req.Name)
+}