break: return error from Customize request option

.golangci.yml

@@ -7,6 +7,7 @@ linters:
     - misspell
     - nonamedreturns
     - testifylint
+    - errcheck
 
 linters-settings:
   errorlint:

docker_test.go

@@ -2123,7 +2123,7 @@ func TestDockerProvider_BuildImage_Retries(t *testing.T) {
 		},
 		{
 			name:        "no retry when not implemented by provider",
-			errReturned: errdefs.NotImplemented(errors.New("unkown method")),
+			errReturned: errdefs.NotImplemented(errors.New("unknown method")),
 			shouldRetry: false,
 		},
 		{
@@ -2169,7 +2169,7 @@ func TestDockerProvider_waitContainerCreation_retries(t *testing.T) {
 		},
 		{
 			name:        "no retry when not implemented by provider",
-			errReturned: errdefs.NotImplemented(errors.New("unkown method")),
+			errReturned: errdefs.NotImplemented(errors.New("unknown method")),
 			shouldRetry: false,
 		},
 		{
@@ -2235,7 +2235,7 @@ func TestDockerProvider_attemptToPullImage_retries(t *testing.T) {
 		},
 		{
 			name:        "no retry when not implemented by provider",
-			errReturned: errdefs.NotImplemented(errors.New("unkown method")),
+			errReturned: errdefs.NotImplemented(errors.New("unknown method")),
 			shouldRetry: false,
 		},
 		{

docs/modules/index.md

@@ -105,7 +105,22 @@ We are going to propose a set of steps to follow when adding types and methods t
 
 - Make sure a public `Container` type exists for the module. This type has to use composition to embed the `testcontainers.Container` type, promoting all the methods from it.
 - Make sure a `RunContainer` function exists and is public. This function is the entrypoint to the module and will define the initial values for a `testcontainers.GenericContainerRequest` struct, including the image, the default exposed ports, wait strategies, etc. Therefore, the function must initialise the container request with the default values.
-- Define container options for the module leveraging the `testcontainers.ContainerCustomizer` interface, that has one single method: `Customize(req *GenericContainerRequest)`.
+- Define container options for the module leveraging the `testcontainers.ContainerCustomizer` interface, that has one single method: `Customize(req *GenericContainerRequest) error`.
+
+!!!warning
+    The interface definition for `ContainerCustomizer` was changed to allow errors to be correctly processed.
+    More specifically, the `Customize` method was changed from:
+
+    ```go
+    Customize(req *GenericContainerRequest)
+    ```
+
+    To:
+
+    ```go
+    Customize(req *GenericContainerRequest) error
+    ```
+
 - We consider that a best practice for the options is define a function using the `With` prefix, that returns a function returning a modified `testcontainers.GenericContainerRequest` type. For that, the library already provides a `testcontainers.CustomizeRequestOption` type implementing the `ContainerCustomizer` interface, and we encourage you to use this type for creating your own customizer functions.
 - At the same time, you could need to create your own container customizers for your module. Make sure they implement the `testcontainers.ContainerCustomizer` interface. Defining your own customizer functions is useful when you need to transfer a certain state that is not present at the `ContainerRequest` for the container, possibly using an intermediate Config struct.
 - The options will be passed to the `RunContainer` function as variadic arguments after the Go context, and they will be processed right after defining the initial `testcontainers.GenericContainerRequest` struct using a for loop.
@@ -130,7 +145,9 @@ func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomize
     }
     ...
     for _, opt := range opts {
-        req = opt.Customize(&genericContainerReq)
+        if err := opt.Customize(&genericContainerReq); err != nil {
+            return nil, fmt.Errorf("customise: %w", err)
+        }
 
         // If you need to transfer some state from the options to the container, you can do it here
         if myCustomizer, ok := opt.(MyCustomizer); ok {
@@ -174,13 +191,24 @@ func (c *Container) ConnectionString(ctx context.Context) (string, error) {...}
 
 In order to simplify the creation of the container for a given module, `Testcontainers for Go` provides a set of `testcontainers.CustomizeRequestOption` functions to customize the container request for the module. These options are:
 
-- `testcontainers.CustomizeRequest`: a function that merges the default options with the ones provided by the user. Recommended for completely customizing the container request.
 - `testcontainers.WithImage`: a function that sets the image for the container request.
+- `testcontainers.WithImageSubstitutors`: a function that sets your own substitutions to the container images.
+- `testcontainers.WithEnv`: a function that sets the environment variables for the container request.
+- `testcontainers.WithHostPortAccess`: a function that enables the container to access a port that is already running in the host.
+- `testcontainers.WithLogConsumers`: a function that sets the log consumers for the container request.
+- `testcontainers.WithLogger`: a function that sets the logger for the container request.
+- `testcontainers.WithWaitStrategy`: a function that sets the wait strategy for the container request.
+- `testcontainers.WithWaitStrategyAndDeadline`: a function that sets the wait strategy for the container request with a deadline.
+- `testcontainers.WithStartupCommand`: a function that sets the execution of a command when the container starts.
+- `testcontainers.WithAfterReadyCommand`: a function that sets the execution of a command right after the container is ready (its wait strategy is satisfied).
+- `testcontainers.WithNetwork`: a function that sets the network and the network aliases for the container request.
+- `testcontainers.WithNewNetwork`: a function that sets the network aliases for a throw-away network for the container request.
 - `testcontainers.WithConfigModifier`: a function that sets the 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.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.WithWaitStrategy`: a function that sets the wait strategy for the container request, adding all the passed wait strategies to the container request, using a `testcontainers.MultiStrategy` with 60 seconds of deadline. Please see [Wait strategies](../features/wait/multi.md) for more information.
 - `testcontainers.WithWaitStrategyAndDeadline`: a function that sets the wait strategy for the container request, adding all the passed wait strategies to the container request, using a `testcontainers.MultiStrategy` with the passed deadline. Please see [Wait strategies](../features/wait/multi.md) 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.
 
 ### Update Go dependencies in the modules
 

docs/modules/localstack.md

@@ -23,7 +23,7 @@ Running LocalStack as a stand-in for multiple AWS services during a test:
 <!--/codeinclude-->
 
 Environment variables listed in [Localstack's README](https://github.com/localstack/localstack#configurations) may be used to customize Localstack's configuration. 
-Use the `OverrideContainerRequest` option when creating the `LocalStackContainer` to apply configuration settings.
+Use the `testcontainers.WithEnv` option when creating the `LocalStackContainer` to apply those variables.
 
 ## Module reference
 

logger.go

@@ -68,8 +68,9 @@ func (o LoggerOption) ApplyDockerTo(opts *DockerProviderOptions) {
 }
 
 // Customize implements ContainerCustomizer.
-func (o LoggerOption) Customize(req *GenericContainerRequest) {
+func (o LoggerOption) Customize(req *GenericContainerRequest) error {
 	req.Logger = o.logger
+	return nil
 }
 
 type testLogger struct {

logger_test.go

@@ -11,7 +11,7 @@ func TestWithLogger(t *testing.T) {
 	logOpt := WithLogger(logger)
 	t.Run("container", func(t *testing.T) {
 		var req GenericContainerRequest
-		logOpt.Customize(&req)
+		require.NoError(t, logOpt.Customize(&req))
 		require.Equal(t, logger, req.Logger)
 	})
 

modulegen/_template/module.go.tmpl

@@ -23,7 +23,9 @@ func {{ $entrypoint }}(ctx context.Context, opts ...testcontainers.ContainerCust
 	}
 
 	for _, opt := range opts {
-		opt.Customize(&genericContainerReq)
+		if err := opt.Customize(&genericContainerReq); err != nil {
+			return nil, fmt.Errorf("customize: %w", err)
+		}
 	}
 
 	container, err := testcontainers.GenericContainer(ctx, genericContainerReq)

modulegen/main_test.go

@@ -428,7 +428,9 @@ func assertModuleContent(t *testing.T, module context.TestcontainersModule, exam
 	assert.Equal(t, data[13], "// "+entrypoint+" creates an instance of the "+exampleName+" container type")
 	assert.Equal(t, data[14], "func "+entrypoint+"(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*"+containerName+", error) {")
 	assert.Equal(t, data[16], "\t\tImage: \""+module.Image+"\",")
-	assert.Equal(t, data[33], "\treturn &"+containerName+"{Container: container}, nil")
+	assert.Equal(t, data[25], "\t\tif err := opt.Customize(&genericContainerReq); err != nil {")
+	assert.Equal(t, data[26], "\t\t\treturn nil, fmt.Errorf(\"customize: %w\", err)")
+	assert.Equal(t, data[35], "\treturn &"+containerName+"{Container: container}, nil")
 }
 
 // assert content GitHub workflow for the module

modules/artemis/artemis.go

@@ -49,16 +49,20 @@ func (c *Container) ConsoleURL(ctx context.Context) (string, error) {
 
 // WithCredentials sets the administrator credentials. The default is artemis:artemis.
 func WithCredentials(user, password string) testcontainers.CustomizeRequestOption {
-	return func(req *testcontainers.GenericContainerRequest) {
+	return func(req *testcontainers.GenericContainerRequest) error {
 		req.Env["ARTEMIS_USER"] = user
 		req.Env["ARTEMIS_PASSWORD"] = password
+
+		return nil
 	}
 }
 
 // WithAnonymousLogin enables anonymous logins.
 func WithAnonymousLogin() testcontainers.CustomizeRequestOption {
-	return func(req *testcontainers.GenericContainerRequest) {
+	return func(req *testcontainers.GenericContainerRequest) error {
 		req.Env["ANONYMOUS_LOGIN"] = "true"
+
+		return nil
 	}
 }
 
@@ -67,8 +71,10 @@ func WithAnonymousLogin() testcontainers.CustomizeRequestOption {
 // Setting this value will override the default.
 // See the documentation on `artemis create` for available options.
 func WithExtraArgs(args string) testcontainers.CustomizeRequestOption {
-	return func(req *testcontainers.GenericContainerRequest) {
+	return func(req *testcontainers.GenericContainerRequest) error {
 		req.Env["EXTRA_ARGS"] = args
+
+		return nil
 	}
 }
 
@@ -91,7 +97,9 @@ func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomize
 	}
 
 	for _, opt := range opts {
-		opt.Customize(&req)
+		if err := opt.Customize(&req); err != nil {
+			return nil, err
+		}
 	}
 
 	container, err := testcontainers.GenericContainer(ctx, req)

modules/cassandra/cassandra.go

@@ -41,19 +41,21 @@ func (c *CassandraContainer) ConnectionHost(ctx context.Context) (string, error)
 // It will also set the "configFile" parameter to the path of the config file
 // as a command line argument to the container.
 func WithConfigFile(configFile string) testcontainers.CustomizeRequestOption {
-	return func(req *testcontainers.GenericContainerRequest) {
+	return func(req *testcontainers.GenericContainerRequest) error {
 		cf := testcontainers.ContainerFile{
 			HostFilePath:      configFile,
 			ContainerFilePath: "/etc/cassandra/cassandra.yaml",
 			FileMode:          0o755,
 		}
 		req.Files = append(req.Files, cf)
+
+		return nil
 	}
 }
 
 // WithInitScripts sets the init cassandra queries to be run when the container starts
 func WithInitScripts(scripts ...string) testcontainers.CustomizeRequestOption {
-	return func(req *testcontainers.GenericContainerRequest) {
+	return func(req *testcontainers.GenericContainerRequest) error {
 		var initScripts []testcontainers.ContainerFile
 		var execs []testcontainers.Executable
 		for _, script := range scripts {
@@ -68,7 +70,7 @@ func WithInitScripts(scripts ...string) testcontainers.CustomizeRequestOption {
 		}
 
 		req.Files = append(req.Files, initScripts...)
-		testcontainers.WithAfterReadyCommand(execs...)(req)
+		return testcontainers.WithAfterReadyCommand(execs...)(req)
 	}
 }
 
@@ -100,7 +102,9 @@ func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomize
 	}
 
 	for _, opt := range opts {
-		opt.Customize(&genericContainerReq)
+		if err := opt.Customize(&genericContainerReq); err != nil {
+			return nil, err
+		}
 	}
 
 	container, err := testcontainers.GenericContainer(ctx, genericContainerReq)

modules/chroma/chroma.go

@@ -33,7 +33,9 @@ func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomize
 	}
 
 	for _, opt := range opts {
-		opt.Customize(&genericContainerReq)
+		if err := opt.Customize(&genericContainerReq); err != nil {
+			return nil, err
+		}
 	}
 
 	container, err := testcontainers.GenericContainer(ctx, genericContainerReq)

modules/clickhouse/clickhouse.go

@@ -101,34 +101,36 @@ func renderZookeeperConfig(settings ZookeeperOptions) ([]byte, error) {
 
 // WithZookeeper pass a config to connect clickhouse with zookeeper and make clickhouse as cluster
 func WithZookeeper(host, port string) testcontainers.CustomizeRequestOption {
-	return func(req *testcontainers.GenericContainerRequest) {
+	return func(req *testcontainers.GenericContainerRequest) error {
 		f, err := os.CreateTemp("", "clickhouse-tc-config-")
 		if err != nil {
-			panic(err)
+			return fmt.Errorf("temporary file: %w", err)
 		}
 
 		defer f.Close()
 
 		// write data to the temporary file
 		data, err := renderZookeeperConfig(ZookeeperOptions{Host: host, Port: port})
 		if err != nil {
-			panic(err)
+			return fmt.Errorf("zookeeper config: %w", err)
 		}
 		if _, err := f.Write(data); err != nil {
-			panic(err)
+			return fmt.Errorf("write zookeeper config: %w", err)
 		}
 		cf := testcontainers.ContainerFile{
 			HostFilePath:      f.Name(),
 			ContainerFilePath: "/etc/clickhouse-server/config.d/zookeeper_config.xml",
 			FileMode:          0o755,
 		}
 		req.Files = append(req.Files, cf)
+
+		return nil
 	}
 }
 
 // WithInitScripts sets the init scripts to be run when the container starts
 func WithInitScripts(scripts ...string) testcontainers.CustomizeRequestOption {
-	return func(req *testcontainers.GenericContainerRequest) {
+	return func(req *testcontainers.GenericContainerRequest) error {
 		initScripts := []testcontainers.ContainerFile{}
 		for _, script := range scripts {
 			cf := testcontainers.ContainerFile{
@@ -139,52 +141,62 @@ func WithInitScripts(scripts ...string) testcontainers.CustomizeRequestOption {
 			initScripts = append(initScripts, cf)
 		}
 		req.Files = append(req.Files, initScripts...)
+
+		return nil
 	}
 }
 
 // WithConfigFile sets the XML config file to be used for the clickhouse container
 // It will also set the "configFile" parameter to the path of the config file
 // as a command line argument to the container.
 func WithConfigFile(configFile string) testcontainers.CustomizeRequestOption {
-	return func(req *testcontainers.GenericContainerRequest) {
+	return func(req *testcontainers.GenericContainerRequest) error {
 		cf := testcontainers.ContainerFile{
 			HostFilePath:      configFile,
 			ContainerFilePath: "/etc/clickhouse-server/config.d/config.xml",
 			FileMode:          0o755,
 		}
 		req.Files = append(req.Files, cf)
+
+		return nil
 	}
 }
 
 // WithConfigFile sets the YAML config file to be used for the clickhouse container
 // It will also set the "configFile" parameter to the path of the config file
 // as a command line argument to the container.
 func WithYamlConfigFile(configFile string) testcontainers.CustomizeRequestOption {
-	return func(req *testcontainers.GenericContainerRequest) {
+	return func(req *testcontainers.GenericContainerRequest) error {
 		cf := testcontainers.ContainerFile{
 			HostFilePath:      configFile,
 			ContainerFilePath: "/etc/clickhouse-server/config.d/config.yaml",
 			FileMode:          0o755,
 		}
 		req.Files = append(req.Files, cf)
+
+		return nil
 	}
 }
 
 // WithDatabase sets the initial database to be created when the container starts
 // It can be used to define a different name for the default database that is created when the image is first started.
 // If it is not specified, then the default value("clickhouse") will be used.
 func WithDatabase(dbName string) testcontainers.CustomizeRequestOption {
-	return func(req *testcontainers.GenericContainerRequest) {
+	return func(req *testcontainers.GenericContainerRequest) error {
 		req.Env["CLICKHOUSE_DB"] = dbName
+
+		return nil
 	}
 }
 
 // WithPassword sets the initial password of the user to be created when the container starts
 // It is required for you to use the ClickHouse image. It must not be empty or undefined.
 // This environment variable sets the password for ClickHouse.
 func WithPassword(password string) testcontainers.CustomizeRequestOption {
-	return func(req *testcontainers.GenericContainerRequest) {
+	return func(req *testcontainers.GenericContainerRequest) error {
 		req.Env["CLICKHOUSE_PASSWORD"] = password
+
+		return nil
 	}
 }
 
@@ -193,12 +205,14 @@ func WithPassword(password string) testcontainers.CustomizeRequestOption {
 // It will create the specified user with superuser power.
 // If it is not specified, then the default user of clickhouse will be used.
 func WithUsername(user string) testcontainers.CustomizeRequestOption {
-	return func(req *testcontainers.GenericContainerRequest) {
+	return func(req *testcontainers.GenericContainerRequest) error {
 		if user == "" {
 			user = defaultUser
 		}
 
 		req.Env["CLICKHOUSE_USER"] = user
+
+		return nil
 	}
 }
 
@@ -225,7 +239,9 @@ func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomize
 	}
 
 	for _, opt := range opts {
-		opt.Customize(&genericContainerReq)
+		if err := opt.Customize(&genericContainerReq); err != nil {
+			return nil, err
+		}
 	}
 
 	container, err := testcontainers.GenericContainer(ctx, genericContainerReq)

modules/cockroachdb/cockroachdb.go

@@ -96,7 +96,9 @@ func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomize
 		if apply, ok := opt.(Option); ok {
 			apply(&o)
 		}
-		opt.Customize(&req)
+		if err := opt.Customize(&req); err != nil {
+			return nil, err
+		}
 	}
 
 	// modify request