- 1. Why Testbench Exists
- 2. Module Layout
- 3. Conceptual Model
- 4. Installation
- 5. Quick Start
- 6. The Docker Fixture Layer
- 7. The Condition Layer
- 8. The Groundwater Base Class
- 9. The Logger
- 10. The Foundation Spring Context
- 11. The Style Tools
- 12. Operational Notes and Troubleshooting
- 13. Limitations and Known Issues
- 14. Defaults Reference
- 15. Package File Map
- 16. See Also
- 17. License
Testbench is the collection of small, focused frameworks the SmallMind project uses to test itself. It is not a general-purpose product offered to consumers of the library; it is the in-house plumbing that lets the rest of the repository write integration tests against real backing services — Kafka, MySQL, MongoDB, RabbitMQ, Memcached, MinIO, a registry — by standing those services up in Docker containers, waiting for them to be genuinely ready, and tearing them down again. Alongside the Docker machinery it carries a precondition-polling layer, a one-call console logger, a Spring bootstrap context, and a pair of command-line tools that keep every pom.xml in the repository tidy.
|
Important
|
This is internal tooling. The audience for this document is a SmallMind contributor writing or maintaining tests inside this repository, not an external adopter assembling an application. Unlike the runtime modules ( |
Most of SmallMind is glue code that sits between an application and a real piece of infrastructure: a JPA layer over a SQL database, a wire transport over Kafka or RabbitMQ, a cache client over Memcached, a document mapper over MongoDB. The only honest way to test that glue is against the real thing. Mock-based unit tests confirm that the code calls the methods the author expected; they do not confirm that MySQL accepts the generated SQL, that a Kafka consumer is actually positioned before the first publish, or that a Memcached cas round-trips the way the protocol says it should.
Running integration tests against real services creates four recurring chores, and each testbench module exists to remove one of them:
-
Standing the service up and knowing when it is ready. A container that is "running" is not the same as a container whose port is accepting connections. The
dockermodule pulls the image, applies the right ports, mounts, and environment, starts the container, and then blocks until every service port answers a TCP connect — so the test body never races the broker’s startup. -
Refusing to start against a dirty environment. A container left behind by a crashed previous run will collide on name or port and produce confusing failures. The
conditionmodule supplies pollable preconditions; thegroundwaterbase class uses them to fail fast when a stale container or mail-server port is still around. -
Boilerplate setup repeated in every integration test. The
groundwatermodule reduces the whole "bring containers up before the class, take them down after" cycle to a one-linesuper(…)call, and theloggermodule reduces "make Scribe print readable debug output" to one static call. -
Keeping the build files consistent. With dozens of modules, dependency blocks drift — declarations go unused, transitive dependencies get relied on without being declared, test-only dependencies leak into compile scope, and ordering becomes arbitrary. The
stylemodule’s two command-line tools rewrite everypom.xmlto fix exactly those problems.
The name reflects the intent: a bench of instruments a contributor reaches for when wiring up a test, each one doing a single mechanical job so the test itself can be about the behavior under test.
testbench is a Maven POM aggregator (smallmind-testbench, packaging pom) with six published JARs. They are independent: depend on the one whose job you need.
| Artifact | Module name | Module | Purpose |
|---|---|---|---|
|
|
|
A catalog of ready-to-run container fixtures ( |
|
|
|
A pollable-precondition abstraction ( |
|
|
|
|
|
|
|
|
|
|
|
A resources-only JAR carrying a Spring |
|
|
|
Two developer command-line tools, |
The dependency edges among them are: condition depends on docker; groundwater depends on both condition and docker (and TestNG); logger, foundation, and style stand alone. The common entry point for an integration test is groundwater, which transitively brings in everything except logger and foundation.
Tests on the classpath are the supported configuration for every testbench artifact; there, module descriptors are ignored. Every testbench artifact ships an explicit module descriptor. See Module Path And Classpath for the repository-wide rules.
-
org.smallmind.testbench.dockerexportsorg.smallmind.testbench.dockerand re-exportsorg.smallmind.nutsnbolts(requires transitive). It requiresorg.smallmind.scribe.penand the docker-java automatic modulescom.github.dockerjava.api,com.github.dockerjava.core,com.github.dockerjava.transport, andcom.github.dockerjava.transport.httpclient5.DockerClientUtility(DockerClient),DockerMount(MountType), andDockerVolume(AccessMode) expose docker-java API types, and automatic modules are never re-exported, so a module that uses them also requirescom.github.dockerjava.api. -
org.smallmind.testbench.conditionexportsorg.smallmind.testbench.conditionand re-exportsorg.smallmind.nutsnbolts(requires transitive). It requiresorg.smallmind.testbench.dockerand the automatic modulescom.github.dockerjava.apiandcom.rabbitmq.client.RabbitMQAvailableTestConditiontakes RabbitMQAddressarguments, and automatic modules are never re-exported, so a module that constructs it also requirescom.rabbitmq.client.amqp-clientbrings Netty, andnetty-codec-marshallingandnetty-codec-protobufdeclarerequireson modules that are not supplied (org.jboss.marshalling,com.google.protobuf). Nothing in a normal graph resolves those two Netty modules, so this only surfaces with--add-modules ALL-MODULE-PATHor a tool that resolves every module, such asjdeps. -
org.smallmind.testbench.groundwaterexportsorg.smallmind.testbench.groundwaterand re-exportsorg.smallmind.testbench.docker(requires transitive), whose types appear inAbstractGroundwaterTest’s constructor. It requires `org.smallmind.testbench.conditionand the TestNG automatic moduleorg.testng; a test class that extendsAbstractGroundwaterTestuses TestNG annotations and requiresorg.testngitself. -
org.smallmind.testbench.loggerrequiresorg.smallmind.scribe.penand opensorg.smallmind.testbench.loggerunconditionally soclasspath:org/smallmind/testbench/logger/logging.xmlstays loadable from other modules. -
org.smallmind.testbench.foundationexports nothing, because it has no classes. It opensorg.smallmind.testbench.foundationunconditionally soclasspath:org/smallmind/testbench/foundation/foundation.xmlandglobal.yamlstay loadable from other modules. It requiresorg.smallmind.nutsnbolts,org.bouncycastle.provider, andorg.yaml.snakeyaml, the three modulesfoundation.xmlandglobal.yamlneed, so requiringorg.smallmind.testbench.foundationbrings them into the module graph. Spring itself is not named; the test that loads the context supplies it. -
org.smallmind.testbench.styleexportsorg.smallmind.testbench.style, re-exportsjava.xml(requires transitive), and requiresorg.smallmind.nutsnboltsandjdk.jdi. It opens its package unconditionally becauseDependencyOrganizerandDependencyReducerloadpretty-print.xsltthrough the thread context class loader.
A handful of terms recur throughout the harness; pinning them down makes the rest of the document precise.
- Fixture
-
A backing service defined as one constant of the
DockerApplicationenum — its image, container name, service ports, environment, and any mounts. A fixture is a recipe, not a running thing. - Owning test
-
The string passed as the
testargument toDockerApplications.start. It is attached to the container both as atestlabel and as aTest=<value>environment variable, so a running container can be traced back to the test that launched it.AbstractGroundwaterTestuses the concrete test class’s simple name for this. - Service port versus external port
-
A
DockerPortpairs a container-internal service port (fixed at construction) with an optional external host port. With no override, the same number is bound on the host. Readiness is always probed against the service port onlocalhost. - Readiness
-
A started container is not considered ready until it reports
runningand a TCP connect to every one of its service ports succeeds.DockerApplications.startdoes not return until that holds, so callers never poll for readiness themselves. - Condition
-
A pollable check (
TestCondition) that reports the current state of the world on each call and leaves the retry-and-timeout loop toTestConditions. A condition returnsnullwhen satisfied and aTestConditionFailure(carrying a human-readable description) when not.
Every testbench artifact belongs in a test-scoped dependency block. They share the project group and version; use the ${project.version} placeholder as the rest of the repository does.
The common case — a TestNG integration test that needs one or more containerized services — pulls in groundwater (which transitively provides condition and docker) and usually logger:
<dependency>
<groupId>org.smallmind</groupId>
<artifactId>testbench-groundwater</artifactId>
<version>${project.version}</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.smallmind</groupId>
<artifactId>testbench-logger</artifactId>
<version>${project.version}</version>
<scope>test</scope>
</dependency>Reach for the narrower artifacts directly when you do not need the whole stack:
-
testbench-dockeralone — when you drive container lifecycle yourself rather than through thegroundwaterbase class. -
testbench-conditionalone — when you only need to poll a precondition (it bringsdockerwith it becauseContainerAbsentTestConditionqueries the daemon). -
testbench-foundation— when a test needs the Spring bootstrap context; add it as atestresource dependency.
testbench-style is not a test dependency at all; it is run as a command-line tool against the repository checkout (see The Style Tools).
|
Important
|
A Scribe backend must be on the test classpath for log output to appear. |
|
Important
|
No testbench artifact depends on the aggregate |
The canonical path is to extend AbstractGroundwaterTest, pass the fixtures the test needs to the constructor, and let the base class manage the container lifecycle. The pattern below is taken from the Memcached integration suite.
@Test(groups = "integration") // (1)
public class CubbyIntegrationTest extends AbstractGroundwaterTest {
private CubbyMemcachedClient client;
public CubbyIntegrationTest () {
super(DockerApplication.MEMCACHED); // (2)
}
@BeforeClass
@Override
public void beforeClass ()
throws Exception {
TestLoggerConfiguration.setup(); // (3)
super.beforeClass(); // (4)
client = new CubbyMemcachedClient(
CubbyConfiguration.OPTIMAL,
new MemcachedHost("0", "localhost", 11211)); // (5)
client.start();
}
@AfterClass
@Override
public void afterClass ()
throws Exception {
client.stop(); // (6)
super.afterClass();
}
@Test
public void testNoop ()
throws Exception {
Response response = client.send(new NoopCommand().setKey("none"), null);
Assert.assertEquals(response.getCode(), ResponseCode.MN);
}
}-
The suite opts into the
integrationgroup, the convention this repository uses to separate container-backed tests from pure unit tests. -
The fixture this test depends on. The base class will start a Memcached container before the class and stop it after.
-
Installs the console logger first, so container pull/start progress and the code under test both log to stdout.
-
Calling
super.beforeClass()is what actually runs the clean-environment check and starts the containers. Because the subclass overrides the TestNG@BeforeClasshook, it must call super explicitly — the base method is not invoked for you. -
The container binds Memcached’s
11211on the host (no external-port override), so the client connects tolocalhost:11211. -
Tear down the client before calling
super.afterClass(), which stops and removes the container.
|
Note
|
|
testbench-docker is the heart of the harness. It has two public faces: the DockerApplication catalog of recipes and the DockerApplications lifecycle operations.
Each enum constant bundles a complete container recipe: image, default container name, service ports, an optional command override, environment variables, and optional bind mounts, volume binds, and a tmpfs mount.
| Constant | Image | Service Ports | Notes |
|---|---|---|---|
|
|
|
KRaft mode (no ZooKeeper). The external listener is on |
|
|
|
No environment or command; the image default. |
|
|
|
Command override |
|
|
|
Root user |
|
|
|
Root password |
|
|
|
Both the TLS and plaintext AMQP ports are exposed. |
|
|
|
OpenTelemetry trace export disabled ( |
Accessors on the enum return defensive copies. getPorts() builds a fresh DockerPort[] with no external override (host port equals service port); getEnvironment(test) returns the configured KEY=VALUE entries plus a trailing Test=<test> entry on every call, never mutating the stored array.
|
Note
|
The container |
DockerApplications exposes static start and stop operations.
// Start under the application's default container name.
String containerId = DockerApplications.start("MyIntegrationTest", DockerApplication.MYSQL);
// Start under an explicit name, overriding the host port for the single service port.
DockerPort port = new DockerPort(3306);
port.setExternalPort(13306);
String otherId = DockerApplications.start("MyIntegrationTest", "mysql-alt", DockerApplication.MYSQL, port);
// Tear down (kills, then removes the container and its volumes).
DockerApplications.stop(containerId);start performs the full sequence in one call:
-
Pull if absent. The image is inspected; on
NotFoundExceptionit is pulled and the download is logged throughLoggerManager. -
Apply the recipe. Port bindings are built from the supplied
DockerPortoverrides, or from the application’s default ports when none are passed. Bind mounts, volume binds, and a tmpfs mount are applied when the fixture declares them. A command override replaces the imageCMDwhen present. Atest=<test>label and theTest=<test>environment entry are attached. -
Start and wait for readiness. The container is started, then the method loops: once the container reports
running, it attempts a one-second TCP connect to every service port onlocalhost. It returns the container id only when all ports answer.
stop is written to be safe in teardown regardless of current state: it kills the container (polling until it is no longer running), then removes it with its volumes (polling until it is gone), and treats an already-stopped or already-removed container as success, logging rather than throwing.
|
Important
|
The readiness loop in |
Three small immutable descriptors model the filesystem options. DockerMount and DockerVolume resolve their host side from a classpath resource at construction time, via the thread context classloader, and raise MissingHostResourceException immediately when the resource cannot be found — so a misconfigured fixture fails when it is declared, not when the container is later started. DockerTmpFs describes an in-memory mount (path plus daemon mount options), used to give I/O-heavy services like MySQL a fast, ephemeral data directory.
DockerMount config = DockerMount.create(
MountType.BIND, // (1)
"fixtures/my-server.conf", // (2)
"/etc/my-server/server.conf", // (3)
true); // (4)
DockerVolume data = DockerVolume.create(
"fixtures/seed-data", // host resource on the classpath
"/var/lib/data", // container path
AccessMode.rw);
DockerTmpFs scratch = DockerTmpFs.create("/var/lib/mysql", "rw,noexec,nosuid,size=1024m");-
The Docker mount type, typically a bind mount.
-
The host side, resolved from the classpath; resolution failure throws here.
-
The absolute container path the resource is mounted at.
-
Whether the mount is read-only inside the container.
DockerClientUtility.createClient() builds the DockerClient over an Apache HTTP/5 transport. The daemon address comes from the DOCKER_HOST environment variable, falling back to tcp://localhost:2375 when it is unset. The returned client is AutoCloseable and owned by the caller — every operation in DockerApplications wraps it in a try-with-resources, and so should any direct use.
|
Important
|
The |
testbench-condition separates what to check from how long to wait. A TestCondition is a functional interface whose test() method reports the current state once — returning null when satisfied or a TestConditionFailure when not — and TestConditions owns the polling loop.
TestConditions offers two static drivers, both taking a timeout budget in seconds and a varargs of conditions. Both treat a null or empty array as nothing to do, and both sleep one second between polling rounds. The deadline is measured from the moment the call begins and is shared across every condition — the budget is not reset per condition.
| Driver | Semantics |
|---|---|
|
Waits for each condition in turn, advancing to the next only once the current one is satisfied. The first condition still unsatisfied when the shared deadline passes aborts the call with a |
|
Re-tests the whole set on each round, dropping conditions as they become satisfied, and returns as soon as none remain. A slow condition does not hold up evaluation of the others. On timeout, the exception reports every still-outstanding failure. |
TestConditionTimeoutException is a checked FormattedException whose message lists each outstanding failure (rendered via its toString()) and the timeout that was exceeded.
| Condition | Satisfied when |
|---|---|
|
No Docker container matching any of the given names is present on the daemon. Polled before starting fixtures to ensure a previous run left nothing behind. The failure names the container that is still around. |
|
Nothing is listening on a given |
|
A RabbitMQ broker at a given address accepts an authenticated AMQP connection. Used to wait for a freshly started broker to finish coming up; echoes an incrementing attempt counter to stdout while it waits. |
Note the two polarities. ContainerAbsentTestCondition and GreenmailAbsentTestCondition wait for something to go away (a clean-environment guard); RabbitMQAvailableTestCondition waits for something to come up (a readiness guard).
Implement TestCondition, probe the resource once, and return null or a MessageTestConditionFailure. The repository’s own DataSourceAvailableTestCondition (in the persistence module, not in testbench) is the model for an availability probe:
public class DataSourceAvailableTestCondition implements TestCondition {
private final DriverManagerDataSource dataSource;
public DataSourceAvailableTestCondition (String driverClassName, String jdbcUrl, String userName, String password)
throws SQLException {
dataSource = new DriverManagerDataSource(driverClassName, jdbcUrl, userName, password);
}
@Override
public TestConditionFailure test () {
try (Connection connection = dataSource.getConnection()) {
return null; // (1)
} catch (Exception exception) {
return new MessageTestConditionFailure("Could not start Mysql"); // (2)
}
}
}-
A successful probe satisfies the condition.
-
A failed probe is reported as an unsatisfied condition, not thrown —
TestConditionskeeps polling. Reserve a thrown exception for a probe that cannot be carried out at all.
Drive it with TestConditions.serial(30, new DataSourceAvailableTestCondition(…)).
AbstractGroundwaterTest is the one-line on-ramp to the whole stack. A subclass passes the fixtures it needs to the constructor; the base class then owns their lifecycle through TestNG hooks.
@BeforeClass beforeClass()-
When the fixture list is non-empty, first waits — via
TestConditions.parallelwith a thirty-second budget — for a clean environment: any leftover Kafka, MongoDB, MySQL, RabbitMQ, or Memcached containers from a prior run must be gone, and the GreenMail port8025must be free. Then it starts every configured application, recording each container id for teardown. Each container is started with the concrete test class’s simple name as its owning-test identifier (thetestlabel andTestenvironment variable) and under the application’s own default container name. @AfterClass afterClass()-
Stops and removes every container started in
beforeClass(). Anullor empty fixture list turns both hooks into no-ops.
The lifecycle is owned entirely by this class: the containers it starts are exactly the ones it stops. Because the hooks are ordinary TestNG @BeforeClass/@AfterClass methods, a subclass that overrides them must call super (see the Quick Start).
|
Note
|
The clean-environment guard’s container-name list is hard-coded to the five services above and GreenMail’s |
TestLoggerConfiguration.setup() is a single static call that points Scribe at the console for readable, debug-level output, so a contributor does not assemble a Scribe configuration by hand in every test.
TestLoggerConfiguration.setup();It registers a DefaultTemplate at Level.DEBUG with auto-filled logger context, routing output through a ConsoleAppender whose PatternFormatter renders timestamp, level, class, method, line, thread, and message — including any exception principal and stack trace — to stdout. Call it once, early in @BeforeClass. Calling it again registers an additional template rather than replacing the first, so avoid repeat calls.
For Spring-assembled tests, the module also ships an equivalent logging.xml (Spring profile default) that wires the same DefaultTemplate, PatternFormatter, and ConsoleAppender as beans.
testbench-foundation is a resources-only JAR (no Java types) providing a Spring bootstrap context for tests that need one. Importing classpath:…/foundation.xml wires:
-
PerApplicationContext— the per-application context many SmallMind runtime types resolve against (Claxon instrumentation, the ORM DAO registry, the wire context). Several of this repository’s components throw without one attached to the current thread, so the foundation context establishes it. Constructing the bean attaches the map to the refresh thread and leaves it there, so every test on that thread, and every thread it starts, carries it. -
SpringContextRefreshedAnnouncerwith application nameEpicenter. -
SecurityProviderInitializingBeanregistering the BouncyCastle provider. -
SystemPropertyInitializingBeanand aPropertyPlaceholderConfigurerthat resolves placeholders fromclasspath:org/smallmind/testbench/foundation/global.yamland, if present,file:${user.home}/.m2/local.yaml— letting a developer override test properties locally without touching the checked-in defaults.
The bundled global.yaml sets two defaults: log.level.default: DEBUG and wire.default_timeout_seconds: 15.
|
Note
|
Tests that do not boot the Spring context but still touch components requiring a per-application context can construct one directly on the test thread with |
The foundation context deliberately declares no PerApplicationScope bean. A ScopedValue binding exists only for the extent of a run / call, so a scope created during the refresh can never be the instance that was bound around it; a bean would look right and bind nothing. Components that resolve through the scope flavor (scope — ScopedValue-bound scopes) need the test to own the instance instead and refresh inside it; register it as a singleton, under the name the Tanuki wrapper uses, only when a bean definition of your own `ref`s that name:
private static final PerApplicationScope SCOPE = new PerApplicationScope();
private static ConfigurableApplicationContext context;
@BeforeClass(groups = "unit")
public void beforeClass () {
SCOPE.run(() -> { // (1)
context = new ClassPathXmlApplicationContext(new String[] {"..."}, false);
context.addBeanFactoryPostProcessor( // (2)
(beanFactory) -> beanFactory.registerSingleton("org.smallmind.spark.perApplicationScope", SCOPE));
context.refresh();
});
}
@Override
public void run (IHookCallBack callBack, ITestResult testResult) { // (3)
SCOPE.run(() -> callBack.runTestMethod(testResult));
}-
The refresh runs inside
SCOPE, and the foundation’sPerApplicationContextbean attaches the context map to the same thread when it is instantiated. BecausesystemPropertiesis aPriorityOrderedBeanFactoryPostProcessorthatdepends-onsecurityProviders, whichdepends-onperApplicationContext, Spring instantiates the context bean before it invokes any post-processor — so even theSpringPropertyAccessorthatPropertyPlaceholderConfigurerregisters at post-processor time, and every later libraryregister(…), goes through a bridging*Managerand lands in both maps. Only aBeanFactoryPostProcessoradded programmatically (the lambda in <2>, say), aBeanDefinitionRegistryPostProcessor, or aPriorityOrderedpost-processor the test declares ahead of the<import>whose own construction registers something runs before the context bean exists and registers into the scope alone. -
Only needed when a bean definition of your own
ref`s that name; a definition that wants the instance in hand can instead `refa bean declared as<bean id="perApplicationScope" class="org.smallmind.nutsnbolts.scope.PerApplicationScope" factory-method="getBound"/>, which yieldsSCOPEbecause the refresh runs inside it, with no registration at all. The shippedmock-wire.xmlandrabbitmq-wire.xmlpass<null/>, and a web server’sperApplicationScopeproperty, the phalanx transports, and a pooled data source’sperApplicationScopecan likewise be left unset: constructed or started during a refresh that runs insideSCOPE, they adopt it; handed any other instance on that thread, they throwScopeException. -
Implementing TestNG’s
IHookablebinds every test method without per-method boilerplate (runTestMethodtakes theITestResult, so it cannot be passed as a method reference). Put@Test(groups = "unit")on the test methods, not on the class: a class-level@Testmakes the publicruna test method of its own, which TestNG then fails to inject. Without the class-level annotation nothing inherits itsgroups, so the methods and@BeforeClass/@AfterClassall need the group explicitly (@BeforeClass(groups = "unit")); the repository’s surefire run is group-filtered, and an ungrouped method is silently skipped.@BeforeMethod/@AfterMethodand data providers run outside the hook, on the context-only thread: library lookups there fall back to the context map the foundation attached, which holds the same registrations as the scope (see <1>), while a directPerApplicationScopeor*ScopeManagerread throwsMissingPerApplicationScopeException. A pool started there without aperApplicationScopefinds no scope to adopt and records metrics through whatever binding its threads inherit; metrics never fail, so without a usable registry they are dropped silently.
testbench-style is unlike the rest of testbench: it contains no test support at all. It is two developer command-line tools that keep every pom.xml in the repository consistent. Both walk a project tree from a root path given as the first argument and rewrite poms in place, pretty-printing the result through a bundled XSLT stylesheet (pretty-print.xslt) that strips insignificant whitespace and re-indents.
DependencyOrganizer-
Sorts the
<dependency>entries of everypom.xmlinto a stable canonical order — bygroupId, then byartifactId, using the segment-aware comparison inDependencyWrapper(dot-delimited group segments, dash-delimited artifact segments, each compared alphanumerically, shorter prefixes first). Both the top-level<dependencies>block and the dependencies inside a<dependencyManagement>block are sorted. Entry point:DependencyOrganizer.main(rootPath)orwalkProject(Path). DependencyReducer-
For each module directory (one containing a
pom.xml, excluding the root and any dot-prefixed path segment) runsmvn dependency:analyze -N, parses the report, and rewrites the pom to: drop unused declared dependencies, add used undeclared ones (as group/artifact/scope, with no version on the assumption it is managed elsewhere), and narrow non-test-scoped test-only dependencies totestscope. Surviving dependencies are re-sorted into the same canonical order. The Maven launcher is located via the platformwhere/where.execommand (MavenCommandLocator); subprocess output is captured byProcessOutputUtility, which expects the process to exit within three seconds of closing its output stream.
# Sort every pom under the repository root into canonical order.
java org.smallmind.testbench.style.DependencyOrganizer /path/to/smallmind|
Note
|
|
- Docker daemon not reachable
-
DockerClientUtilitydefaults totcp://localhost:2375(plaintext TCP). SetDOCKER_HOSTto match your daemon (for example a TLS endpoint on2376, or a named pipe / socket) before running container-backed tests. startnever returns-
The readiness loop spins without an internal timeout until every service port connects. A hang means the container started but never opened its port — inspect the container’s logs. The clean-environment guard does not protect against an image that genuinely fails to come up.
- Name or port collision on startup
-
A container from a crashed prior run is still present.
AbstractGroundwaterTest’s clean-environment check should surface this as a `TestConditionTimeoutExceptionwithin thirty seconds; if you bypass that base class, run aContainerAbsentTestConditionyourself, or remove the stale container manually. - No log output
-
TestLoggerConfiguration.setup()configures Scribe but does not provide a backend. Addscribe-ink-indigenous(test scope) soLoggerManagerresolves a logging blueprint. See the installation note above. MissingHostResourceExceptionwhen declaring a mount-
DockerMount/DockerVolumeresolve the host resource from the classpath at construction. The named resource is not on the test classpath, or its URL is malformed. Confirm the resource path is correct and present undersrc/test/resources.
- No internal start timeout
-
DockerApplications.startwaits for readiness indefinitely. This is intentional — the surroundingcondition/groundwaterlayers own the "fail fast on a dirty environment" guard — but it means a genuinely broken image hangs the test rather than failing it. - Hard-coded clean-environment list
-
AbstractGroundwaterTestchecks for a fixed set of leftover containers (Kafka, MongoDB, MySQL, RabbitMQ, Memcached) and GreenMail port8025. A new long-running fixture is not added to that guard automatically. - TestNG-only base class
-
groundwateris built on TestNG’s@BeforeClass/@AfterClass. There is no JUnit equivalent; a JUnit-based test must driveDockerApplicationsdirectly. - Plaintext daemon default
-
The
tcp://localhost:2375fallback assumes an unauthenticated TCP daemon. There is no built-in TLS configuration beyond whatDOCKER_HOSTand the docker-java defaults supply. DependencyReduceris heuristic-
It acts on
mvn dependency:analyzeoutput, which can misclassify dependencies used only via reflection, SPI, or resources. Treat its rewrites as proposals to review, not as authoritative.
| Setting | Default | Source |
|---|---|---|
Docker daemon host |
|
|
Port readiness connect timeout |
|
|
Condition polling interval |
|
|
Clean-environment budget |
|
|
GreenMail absence port |
|
|
Test log level |
|
|
Wire default timeout |
|
|
Subprocess exit grace |
|
|
| File | Role |
|---|---|
|
Enum catalog of container fixtures (image, name, ports, env, mounts). |
|
Static |
|
|
|
Service-port / external-host-port pair. |
|
Bind-mount descriptor; resolves host side from the classpath. |
|
Volume-bind descriptor; resolves host side from the classpath. |
|
In-memory mount descriptor. |
|
Thrown when a mount/volume host resource is unresolved. |
|
Functional interface: one pollable precondition check. |
|
|
|
Marker for an unsatisfied condition; described via |
|
String-backed |
|
Checked timeout exception listing outstanding failures. |
|
Satisfied when named containers are gone. |
|
Satisfied when a GreenMail port is closed. |
|
Satisfied when a broker accepts an AMQP connection. |
|
TestNG base class managing fixture lifecycle. |
|
One-call Scribe console bootstrap. |
|
Spring-bean equivalent of the console bootstrap. |
|
Spring bootstrap context (per-app context, BouncyCastle, properties). |
|
Default test properties. |
|
Sorts pom dependencies into canonical order. |
|
Adds/removes/re-scopes dependencies from |
|
Parsed coordinate from analyze output. |
|
Sortable wrapper around a |
|
Locates the |
|
Captures subprocess stdout. |
|
Whitespace-stripping re-indent stylesheet. |
-
Sleuth — the dependency-aware test runner and Surefire provider that executes these suites.
-
Scribe — the logging system
testbench-loggerconfigures; pair it with a backend such asscribe-ink-indigenousfor output. -
NutsNBolts — provides
PerApplicationContext,FormattedException, and the alphanumeric comparator the style tools sort with. -
docker-java — the daemon client
testbench-dockeradapts.