feat: allow overriding the session ID

[jcmfernandes]

What does this PR do?

Makes the session ID configurable, allowing for long-running sessions.

Why is it important?

Speaking of my use-case, Apache Pulsar takes a long time to boot, so I wanted testcontainers to boot it up, eventually take it down, but allow me to use the same container across several runs. This wasn't the case, since I was getting a new reaper running on every test run. I wanted a rolling-window behavior, hence this change.

Related issues

• Closes [Feature]: Support a reuseWindow for cleaning up reusable containers if no tests run within a certain duration #2804

Follow-ups

Update the documentation.

[netlify]

✅ Deploy Preview for testcontainers-go ready!

Name	Link
🔨 Latest commit	01dc605
🔍 Latest deploy log	https://app.netlify.com/projects/testcontainers-go/deploys/691f47766a4c9a000817bad0
😎 Deploy Preview	https://deploy-preview-3051--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 project configuration.

[kiview]

Hey @jcmfernandes, I am actually surprised your setup doesn't work with the current Test Session Semantics.

Also, your change doesn't take the parent PID into account anymore, so it would be a breaking change for downstream integrations, that rely on the current session ID semantics.

[jcmfernandes]

Hey @jcmfernandes, I am actually surprised your setup doesn't work with the current Test Session Semantics.

Also, your change doesn't take the parent PID into account anymore, so it would be a breaking change for downstream integrations, that rely on the current session ID semantics.

Thanks for getting back to me.

Without these changes, every go test ./... run create a new instance of the reaper, and I'm not alone (#2804).

As stated in the PR description:

Regarding point 3, I must admit that I don't understand the advantages of the hashing logic I ended up deleting. I'm happy to revert it, though.

I'm happy to revert those changes, but so far, setting the session ID myself (through an env var) has been the only solution that worked for me.

[kiview]

Without these changes, every go test ./... run create a new instance of the reaper

Alright, that is how it is supposed to work.
But what it sounds to me from what you are trying to achieve, it sounds you need Reusable Containers.

Either way, the semantics around sessions IDs and cleanup behavior are fairly involved. I'd suggest to not proceed with this work without specifically syncing with @mdelapenya and @stevenh on the design.

[jcmfernandes]

Without these changes, every go test ./... run create a new instance of the reaper

Alright, that is how it is supposed to work. But what it sounds to me from what you are trying to achieve, it sounds you need Reusable Containers.

Either way, the semantics around sessions IDs and cleanup behavior are fairly involved. I'd suggest to not proceed with this work without specifically syncing with @mdelapenya and @stevenh on the design.

Thanks for the pointers. @mdelapenya and @stevenh, your input is very much welcome.

But what it sounds to me from what you are trying to achieve, it sounds you need Reusable Containers.

I am using a reusable container, and the container was always reused as expected; no issues there. The problem is that the reaper isn't reused because the session ID keeps changing.

[jcmfernandes]

Also, your change doesn't take the parent PID into account anymore, so it would be a breaking change for downstream integrations, that rely on the current session ID semantics.

I pushed a new commit that brings back the logic I had previously removed. This shouldn't break things for anyone anymore.

[stevenh]

Hi @jcmfernandes can you clarify to me the problem you're trying to solve?

Your description seems to indicate to me you want to share containers between tests due to the slow startup time?

[jcmfernandes]

Hi @jcmfernandes can you clarify to me the problem you're trying to solve?

Your description seems to indicate to me you want to share containers between tests due to the slow startup time?

Hi @stevenh! Correct. In other words, I want:

1. Reusable containers (all good!)
2. Reusable reapers for reusable containers (not good)

Copying from #2804, this is what I see when I enable reusable containers:

