feat: define test session semantics

[mdelapenya]

What does this PR do?

This PR refactors how the session ID is obtained. Instead of simply getting an UUID from the Google's library, which we will still use as default, we are going to get the current process' parent ID (parent pid) in order to make sure that any test package in the project shares the same unique identifier.

This is needed to synchronise how multiple test packages in Go are seen from the test execution standpoint: because each Go package will be compiled, packaged and tested in a separate binary, and because "go test" will call all of those test binaries for running tests, we need a way to aggregate the execution into one single hash representing that test execution. By test execution 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, the new code will use the parent process ID (pid) of the current process and 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 ./...".

For getting an unique representation of the test session, we are creating the following hash:

sessionID := hash("testcontainers-go:${parentPid}:${parentPidCreationTime})

As a consequence, the reaper (Ryuk) has to be started just once across the entire test session, so we have implemented a way to look up the Ryuk container, and if it exists, create our own reaper instance from the raw representation of the underlying container. With this, Ryuk should be started just once, killing all containers in the test session. The diagram for getting Ryuk:

graph TD
    classDef red fill:#ff7e6b, color: #fff;
    classDef green fill:#6fd890;
    classDef yellow fill:#fff68f;
    classDef blue fill:#668aff, color: #fff;

    G0[Goroutine 0] --> Mutex((sync.Mutex))
    G1[Goroutine 1] --> Mutex
    G2[Goroutine 2] --> Mutex
    G3[Goroutine 3] --> Mutex
    Gn[Goroutine n] --> Mutex
    Mutex --> InstanceNil{"reaperInstance == nil"}
    InstanceNil -- yes --> LookupDocker{"reaper in Docker"}
    InstanceNil -- no --> ReaperInstance(Reaper Instance)
    LookupDocker -- no --> Once((sync.Once))
    LookupDocker -- yes --> ReadFromDocker["Read instance from Docker"]
    ReadFromDocker --> ReaperInstance
    Once --> CreateReaper["Create Reaper Container"]
    CreateReaper --> ReaperInstance

    class Mutex,Once red
    class CreateReaper green
    class InstanceNil,LookupDocker yellow
    class ReadFromDocker blue

Loading

Then, Ryuk has to label all the containers in the session properly, including the sessionID, which will be the label used to kill them, among others that we use, such as the testcontainers language. For that reason, we have simplified how the container labels are spread across the codebase, keeping an internal DefaultLabels function, which will set the default labels for a given sessionID (helpful for tests too).

Why is it important?

A perfect use case to consume this unique identifier for a test execution would be Ryuk: avoid multiple instances per Go package. Therefore, Ryuk will label all containers in a test session to kill them. As a consequence, Ryuk has to be started just once across the entire test session.

[netlify]

✅ Deploy Preview for testcontainers-go ready!

Name	Link
🔨 Latest commit	765221e
🔍 Latest deploy log	https://app.netlify.com/sites/testcontainers-go/deploys/6508632231fc6f0008371ec2
😎 Deploy Preview	https://deploy-preview-1513--testcontainers-go.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.