@@ -31,3 +31,60 @@ After that, the `sessionID` will be used to:
3131- identify the test session, aggregating the test execution of multiple packages in the same test session.
3232- pass the ` sessionID ` to the container runtime, as an HTTP header to the daemon.
3333- tag the containers created by _ Testcontainers for Go_ , adding a label to the container with this session ID.
34+
35+ ## Overriding the session ID
36+
37+ Deriving the session ID from the parent process works when the processes taking part in a test session
38+ share a parent, which is the case for ` go test ` and for the IDE. When that is not true, the processes
39+ end up in different sessions: some build systems and CI setups run each test target in isolation, and
40+ the parent process they are given is not guaranteed to be stable or shared.
41+
42+ For those cases the session ID can be set explicitly, either with the ` TESTCONTAINERS_SESSION_ID `
43+ ** environment variable** or with the ` session.id ` ** property** . When set, the value is used as-is,
44+ instead of being derived, so every process configured with the same value takes part in the same session.
45+
46+ !!!warning
47+ Setting this value will preclude runs from creating more than one reaper. Therefore, changes to Ryuk
48+ settings past its creation will be ignored.
49+
50+ The session ID is used to build the name of the reaper container (` reaper_<sessionID> ` ), so a configured
51+ value must produce a name the container runtime accepts. It must:
52+
53+ - not be empty;
54+ - contain only alphanumeric characters, dots (` . ` ), hyphens (` - ` ) and underscores (` _ ` );
55+ - be at most 121 characters long, so that the resulting container name stays within the 128 character
56+ limit imposed by the container runtime.
57+
58+ A configured value that does not satisfy these constraints is rejected when the configuration is read,
59+ reporting the offending value and the reason. The session IDs generated by the library always satisfy
60+ them, so this only applies to values coming from the configuration.
61+
62+ ### Bazel
63+
64+ Bazel is a concrete example of a build system where the session ID needs to be set explicitly, because it
65+ does not provide the conditions the derivation relies on. Its
66+ [ Test Encyclopedia] ( https://bazel.build/reference/test-encyclopedia ) states that _ "the current process id,
67+ process group id, session id, and parent process id are unspecified"_ , so the parent process the library
68+ would derive the session ID from is not guaranteed to be stable or shared across test targets. Sharding
69+ makes this more visible, as the test runner is launched once per shard.
70+
71+ Two more details of the test environment matter:
72+
73+ - ` HOME ` is set to the value of ` $TEST_TMPDIR ` , a private directory for the test, so the
74+ ` ~/.testcontainers.properties ` file is not picked up.
75+ - The test environment is sanitised: tests _ "should not depend on the presence, absence, or value of any
76+ environment variable not listed"_ in the encyclopedia, so ` TESTCONTAINERS_SESSION_ID ` does not reach the
77+ test unless it is explicitly propagated.
78+
79+ That leaves the environment variable, declared with ` --test_env ` , as the way to share a session across test
80+ targets. The value can be taken from the invocation environment:
81+
82+ ``` shell
83+ bazel test //... --test_env=TESTCONTAINERS_SESSION_ID
84+ ```
85+
86+ or set independently of it:
87+
88+ ``` shell
89+ bazel test //... --test_env=TESTCONTAINERS_SESSION_ID=my-session
90+ ```
0 commit comments