Testcontainers for Python

testcontainers-python 方便使用 Docker 容器进行功能和集成测试。该软件包集合目前支持以下功能。

入门

from testcontainers.postgres import PostgresContainer
import sqlalchemy

with PostgresContainer("postgres:16") as postgres:
    psql_url = postgres.get_connection_url()
    engine = sqlalchemy.create_engine(psql_url)
    with engine.begin() as connection:
        version, = connection.execute(sqlalchemy.text("SELECT version()")).fetchone()
version
'PostgreSQL 16...'

上述代码片段将在容器中启动当前最新版本的 postgres 数据库。get_connection_url()便捷方法返回sqlalchemy兼容的 URL（psycopg2默认使用驱动程序）以连接到数据库并检索数据库版本。

from testcontainers.postgres import PostgresContainer
import psycopg

with PostgresContainer("postgres:16", driver=None) as postgres:
    psql_url = postgres.get_connection_url()
    with psycopg.connect(psql_url) as connection:
        with connection.cursor() as cursor:
            version, = cursor.execute("SELECT version()").fetchone()
version
'PostgreSQL 16...'

此代码片段执行相同的操作，但是使用特定版本并将驱动程序设置为 None，以影响get_connection_url()便捷方法不将驱动程序包含在 URL 中（例如，为了与psycopgv3 兼容）。

请注意，sqlalchemy和psycopg包不再是依赖项testcontainers[postgres]，也不需要启动 Postgres 容器。因此，您的项目需要声明对代码中使用的驱动程序和数据库访问方法的依赖关系。

默认情况下，Testcontainers 将通过网关 IP 搜索容器。您可以使用环境变量TESTCONTAINERS_HOST_OVERRIDE手动指定自己的 IP 。

安装

testcontainers 包套件可在PyPI上获得，可以使用 安装该包pip。

从4.0.0版本开始，我们不再支持testcontainers-*包，因为维持所有权是不可持续的。

相反，可以通过指定extras来安装软件包，例如。pip install testcontainers[postgres]

请注意，社区模块将尽最大努力提供支持，重大更改不会在软件包中创建主要版本。因此，只有软件包核心严格遵循 SemVer。如果您的工作流程因小更新而中断，请查看更改日志以获取指导。

自定义容器

核心模块支持基于自定义镜像制作容器。请查看核心文档了解更多信息。

这使您可以从不属于 testcontainers-python 提供的模块的图像创建容器。

对于常见用例，您还可以使用testcontainers-generic模块提供的通用容器。请查看通用文档以获取更多信息。（例如：用于运行 FastAPI 服务器的ServerContainer ）

Docker 中的 Docker（DinD）

当尝试从 Docker 容器内启动测试容器时（例如在持续集成测试中），必须提供两件事：

容器必须提供 docker 客户端安装。可以使用预装了 docker 的镜像（例如官方 docker 镜像）或从Dockerfile规范中安装客户端。

容器必须能够访问 docker 守护进程，这可以通过挂载/var/run/docker.sock或将DOCKER_HOST环境变量设置为docker run命令的一部分来实现。

私有 Docker 注册表

使用私有docker registry 需要设置 DOCKER_AUTH_CONFIG 环境变量。官方文档

该变量的值应该是一个包含注册表的身份验证信息的 JSON 字符串。

例子：

DOCKER_AUTH_CONFIG='{"auths": {"https://myregistry.com": {"auth": "dXNlcm5hbWU6cGFzc3dvcmQ="}}}'

为了生成 JSON 字符串，您可以使用以下命令：

echo -n '{"auths": {"<url>": {"auth": "'$(echo -n "<username>:<password>" | base64 -w 0)'"}}}'

从云提供商获取密码：

ECR_PASSWORD = $(aws ecr get-login-password --region eu-west-1)
GCP_PASSWORD = $(gcloud auth print-access-token)
AZURE_PASSWORD = $(az acr login --name <registry-name> --expose-token --output tsv)

配置

开发与贡献

我们推荐您使用Poetry进行开发。安装poetry后，您可以运行以下代码片段来设置您的本地开发环境。

make install

包结构

Testcontainers 是一组隐式命名空间包的集合 ，用于解耦不同扩展的开发，例如testcontainers[mysql]分别testcontainers[postgres]用于 MySQL 和 PostgreSQL 数据库容器。

文件夹结构如下：

modules
# One folder per feature.
[feature name]
    # Folder without __init__.py for implicit namespace packages.
    testcontainers
        # Implementation as namespace package with __init__.py.
        [feature name]
            __init__.py
            # Other files for this
            ...
    # Tests for the feature.
    tests
        test_[some_aspect_for_the_feature].py
        ...
    # README for this feature.
    README.rst