feat: run @StormTest and @DataStormTest against a real database with Testcontainers

[zantvoort]

Fixes #502

What

@StormTest and @DataStormTest gain database and image attributes that run the test on the database the application deploys on, in a Testcontainers-managed container, without any container wiring in the test class:

@StormTest(database = POSTGRESQL, scripts = {"/schema.sql", "/data.sql"})
class VisitRepositoryTest {

    @Test
    void findsVisitsByPet(ORMTemplate orm) {
        // running against a real PostgreSQL
    }
}

• st.orm.test.TestDatabase: H2 (default), POSTGRESQL, MYSQL, MARIADB, MSSQL_SERVER, ORACLE, each with a pinned default image (postgres:17, mysql:8.4, mariadb:11.8, mcr.microsoft.com/mssql/server:2022-latest, gvenzl/oracle-free:23-slim-faststart). Majors are pinned, patch levels float. image names another tag or another distribution of the database (pgvector/pgvector:pg17).
• DatabaseContainer: JVM-wide registry keyed by database and image; the container starts on first use and is shared by every test class of the run. createDatabase() provisions a fresh database inside the container per test class (JUnit) or per Spring context (slice): a new catalog on PostgreSQL, MySQL, MariaDB and SQL Server, a new user on Oracle, dropped when the class or context completes. That is what makes reuse safe beyond per-test rollback: scripts run into an empty database with no drop guards, and classes never observe each other's tables. Exposed publicly (TestDatabase.POSTGRESQL.container()) for setups outside the annotations.
• Testcontainers is a provided dependency of storm-test. Only JdbcContainers references Testcontainers types and it is loaded after a Class.forName check, so a missing module or driver fails with add org.testcontainers:postgresql in test scope rather than a NoClassDefFoundError; tests on H2 pull in nothing new. database combined with url, a dataSource() factory, or image without a container database fails with an ExtensionConfigurationException naming the conflict.
• @DataStormTest: a second ContextCustomizerFactory provisions the database, points spring.datasource.url/username/password at it, sets spring.test.database.replace=none and, unless the application configures it, spring.sql.init.mode=always so schema.sql initializes the container database as it does the embedded one. The customizer is part of the context cache key. storm-spring-boot-test-autoconfigure now depends on storm-test, so both annotations share one container within a JVM.
• Docs: docs/testing.md (new section, attribute table), docs/spring-integration.md, docs/ai.md; CHANGELOG entry.

Notes

• Testcontainers splits org.testcontainers.containers across its jars, so it can never be requires static from a module descriptor. storm-test compiles it from the classpath with --add-reads storm.test=ALL-UNNAMED (compiler and javadoc), commented in module-info.java.
• The MySQL default is the 8.4 LTS line rather than the current lts tag (9.7): Testcontainers 1.21.3's bundled my.cnf sets innodb_log_file_size, which MySQL 9.x rejects, so 9.7 and latest fail to start under the Boot 3.5 BOM's Testcontainers.
• SQL Server's EULA is not accepted on the user's behalf; Testcontainers' container-license-acceptance.txt mechanism applies and is documented.
• storm-test's tests now need Docker: real container tests for all five databases (lifecycle, reuse across classes, fresh database per class, image override, configuration conflicts, missing-dependency message via an isolated class loader), plus a PostgreSQL slice test. Locally the whole storm-test suite runs in about 50s with images cached.
• Left for follow-ups: aligning the dialect modules' own test images with these defaults (CI pulls both sets), the website testing tutorial (update once 1.14.0 ships), and a database parameter for Ktor's testStormApplication.

[codecov]

Codecov Report

❌ Patch coverage is 81.01852% with 41 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...t/src/main/java/st/orm/test/DatabaseContainer.java	85.57%	11 Missing and 4 partials ⚠️
...DataStormTestDatabaseContextCustomizerFactory.java	66.66%	5 Missing and 4 partials ⚠️
...st/src/main/java/st/orm/test/SimpleDataSource.java	40.00%	9 Missing ⚠️
...test/src/main/java/st/orm/test/JdbcContainers.java	58.82%	7 Missing ⚠️
...test/src/main/java/st/orm/test/StormExtension.java	96.55%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!