CONTAINER ID  IMAGE                                                  COMMAND     CREATED             STATUS             PORTS                                                                   NAMES
b551cb564516  docker.io/testcontainers/ryuk:0.8.1                    /bin/ryuk   2 minutes ago       Up 2 minutes       0.0.0.0:39033->8080/tcp, 8080/tcp                                       reaper_42d84025974814469f367f10224b4657f7ad888e2a5d827e76703f06292c39ec
5a7876b38a26  docker.io/mysql:8.0.36                                 mysqld      2 minutes ago       Up 2 minutes       0.0.0.0:42559->3306/tcp, 0.0.0.0:44633->33060/tcp, 3306/tcp, 33060/tcp  tests-mysql
c93fdf315582  docker.io/testcontainers/ryuk:0.8.1                    /bin/ryuk   2 minutes ago       Up 2 minutes       0.0.0.0:34995->8080/tcp, 8080/tcp                                       reaper_3ccf995c484a246a36990a92f85c3fc17ffb3912f867ba70b029aaf323f48547
e63820a62ce3  docker.io/testcontainers/ryuk:0.8.1                    /bin/ryuk   2 minutes ago       Up 2 minutes       0.0.0.0:44359->8080/tcp, 8080/tcp                                       reaper_fe49fa57fcc7031f3d1e9dbb6f305a2f4b392d1b10921d42b6a0df56e4970667
56d082f1fbbd  docker.io/testcontainers/ryuk:0.8.1                    /bin/ryuk   About a minute ago  Up About a minute  0.0.0.0:38461->8080/tcp, 8080/tcp                                       reaper_669ec11b7226f1c446fddd1a0e3f1aadfd1627687ed6adf3b5c846e66ecbe276
9922c527850c  docker.io/testcontainers/ryuk:0.8.1                    /bin/ryuk   About a minute ago  Up About a minute  0.0.0.0:34041->8080/tcp, 8080/tcp                                       reaper_74976de06285397df7d0edffbdd2e5fd284cf833f5b3de025705fbcad5e3608b
c76bcd09a892  docker.io/testcontainers/ryuk:0.8.1                    /bin/ryuk   52 seconds ago      Up 52 seconds      0.0.0.0:32785->8080/tcp, 8080/tcp                                       reaper_6e46bea7477b04a07464880892df435bdbd55753551da0d80b51d8917f4ab094
df476617ebdf  docker.io/testcontainers/ryuk:0.8.1                    /bin/ryuk   42 seconds ago      Up 42 seconds      0.0.0.0:39403->8080/tcp, 8080/tcp                                       reaper_24fdf990fc0d0ce6e34d030f619611233f7b7e714e623e1b6c635f7a85fdee4a
fc398aaabe82  docker.io/testcontainers/ryuk:0.8.1                    /bin/ryuk   27 seconds ago      Up 27 seconds      0.0.0.0:34295->8080/tcp, 8080/tcp                                       reaper_f9596c3bfefde5404c227e99286798894109b8d3b1de2fe207580a1baf340ac6
8ac0c88b5298  docker.io/testcontainers/ryuk:0.8.1                    /bin/ryuk   18 seconds ago      Up 18 seconds      0.0.0.0:42809->8080/tcp, 8080/tcp                                       reaper_8a5edab68adc986d01ff49f0774b013c3933ee8854bda319df02d26dfa233ded
64edfcfa3ec0  docker.io/testcontainers/ryuk:0.8.1                    /bin/ryuk   8 seconds ago       Up 9 seconds       0.0.0.0:35387->8080/tcp, 8080/tcp                                       reaper_3d76e1e0b630828fad795b4fcc603edaf11179da4d56148248f89862e92139d1

I want to see one reaper for the reusable container. As a side effect, having one reaper creates a “rolling window” behavior, where the reaper resets its timeout upon a new connection to the container, which is precisely what I would like to see: keep the container up and running between test runs and terminate it after the defined period of inactivity.

Am I making sense?

[kiview]

Oh yes, that makes absolutely sense and I believe this is more of a bug and something that Testcontainers should already handle correctly, rather than having a user to specify a session id manually.

[stevenh]

Thanks for the confirmation @jcmfernandes.

To facilitate this are you intending to set a long ReconnectionTimeout for all containers? I ask as if so I think thats going to prevent clean up of all other containers too, which I'm not sure is your intention?

[jcmfernandes]

@stevenh yes, because I want to keep the testcontainer running for the entirety of my work session.

I usually start a watcher that runs tests automatically as I save changes. I want the testcontainer to boot on the first test run and to stay around for, say, one hour, waiting for new connections. Furthermore, I then want new connections to reset that timeout. Example.

1. Run a test that starts the testcontainer at 9:05 AM with a reconnection timeout of 1 hour. Ryuk must wait for new connections until 10:05 AM, and GC the testcontainer if that doesn't happen.
2. Run another test at 9:35 AM --> I now want ryuk to wait until 10:35 AM for new connections.

