求助：使用Testcontainers的JUnit测试等待MySQL连接时超时挂起

我之前也遇到过一模一样的情况！明明容器能通过外部JDBC工具正常连接，JUnit测试却卡在Waiting for database connection to become available at直到超时，容器日志还没任何错误。通常是这几个细节没处理好，给你逐一排查：

1. 检查连接等待策略是否适配你的MySQL版本 #

不同MySQL版本（比如8.0+和5.7）的初始化流程有差异，Testcontainers默认的连接检测逻辑可能没跟上。比如默认的检测语句可能在某些版本里无法正确判断数据库是否就绪，导致一直等待。

你可以手动指定更可靠的SQL查询等待策略，比如用SELECT 1确认连接可用，同时延长超时时间：

@Container
public static MySQLContainer<?> mysqlContainer = new MySQLContainer<>("mysql:8.0")
        .withDatabaseName("testdb")
        .withUsername("testuser")
        .withPassword("testpass")
        .withWaitStrategy(Wait.forListeningPort()
                .and(Wait.forSqlQuery("SELECT 1")
                        .withUsername("testuser")
                        .withPassword("testpass")
                        .withTimeout(Duration.ofMinutes(2))));

这样既等待端口监听，又通过实际的SQL查询确认数据库完全就绪，避免容器端口起来了但内部还在初始化的情况。

2. 绝对不要硬写JDBC URL的端口！ #

这是最常见的坑！Testcontainers默认会给容器分配随机映射端口，如果你在测试代码里硬写localhost:3306，测试程序会去连宿主机的3306端口（而非容器的映射端口），自然连不上超时。但你用外部工具能连上是因为你手动找到了容器的映射端口，测试代码却没拿到正确地址。

正确的做法是直接用容器提供的方法获取连接信息：

// 错误写法
// String jdbcUrl = "jdbc:mysql://localhost:3306/testdb?useSSL=false&serverTimezone=UTC";

// 正确写法
String jdbcUrl = mysqlContainer.getJdbcUrl();
String username = mysqlContainer.getUsername();
String password = mysqlContainer.getPassword();

3. 初始化脚本执行时间过长，超过默认超时 #

如果你的容器挂载了初始化SQL脚本（比如withInitScript("init.sql")），脚本执行时间如果超过Testcontainers默认的等待时长，就会导致超时。

这种情况可以延长启动超时时间：

.withWaitStrategy(Wait.forListeningPort()
        .withStartupTimeout(Duration.ofMinutes(3)))

或者结合SQL查询等待，确保脚本执行完成后再继续测试。

4. JDBC驱动版本与MySQL容器版本不兼容 #

比如你用了MySQL 8.0的容器，但测试依赖的JDBC驱动还是5.x版本，虽然外部工具可能能兼容，但Testcontainers的连接检测逻辑可能因为驱动兼容性问题失败。

确保驱动版本和容器版本匹配，比如MySQL 8.0容器对应8.x的驱动：

<!-- Maven依赖示例 -->
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.33</version>
    <scope>test</scope>
</dependency>

5. Docker网络的小概率问题 #

偶尔Testcontainers默认的网络模式会导致测试程序无法访问容器，你可以尝试临时切换到host模式排查（仅限开发环境，生产不推荐）：

@Container
public static MySQLContainer<?> mysqlContainer = new MySQLContainer<>("mysql:8.0")
        .withNetworkMode("host");

注意host模式下容器会直接使用宿主机端口，要避免端口冲突，而且这个方法不是跨平台兼容的，但能帮你快速排查是不是网络问题。

先从第2点（端口问题）和第1点（等待策略）开始排查，这两个是最常见的原因！

内容的提问来源于stack exchange，提问作者gkephorus