Three hosts can start dev services, all through the same vidocq-runtime-devservices-host machinery:

Testcontainers and the Docker client never reach the application’s own module path: they live in vidocq-runtime-devservices-host and the providers, consumed only by the host. The application depends on nothing but vidocq-runtime-devservices-extension, which reads a small state file and has no Testcontainers, no Maven API and no JSON library of its own.

Every dev services jar is a named module NEW, as every published Vidocq jar is: none of them reaches a module path as an automatic module. The providers name Testcontainers by the name its jar’s file gives it (testcontainers), which is fine where they run, the plugin’s class path, and they need Testcontainers' core only: the PostgreSQL provider configures a plain container rather than Testcontainers' postgresql module. vidocq-runtime-devservices-junit still lands on a test run’s class path, where its META-INF/services entry finds it; on a module path, its provides does.

A provider’s keys are one of two kinds:

vidocq.pool.url in that same file is still no opt-out: a PostgreSQL URL there never disables the PostgreSQL dev service. What the file tells the provider is which database the application uses.

vidocq:run starts the application the way the production launcher does, so it starts no container unless asked — the same vidocq.dev.devServices tuning key turns it on, as a -D or in vidocq.properties:

Once on, vidocq:run and vidocq:dev share every other piece: the providers, the "Connection information" console block, target/vidocq-dev-services.properties, the state file, and the extension added to the child’s module path. Ctrl+C, or the process exiting on its own, stops the containers exactly once.

A test that only needs a database adds the JUnit host’s listener and the provider it wants, both test scope:

No annotation is needed in the tests themselves: vidocq-runtime-devservices-junit registers a JUnit Platform LauncherSessionListener, discovered through META-INF/services, that starts the providers found on the test class path once, before any test class, injects their coordinates as system properties (vidocq.pool.url, .username, .password, …), and stops them once the whole test run ends — one set of containers for the whole suite. -Dvidocq.dev.devServices=false, or that same key in the application’s own files, skips it entirely; without Docker or Podman, the listener fails the run fast, naming the runtime it looked for and the key that switches it off, so a test that needed the database does not time out silently.

Whichever host started them, the application reads one state file, <basedir>/target/vidocq-dev-services.json — <basedir> is always the project’s own pom.xml directory, unaffected by a custom project.build.directory — through vidocq-runtime-devservices-extension, which the host adds to the child’s module path (the Maven-plugin hosts) or which arrives on the class path (the JUnit host, transitively with vidocq-runtime-devservices-junit). An application declares nothing itself.

A real run of this repository’s own end-to-end integration test (vidocq-runtime-it-devservices, -Pdocker) shows what the detailed report prints:

The summary names every service, its image and its first endpoint, and the host that started it; the detailed report adds a row per service and, in a dev launch, every key it injected — a secret (vidocq.pool.password above) always as configured, never its value, whatever the launch mode. Without a state file or the vidocq.devservices.state system property, the summary reads no dev service: not started by vidocq:dev, vidocq:run or the test launcher — not an anomaly, the ordinary state of an application nobody has started with a dev service yet. The extension never scans target/ for a stray file on its own: a killed session’s leftover file is read again only when a later host overwrites vidocq.devservices.state, never merely because the file exists.

A provider that did not start and said why (A PostgreSQL container only for a PostgreSQL application NEW) gets a row of its own, at every verbosity: the row postgres, its value not started: vidocq.pool.url is jdbc:h2, not PostgreSQL. When no service started and at least one said why, the summary reads no dev service started. The dev console’s Dev services panel shows the same rows. The state file keeps them as "skipped": [{"id": "postgres", "reason": "…"}]; a file written before that key existed reads as none.

Continuous testing reuses the dev containers: under vidocq:dev every test run gets the session’s connection keys, and vidocq:test opens a session of its own, host vidocq:test. Each run gets -Dvidocq.dev.devServices=false, so the tests never start a second set of containers.

A key whose last dot-separated segment names a secret — password, passwd, pwd, secret, token, key, credential(s), apikey, api-key, private-key, in any case — is written to the state file as "configured": true, never with its value; a URL loses its user:password@ part and any secret query parameter is masked as * before anything is written. Only target/vidocq-dev-services.properties, documented in DEV_SERVICES.md’s "Connection information", keeps a password in clear text, on purpose: it is the local, machine-only file an external tool — `psql, DataGrip, a migration runner — reads to connect to the dev database without a JDBC URL copied by hand.