This is precisely the behavior I get by manually setting the session ID and RYUK_RECONNECTION_TIMEOUT to 1 hour. Now, I'm happy to discuss ways to make the session ID stable and auto-generated.

[stevenh]

Thanks again for the clarification, the challenge I see with that is not only does it impact the long lived container but all containers for example:

You run a test which starts the long lived DB container as well a short lived test container. The desired behaviour is the DB container stays running between tests, but the test container itself exits after the test is run.

However in the case where the test fails and the short lived contain didn't exit as expected, with a standard ryuk setup this wouldn't be an issue as the test container would be quickly cleaned up, but with RYUK_RECONNECTION_TIMEOUT set to one hour no clean up will happen until that hour expires.

Does this make sense?

To handle this situation properly I think we'd need more fine grained control of when specific containers are cleaned up.

[jcmfernandes]

Thanks for the prompt reply, @stevenh.

That's a fair concern — it seems that testcontainers is missing some kind of "group" concept to which certain GC options apply. Currently, that's a "session", and this PR won't change it. That is, I don't see how this PR makes things worse regarding your concern, and it solves an actual reported issue.

[mdelapenya]

Hi @jcmfernandes, thanks for opening this PR, and following-up after @kiview's comments. I'm returning today after summer break, working on the open PRs/issues in the repo.

I'm not against the changes in this PR, although it introduces some breaking changes (BCs) after removing public API functions. See my comments for that. We could avoid it offering a deprecation path when/if possible, although we sometimes introduce BCs if needed.

I'd rename the PR to feat: allow overriding the sessionID and would focus on that, only. The added value if we do this is we would also enable Bazel folks to contribute their own env var for the session ID at build time. Nevertheless, we must check how the reaper behaves in that scenario. As discussed here, it's by design that the reaper is spawned just once per test session (a shell), but it's true that the design could be inconsistent with reusable containers used in multiple shells (different session IDs). Sharing state, even in tests, is a complex thing to maintain, so we probably need a more robust design for both features: reusable containers and the reaper, and it could need dedicated work on that direction.

@kiview @stevenh wdyt?

[jcmfernandes]

@mdelapenya thanks for your input. I modified this PR, making it focus solely on allowing devs to set the session ID, and I opened a separate PR #3269 where I delete TestcontainersConfig.

[stevenh]

I'm concerned calling config.Read in init could have some unintended side effects which are impossible to address, something we'll need to confirm.

[stevenh]

@mdelapenya could calling config.Read() in init cause undesired behaviour due to how early it called?

I'm thinking this would prevent things like changing the environment variables in a test from having the desired effect as an example.

[jcmfernandes]

Thanks for the feedback, @stevenh. I understand your concern: reading the config in an init() function felt wrong.

I change the code so that config.Read falls back to the session in core/bootstrap (I moved bootstrap.go to a new package to avoid import cycle between internal/config and internal/core). Please let me know what you think.

[coderabbitai]

Summary by CodeRabbit

• New Features

  • Session identifiers can now be configured via the TESTCONTAINERS_SESSION_ID environment variable, enabling improved session management and reaper coordination across container operations.

• Tests

  • Added test coverage for session ID configuration handling and environment variable precedence.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Walkthrough

Session ID retrieval has been refactored from the core package to a centralized config system. A new SessionID field was added to the Config struct, initialized via environment variables or bootstrap. All direct calls to core.SessionID() have been replaced with config.Read().SessionID across multiple files. Bootstrap package has been reorganized.

Changes

Cohort / File(s)	Summary
Config structure and initialization internal/config/config.go, internal/config/config_test.go	Added public SessionID field to Config struct with runtime initialization from TESTCONTAINERS_SESSION_ID environment variable or bootstrap. Extended tests to cover session ID sourcing from properties and environment variables.
Session ID retrieval migration container.go, docker_client.go, generic.go, network.go, testcontainers.go	Replaced core.SessionID() calls with config.Read().SessionID across multiple request and utility functions to centralize session tracking.
Docker provider session handling docker.go, reaper_test.go	Updated reaper initialization and test lookup to source session ID from config instead of core package.
HTTP client header sourcing internal/core/client.go	Replaced direct function calls (ProjectPath(), SessionID()) with bootstrap.ProjectPath() and tcConfig.SessionID for HTTP header values.
Bootstrap package reorganization internal/core/bootstrap/bootstrap.go	Changed package declaration from core to bootstrap for proper module structure.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Focus areas:
  • Verify that all session ID retrieval points have been consistently migrated to the config system; check for any remaining core.SessionID() calls in untouched files
  • Validate the initialization logic in internal/config/config.go for handling TESTCONTAINERS_SESSION_ID environment variable and bootstrap fallback
  • Confirm that the package rename in internal/core/bootstrap/bootstrap.go doesn't break existing imports or cause circular dependencies
  • Review the test coverage in internal/config/config_test.go to ensure all session ID sourcing scenarios are tested (environment variable precedence, properties, bootstrap defaults)
  • Check that docker_client.go's config initialization doesn't introduce unintended side effects or timing issues

