feat: make the session ID configurable

This allows for long-running sessions - e.g., across multiple runs - to
reuse the reaper.

Author: jcmfernandes

internal/config/config.go

@@ -52,6 +52,13 @@ type Config struct {
 	// Environment variable: TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX
 	HubImageNamePrefix string `properties:"hub.image.name.prefix,default="`
 
+	// SessionID is the ID of the testing session.
+	// Setting this value will preclude runs from creating more than one reaper. Therefore,
+	// changes to ryuk settings past its creation will be ignored.
+	//
+	// Environment variable: TESTCONTAINERS_SESSION_ID
+	SessionID string `properties:"session.id,default="`
+
 	// RyukDisabled is a flag to enable or disable the Garbage Collector.
 	// Setting this to true will prevent testcontainers from automatically cleaning up
 	// resources, which is particularly important in tests which timeout as they
@@ -111,6 +118,11 @@ func read() Config {
 	config := Config{}
 
 	applyEnvironmentConfiguration := func(config Config) Config {
+		sessionID := os.Getenv("TESTCONTAINERS_SESSION_ID")
+		if sessionID != "" {
+			config.SessionID = sessionID
+		}
+
 		ryukDisabledEnv := os.Getenv("TESTCONTAINERS_RYUK_DISABLED")
 		if parseBool(ryukDisabledEnv) {
 			config.RyukDisabled = ryukDisabledEnv == "true"

internal/core/bootstrap.go

@@ -1,36 +1,14 @@
 package core
 
 import (
-	"crypto/sha256"
-	"encoding/hex"
-	"fmt"
 	"os"
 
 	"github.com/google/uuid"
 	"github.com/shirou/gopsutil/v4/process"
+	"github.com/testcontainers/testcontainers-go/internal/config"
 )
 
-// sessionID returns a unique session ID for the current test session. Because each Go package
-// will be run in a separate process, we need a way to identify the current test session.
-// By test session, we mean:
-//   - a single "go test" invocation (including flags)
-//   - a single "go test ./..." invocation (including flags)
-//   - the execution of a single test or a set of tests using the IDE
-//
-// As a consequence, with the sole goal of aggregating test execution across multiple
-// packages, this function will use the parent process ID (pid) of the current process
-// and its creation date, to use it to generate a unique session ID. We are using the parent pid because
-// the current process will be a child process of:
-//   - the process that is running the tests, e.g.: "go test";
-//   - the process that is running the application in development mode, e.g. "go run main.go -tags dev";
-//   - the process that is running the tests in the IDE, e.g.: "go test ./...".
-//
-// Finally, we will hash the combination of the "testcontainers-go:" string with the parent pid
-// and the creation date of that parent process to generate a unique session ID.
-//
-// This sessionID will be used to:
-//   - identify the test session, aggregating the test execution of multiple packages in the same test session.
-//   - tag the containers created by testcontainers-go, adding a label to the container with the session ID.
+// sessionID returns a unique session ID for the current test session.
 var sessionID string
 
 // projectPath returns the current working directory of the parent test process running Testcontainers for Go.
@@ -42,13 +20,17 @@ var projectPath string
 // we need a way to identify the current test process, in the form of a UUID
 var processID string
 
-const sessionIDPlaceholder = "testcontainers-go:%d:%d"
-
 func init() {
+	cfg := config.Read()
+	if cfg.SessionID != "" {
+		sessionID = cfg.SessionID
+	} else {
+		sessionID = uuid.New().String()
+	}
+
 	processID = uuid.New().String()
 
 	parentPid := os.Getppid()
-	var createTime int64
 	fallbackCwd, err := os.Getwd()
 	if err != nil {
 		// very unlikely to fail, but if it does, we will use a temp dir
@@ -57,7 +39,6 @@ func init() {
 
 	processes, err := process.Processes()
 	if err != nil {
-		sessionID = uuid.New().String()
 		projectPath = fallbackCwd
 		return
 	}
@@ -73,24 +54,8 @@ func init() {
 		}
 		projectPath = cwd
 
-		t, err := p.CreateTime()
-		if err != nil {
-			sessionID = uuid.New().String()
-			return
-		}
-
-		createTime = t
 		break
 	}
-
-	hasher := sha256.New()
-	_, err = hasher.Write([]byte(fmt.Sprintf(sessionIDPlaceholder, parentPid, createTime)))
-	if err != nil {
-		sessionID = uuid.New().String()
-		return
-	}
-
-	sessionID = hex.EncodeToString(hasher.Sum(nil))
 }
 
 func ProcessID() string {