feat: add the ability to configure the provider type in the properties file or as an env var

[mkeeler]

What does this PR do?

This PR allows for setting the Provider type (Podman or Docker) in either the properties file (e.g. provider=podman) or as an environment variable (e.g. TESTCONTAINERS_PROVIDER=docker)

Why is it important?

Using WithProvider in tests results in tests that are not portable to other developer environments when not all contributors to a codebase all use the same container engine. This PR allows for user/environment settings to control the provider type ensuring that tests remain portable.

Related issues

• Relates #2264
• Relates #3241

How to test this PR

• Use any test that runs a test container without specifying the WithProvider option.
• Run the test on a system with Podman and not Docker running. It should fail to run the reaper container (I am using Podman Desktop on MacOS).
• Set the TESTCONTAINERS_PROVIDER=podman env var.
• Rerun the tests and watch it now pass.
• Remove the env var and this time add provider=podman to the properties file.
• Rerun the tests and they should still pass.

[netlify[bot]]

✅ Deploy Preview for testcontainers-go ready!

Name	Link
🔨 Latest commit	1c2bf2a9626566fb8a9f185dbe5c1c2244906431
🔍 Latest deploy log	https://app.netlify.com/projects/testcontainers-go/deploys/691f49360a1f9d0008419a90
😎 Deploy Preview	https://deploy-preview-3494--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.

[coderabbitai[bot]]

Summary by CodeRabbit

• New Features

  • Container provider (Docker or Podman) can now be configured globally via the TESTCONTAINERS_PROVIDER environment variable.
  • Provider setting can also be configured in .testcontainers.properties file.

• Documentation

  • Updated Podman usage documentation with new global provider configuration options.

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

Walkthrough

Adds a new Config.Provider field (bound to TESTCONTAINERS_PROVIDER and properties), updates config reading to populate it, and introduces ProviderType.UnderlyingProviderType() to centralize provider resolution with explicit → config → auto-detect → default precedence.

Changes

Cohort / File(s)	Summary
Configuration Support internal/config/config.go, internal/config/config_test.go	Added public Provider field to Config with property/env binding (provider / TESTCONTAINERS_PROVIDER); tests added/updated to validate setting via properties and environment and precedence where env overrides properties
Provider Detection Logic provider.go, provider_test.go	Added UnderlyingProviderType() method on ProviderType that resolves effective provider using precedence (explicit → config.Provider → auto-detect Podman from host → Docker fallback); refactored GetProvider to use this method; added table-driven tests for resolution across env/properties/explicit inputs
Documentation docs/system_requirements/using_podman.md	Documented that TESTCONTAINERS_PROVIDER=podman (or provider=podman in properties) can force Podman provider for tests

Sequence Diagram

sequenceDiagram
    participant App as Application
    participant PT as ProviderType.UnderlyingProviderType()
    participant CFG as Config (properties / file)
    participant ENV as Environment (TESTCONTAINERS_PROVIDER)
    participant AUTO as Auto-detection (host/docker info)

    App->>PT: Request effective provider

    rect rgb(220,235,255)
    PT->>PT: Check explicit ProviderType argument
    alt explicit provided
        PT-->>App: Return explicit ProviderType
    end
    end

    rect rgb(235,255,220)
    PT->>CFG: Check Config.Provider
    PT->>ENV: Check TESTCONTAINERS_PROVIDER
    alt env set
        PT-->>App: Return provider from ENV
    else cfg set
        PT-->>App: Return provider from CFG
    end
    end

    rect rgb(255,245,220)
    PT->>AUTO: Perform auto-detect (e.g., inspect Docker host for Podman)
    alt auto-detect Podman
        PT-->>App: Return Podman
    else
        PT-->>App: Return Docker (default)
    end
    end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Focus review on:
  • Config binding for Provider (env/property mapping and default handling)
  • Correctness of precedence in UnderlyingProviderType() and integration with GetProvider
  • Test setup/teardown in new table-driven tests (env and properties file manipulation)

Poem

🐰 A little provider hops to say hello,
Env leads the dance, properties follow slow,
Detection listens to the host's soft drum,
If unsure, Docker waits—steady and hum,
I nibble code, and testers gently glow.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

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

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main feature: adding provider type configuration via properties file or environment variable.
Description check	✅ Passed	The description clearly explains what the PR does, why it matters, and provides concrete testing instructions related to the changeset.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

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

---

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.}

[mdelapenya]

Hi @mkeeler thanks for opening this PR.

We are working on moving the core of this library to use https://github.com/docker/go-sdk so that the selection of the container runtime (the provider) will be managed by the Docker config file and its current docker context. So selecting Podman, Orbstack or Colima would be just a matter of changing the current context. We have examples here: https://github.com/mdelapenya/go-sdk-examples

In any case, for an initial shallow review, I think this PR is harmless, although I need to start a more in-depth one, just wanted to give you feedback the soonest.

[mkeeler]

@mdelapenya Thanks for the update. Using docker contexts would definitely be better. If moving to the docker/go-sdk is something that would land relatively soon then I see no reason to review and merge this PR. If it will take a while longer, then this does solve the test portability issue for now.