Suggested reviewers

• stevenh

Poem

🐰 A session now lives in config's care,
No longer scattered core here and there!
Bootstrap whispers IDs so clean,
One reaper reigns where chaos has been,
This refactor hops toward cleaner machines! 🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: allow overriding the session ID' directly aligns with the main change, which makes the session ID configurable to allow long-running sessions.
Description check	✅ Passed	The description clearly explains the motivation and use case: enabling container reuse across test runs without spawning new reapers, addressing the need for long-running sessions.
Linked Issues check	✅ Passed	The PR successfully implements the core requirement from #2804: making the session ID configurable to enable container reuse with automatic cleanup. The changes add a SessionID field to Config, allow setting it via TESTCONTAINERS_SESSION_ID environment variable, and integrate it throughout the codebase to use the configured session ID instead of auto-generating one each run.
Out of Scope Changes check	✅ Passed	All changes are focused on making the session ID configurable and integrating it throughout the codebase. The package rename in bootstrap.go and bootstrap import additions support the new config-based session ID retrieval, staying within scope.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

testcontainers.go (1)

32-55: Update SessionID doc comment to match config‑based implementation

SessionID() now delegates to config.Read().SessionID, so the detailed description of how the ID is derived (parent PID + creation time, hashing, etc.) is no longer local to this function and may be overridden via config/env. Consider rewording the comment to describe it as “the current configured session ID” and, if needed, point to the bootstrap/config docs for the generation details.

docker.go (1)

924-932: Reaper now uses provider‑level SessionID; consider container ID if you ever support per‑container sessions

Using c.provider.config.SessionID when calling spawner.reaper aligns reaper lifetime with the configured, process‑wide session ID and matches the new config‑centric model. If, in the future, you want to honor per‑container LabelSessionID overrides consistently, this call would likely need to switch to c.sessionID instead; for the current design, though, the change is coherent.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 00f2020 and 01dc605.

📒 Files selected for processing (11)

