Testcontainers-Python项目中MySQL容器集成测试的常见问题解析

在基于Testcontainers-Python进行Django项目测试时，开发者经常会遇到MySQL容器连接问题。本文将以典型错误"Unknown MySQL server host 'mysql'"为例，深入分析问题根源并提供完整的解决方案。

问题现象分析

当开发者使用testcontainers-python库创建MySQL容器进行集成测试时，在GitHub Actions环境中频繁出现数据库连接失败的情况。错误信息显示系统无法解析MySQL主机地址，而同样的配置在本地开发环境却能正常运行。

核心问题诊断

通过分析典型配置代码可以发现，问题主要源于两个关键因素：

1. 容器网络隔离性：GitHub Actions的容器化执行环境与本地Docker网络存在差异
2. 数据库初始化时序：MySQL服务启动后需要额外的数据库创建步骤

解决方案实现

正确的实现方式需要包含以下关键点：

1. 完整的容器配置

@pytest.fixture(scope="session")
def mysql_container():
    container = MySqlContainer("mysql:8.0")  # 推荐使用稳定版本
    container.with_env("MYSQL_ROOT_PASSWORD", "test")
    container.with_env("MYSQL_DATABASE", "testdb")  # 关键配置：预先创建数据库
    container.with_env("MYSQL_USER", "testuser")
    container.with_env("MYSQL_PASSWORD", "testpass")
    container.with_exposed_ports(3306)
    with container:
        yield container

2. Django配置动态注入

@pytest.fixture(scope="module", autouse=True)
def setup_database(mysql_container, django_db_blocker):
    settings.DATABASES["default"].update({
        "HOST": mysql_container.get_container_host_ip(),
        "PORT": mysql_container.get_exposed_port(3306),
        "NAME": "testdb",  # 必须与容器配置一致
        "USER": "testuser",
        "PASSWORD": "testpass",
    })

最佳实践建议

1. 版本明确化：始终指定具体的MySQL镜像版本，避免使用latest标签
2. 环境隔离：为测试环境配置独立的数据库凭证
3. 健康检查：添加容器就绪检查确保服务可用性
4. 资源清理：测试结束后自动清理测试数据

进阶技巧

对于复杂测试场景，可以考虑：

container.with_command("--character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci")

配置字符集以确保多语言支持，或者使用with_volume_mount挂载初始化SQL脚本实现更复杂的数据库初始化。

通过以上方案，开发者可以构建出稳定可靠的MySQL集成测试环境，确保在CI/CD流水线中也能获得与本地开发一致的行为表现。