Expose explicitly declared image compatibility

[dlwhdgus0810]

Closes #7305.

Container modules cannot currently distinguish an explicit asCompatibleSubstituteFor(...) declaration from compatibility inferred from an image name. For example, a module that enforces a minimum version cannot tell whether an unversioned custom image was explicitly accepted by its caller.

Add a nullable DockerImageName.getCompatibleSubstituteFor() accessor for the existing declaration. Undeclared images return null; existing compatibility validation and immutable copy behavior remain unchanged.

Validation: all 61 DockerImageName tests passed, including explicit and absent declarations and preservation across registry/repository/tag changes. Core Checkstyle, Spotless, Javadoc and japicmp API compatibility checks passed. The complete Docker-backed core and module suites were not run for this accessor-only change.

Summary by CodeRabbit

• New Features

  • Added access to an explicitly configured compatible Docker image for improved compatibility inspection.
  • Returns no compatible image when none has been configured.

• Tests

  • Added coverage for compatibility behavior with and without explicit substitutions.
  • Verified compatibility is preserved when registry, repository, or tag details change.

[coderabbitai]

Understand this PR’s impact

Explore downstream dependencies and potential security impact with Blast Radius.

View blast radius →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: 537950c0-8f1b-4243-9e0c-e24a633d6553

📥 Commits

Reviewing files that changed from the base of the PR and between 8e54951 and e234de2.

📒 Files selected for processing (2)

• core/src/main/java/org/testcontainers/utility/DockerImageName.java
• core/src/test/java/org/testcontainers/utility/DockerImageNameCompatibilityTest.java

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

Changes

Docker image compatibility

Layer / File(s)	Summary
Compatibility accessor and validation core/src/main/java/org/testcontainers/utility/DockerImageName.java, core/src/test/java/org/testcontainers/utility/DockerImageNameCompatibilityTest.java	DockerImageName exposes the explicitly configured compatible substitute and returns null when none is configured. Tests cover string-based declaration and preservation through registry, repository, and tag changes.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Feature

Suggested reviewers: eddumelendez

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description explains the existing problem, the new accessor, expected behavior, issue reference, validation performed, and tests not run. It provides the required change context and is sufficientl…
Title check	✅ Passed	The title clearly and concisely describes the main change: exposing explicitly declared image compatibility.
Linked Issues check	✅ Passed	The PR meets the coding requirements in [#7305]. DockerImageName.getCompatibleSubstituteFor() is public and nullable. It returns the explicitly stored substitute and returns null for images create…
Out of Scope Changes check	✅ Passed	The changes stay within [#7305]. They add the requested Core API accessor and focused compatibility tests. The changes do not add unrelated module behavior or alter existing validation and compatibili…

• Fix all pre-merge checks with AI

---

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