• container.go (2 hunks)
• docker.go (1 hunks)
• docker_client.go (3 hunks)
• generic.go (2 hunks)
• internal/config/config.go (3 hunks)
• internal/config/config_test.go (36 hunks)
• internal/core/bootstrap/bootstrap.go (1 hunks)
• internal/core/client.go (2 hunks)
• network.go (2 hunks)
• reaper_test.go (1 hunks)
• testcontainers.go (2 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-09-29T15:08:18.694Z

Learnt from: mdelapenya
Repo: testcontainers/testcontainers-go PR: 3320
File: modules/artemis/artemis.go:98-103
Timestamp: 2025-09-29T15:08:18.694Z
Learning: In testcontainers-go, nat.Port is a type alias for string, so untyped string constants can be passed directly to functions expecting nat.Port (like wait.ForListeningPort) without explicit type conversion - the Go compiler handles the implicit conversion automatically.

Applied to files:

• network.go

🧬 Code graph analysis (10)

container.go (3)

internal/config/config.go (1)

• Read (103-109)

internal/core/bootstrap/bootstrap.go (1)

• SessionID (104-106)

testcontainers.go (1)

• SessionID (53-55)

internal/core/client.go (2)

internal/core/bootstrap/bootstrap.go (2)

• ProjectPath (100-102)
• SessionID (104-106)

testcontainers.go (1)

• SessionID (53-55)

internal/config/config.go (2)

internal/core/bootstrap/bootstrap.go (1)

• SessionID (104-106)

testcontainers.go (1)

• SessionID (53-55)

reaper_test.go (3)

internal/config/config.go (1)

• Read (103-109)

internal/core/bootstrap/bootstrap.go (1)

• SessionID (104-106)

testcontainers.go (1)

• SessionID (53-55)

network.go (3)

internal/config/config.go (1)

• Read (103-109)

internal/core/bootstrap/bootstrap.go (1)

• SessionID (104-106)

testcontainers.go (1)

• SessionID (53-55)

internal/config/config_test.go (2)

internal/core/bootstrap/bootstrap.go (1)

• SessionID (104-106)

internal/config/config.go (1)

• Config (34-97)

docker.go (3)

internal/core/docker_host.go (1)

• DockerHostContextKey (19-19)

internal/core/bootstrap/bootstrap.go (1)

• SessionID (104-106)

testcontainers.go (1)

• SessionID (53-55)

generic.go (4)

internal/core/labels.go (1)

• DefaultLabels (38-51)

internal/config/config.go (1)

• Read (103-109)

internal/core/bootstrap/bootstrap.go (1)

• SessionID (104-106)

testcontainers.go (1)

• SessionID (53-55)

docker_client.go (2)

internal/config/config.go (2)

• Config (34-97)
• Read (103-109)

internal/core/bootstrap/bootstrap.go (2)

• SessionID (104-106)
• ProcessID (96-98)

testcontainers.go (2)

internal/config/config.go (1)

• Read (103-109)

internal/core/bootstrap/bootstrap.go (1)

• SessionID (104-106)

🔇 Additional comments (9)

internal/core/bootstrap/bootstrap.go (1)

1-105: Package rename to bootstrap looks safe

Exports and init semantics are unchanged; renaming the package to bootstrap aligns with the new import sites and keeps behavior intact.

internal/core/client.go (1)

11-38: HTTP headers now correctly use config‑driven session ID

Using bootstrap.ProjectPath() and tcConfig.SessionID wires the Docker client headers into the same bootstrap/config session machinery used elsewhere; this is consistent and non‑breaking.

reaper_test.go (1)

115-124: Session ID lookup in test aligned with config

Fetching the session via config.Read().SessionID keeps this test in sync with how the provider/reaper obtain the session ID after the refactor; the lookup logic remains correct.

container.go (1)

25-28: Container session ID now correctly derives from config

ContainerRequest.sessionID() still respects an explicit LabelSessionID but now falls back to config.Read().SessionID, which is exactly what you want for a configurable, process‑wide session ID.

Also applies to: 174-181

network.go (1)

55-61: Network session ID consistent with config‑driven model

Aligning NetworkRequest.sessionID() with config.Read().SessionID (while still honoring a LabelSessionID override) keeps networks and containers on the same configurable session semantics.

generic.go (1)

108-114: Generic labels now reflect configured session ID

Passing config.Read().SessionID into core.DefaultLabels ensures all auto‑applied labels (including the session label) follow the same configurable session ID used elsewhere.

docker_client.go (1)

15-18: SessionID wiring via config.Config in DockerClient looks consistent

The new config field, use of config.Read() in NewDockerClientWithOpts, and logging of c.config.SessionID in Info() are all consistent with the new config‑driven session semantics. Using bootstrap.ProcessID() here also aligns with the bootstrap accessor pattern. No functional issues spotted in this hunk.

Also applies to: 26-27, 81-91, 121-130

internal/config/config.go (1)

13-14: SessionID config field and env/props precedence are correctly implemented

The new SessionID field, its properties tag (session.id) and the precedence logic in applyEnvironmentConfiguration (env → properties → bootstrap.SessionID() fallback) are coherent and match the documented TESTCONTAINERS_SESSION_ID behavior. This gives a stable, overridable session ID without altering existing config semantics.

Also applies to: 57-63, 119-138

internal/config/config_test.go (1)

12-13: Tests thoroughly cover new SessionID behavior across env, properties, and defaults

The additions to resetTestEnv, the updated expectations using bootstrap.SessionID(), and the new table entries for session.id and TESTCONTAINERS_SESSION_ID correctly encode the intended precedence and defaulting rules. This should give good regression coverage for the new SessionID configuration path.

Also applies to: 24-32, 47-59, 71-78, 85-102, 112-115, 126-132, 140-157, 163-167, 179-181, 220-224, 232-236, 243-247, 263-268, 275-279, 286-291, 298-301, 311-314, 325-328, 335-339, 348-352, 361-365, 374-378, 387-391, 416-420, 429-433, 458-462, 471-475, 502-505, 528-532, 541-545, 554-558, 561-582