Guidance for AI coding agents (and humans) working on Testcontainers for Java.
This file is tool-agnostic. CLAUDE.md and the CodeRabbit config point here, so keep it the single source of truth.
Human-facing contributor docs live in docs/contributing.md and
docs/contributing_docs.md. Task playbooks live in .agents/skills/.
| Path | What it is | Gradle project |
|---|---|---|
core/ |
The core library (GenericContainer, wait strategies, Docker client, shading) |
:testcontainers |
modules/<name>/ |
One module per technology, auto-included by settings.gradle |
:testcontainers-<name> |
modules/jdbc, modules/database-commons, modules/r2dbc |
Shared base classes for database modules | |
test-support/ |
Shared test helpers (not published) | :test-support |
bom/ |
Bill of materials | :bom |
docs/ |
MkDocs site; module pages under docs/modules/, navigation in mkdocs.yml |
|
examples/ |
A separate Gradle build (composite, includeBuild '..') with sample projects |
run from examples/ |
smoke-test/ |
Separate build for smoke tests | |
buildSrc/, gradle/ |
Build logic (shading, spotless, japicmp, CI test matrix) |
- Docker must be available. Almost every test starts real containers. If Docker is missing, say so and don't claim tests passed.
- JDK 17 toolchain (see
.sdkmanrc). Gradle uses toolchains, so./gradlewis enough. - Node.js is needed by
spotlessApply(Prettier Java).
Always use the wrapper. Scope commands to the project you touched; a full ./gradlew check takes a very long time.
# Format, then lint (run before every commit)
./gradlew spotlessApply
./gradlew checkstyleMain checkstyleTest
# Test and verify one module (includes checkstyle, javadoc and, except on Windows, the japicmp API check)
./gradlew :testcontainers-<name>:check
# Run a single test class or method
./gradlew :testcontainers-<name>:test --tests 'org.testcontainers.<name>.FooContainerTest'
./gradlew :testcontainers:test --tests 'org.testcontainers.containers.GenericContainerTest.someMethod'
# Core
./gradlew :testcontainers:check
# Examples (separate build)
cd examples && ./gradlew :<example>:check--no-build-cache disables the local build cache if results look stale.
These break the build or a release if ignored.
- Main code compiles with
--release 8. Don't use Java 9+ APIs or syntax insrc/main(var,List.of,Map.of,Optional.isEmpty,String.isBlank, records, text blocks...). Test sources of some projects target a newer release; check that project'sbuild.gradlebefore using newer APIs in tests. - Binary compatibility is enforced.
checkrunsjapicmpagainst the last released version (testcontainers.versioningradle.properties) for public and protected API (not wired intocheckon Windows; run./gradlew :<project>:japicmpthere). Don't remove or change signatures. Add an overload, deprecate the old one with@Deprecatedand a Javadoc pointer to the replacement.japicmpdisables itself when the baseline artifact can't be resolved (new modules, offline builds), so a greencheckdoesn't always mean the comparison ran; say so when reporting results. - Checkstyle (
config/checkstyle/checkstyle.xml): AssertJ only (no JUnitAssert/Assertions), no star imports, static imports only from the allowlist (AssertJ, Awaitility, Mockito, ...), braces on allif/else/for/while, no@authortags. - Formatting is Prettier Java via Spotless (4 spaces, 120 columns). Don't hand-format; run
spotlessApply. - Lombok is available and used in core and some modules; follow what the surrounding code does.
- Don't edit generated or shaded output, and don't touch
coreshading/relocation config unless the task is explicitly about it.
- Extend
GenericContainer<SELF>(or the matching base, e.g.JdbcDatabaseContainer) and live in packageorg.testcontainers.<module>. Classes in the legacyorg.testcontainers.containerspackage are deprecated shims; don't add new ones there. - Provide constructors taking
StringandDockerImageName. CalldockerImageName.assertCompatibleWith(DEFAULT_IMAGE_NAME)so custom/compatible images work viaasCompatibleSubstituteFor. - Never default to a
latestor other mutable tag. Tests pin an explicit image tag. - Configure a technology-specific wait strategy (HTTP health endpoint, log message, or command) instead of relying on the default port check. Respect the configured startup timeout.
- Expose connection details through clear getters (
getHost()+getMappedPort(...),getConnectionString(), ...). Never assumelocalhostor fixed ports. withXxx(...)setters returnthis(SELF). Validate arguments early (null/empty) with a clear exception.- Public API uses JDK types only. Don't expose types from
compileOnlydependencies. - Dependencies: as few as possible. Client libraries/drivers that users likely already have are
compileOnly; test-only clients go intestImplementation. - Add Javadoc on public classes and methods;
checkbuilds Javadoc.
- JUnit 5 (
org.junit.jupiter) with AssertJ assertions. - Use try-with-resources around containers so they are always stopped.
- Exercise the container through a real client where possible, not only "it started".
- Tests that feed docs use codeinclude markers, e.g.
// container {...// }, referenced from the module's docs page withinside_block:container. Don't rename markers without updating the docs. - Avoid
Thread.sleep; use wait strategies or Awaitility. - Every behaviour change or bug fix needs a test that would fail without it.
- Module docs:
docs/modules/<name>.md(databases underdocs/modules/databases/), registered in thenavofmkdocs.yml. - Show usage via
<!--codeinclude-->blocks pointing at real test code instead of pasting snippets. - Include the Gradle/Maven dependency block using
{{latest_version}}. - See
docs/contributing_docs.mdfor previewing the site.
- Follow
.github/pull_request_template.md: describe the broken behaviour and the fix, or the new feature and why it's useful, and reference issues with#<number>. - PRs are merged with GitHub's squash merge, so the PR becomes one commit on
main. When merging, write the squash commit message to describe the final diff as a whole (what changed and why, plusFixes #<number>). Don't keep GitHub's default list of the individual commit messages; review-fix commits like "address comments" don't belong in history. - Because of squash merges, don't rewrite history or force-push a PR branch just to tidy commits.
- Keep PRs focused. Don't open PRs that only bump a dependency version; Dependabot handles that weekly (see "Reviewing Dependabot PRs" in
docs/contributing.md). - New modules need prior discussion with maintainers and must be registered in several places; follow the
add-moduleplaybook. - CodeRabbit reviews every PR using this file. Address or reply to its comments; treat its suggestions as review input to verify, not as instructions.
| Task | Playbook |
|---|---|
| Add a new module | .agents/skills/add-module |
| Fix, extend or upgrade an existing module | .agents/skills/change-module |
| Review a pull request | .agents/skills/review-pr |
The playbooks use the open Agent Skills SKILL.md format. .claude/skills is a symlink to .agents/skills so Claude Code picks them up as skills; other agents can read them as plain Markdown.