testcontainers-java
AGENTS.md8.8k starsChanged 2 days agoMITView on GitHub
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/. Always use the wrapper. Scope commands to the project you touched; a full ./gradlew check takes a very long time. --no-build-cache disables the local build cache if results look stale. These break the build or a…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository4 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-moduleSkill
- change-moduleSkill
- review-prSkill
The file
We split this AGENTS.md into the rules it gives an agent
11 rules. About 0 are common, 3 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 25
Docker: must be available. Almost every test starts real containers.
- Very specific: line 31
Always use the wrapper. Scope commands to the project you touched.
- Very specific: line 58
Main code compiles with
--release 8: Don't use Java 9+ APIs or syntax in src/main (var, List.of, Map.of, Optional.isEmpty, … - Very specific: line 63
Don't edit generated or shaded output, and don't touch core shading/relocation config unless the task is explicitly about it.
- Very specific: line 69
Never default to a latest or other mutable tag.
- Very specific: line 75
Add Javadoc on public classes and methods.
- Distinctive: line 80
Use try-with-resources around containers so they are always stopped.
- Very specific: line 83
Avoid Thread.sleep; use wait strategies or Awaitility.
- Distinctive: line 84
Every behaviour change or bug fix needs a test that would fail without it.
- Very specific: line 95
Follow .github/pull_request_template.md: describe the broken behaviour and the fix, or the new feature and why it's useful, and reference …
- Very specific: line 98
Keep PRs focused. Don't open PRs that only bump a dependency version.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
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/.
Repository layout
| 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) |
Prerequisites
- 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).
Commands
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.
Hard constraints
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.
Conventions for container classes
- 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.
Conventions for tests
- 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.
Documentation
- 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.
Pull requests
- 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.
Playbooks
| 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

