Skip to content

Latest commit

 

History

History
110 lines (82 loc) · 7.84 KB

AGENTS.md

File metadata and controls

110 lines (82 loc) · 7.84 KB

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 ./gradlew is 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 in src/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's build.gradle before using newer APIs in tests.
  • Binary compatibility is enforced. check runs japicmp against the last released version (testcontainers.version in gradle.properties) for public and protected API (not wired into check on Windows; run ./gradlew :<project>:japicmp there). Don't remove or change signatures. Add an overload, deprecate the old one with @Deprecated and a Javadoc pointer to the replacement. japicmp disables itself when the baseline artifact can't be resolved (new modules, offline builds), so a green check doesn't always mean the comparison ran; say so when reporting results.
  • Checkstyle (config/checkstyle/checkstyle.xml): AssertJ only (no JUnit Assert/Assertions), no star imports, static imports only from the allowlist (AssertJ, Awaitility, Mockito, ...), braces on all if/else/for/while, no @author tags.
  • 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 core shading/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 package org.testcontainers.<module>. Classes in the legacy org.testcontainers.containers package are deprecated shims; don't add new ones there.
  • Provide constructors taking String and DockerImageName. Call dockerImageName.assertCompatibleWith(DEFAULT_IMAGE_NAME) so custom/compatible images work via asCompatibleSubstituteFor.
  • Never default to a latest or 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 assume localhost or fixed ports.
  • withXxx(...) setters return this (SELF). Validate arguments early (null/empty) with a clear exception.
  • Public API uses JDK types only. Don't expose types from compileOnly dependencies.
  • Dependencies: as few as possible. Client libraries/drivers that users likely already have are compileOnly; test-only clients go in testImplementation.
  • Add Javadoc on public classes and methods; check builds 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 with inside_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 under docs/modules/databases/), registered in the nav of mkdocs.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.md for 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, plus Fixes #<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-module playbook.
  • 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.