pytest-databases

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

pytest-databases

A pytest plugin providing ready-made database fixtures for testing using Docker containers.

一个pytest插件，提供现成的数据库fixture，用于通过Docker容器进行测试。

References Index

参考索引

For detailed guides and code examples, refer to the following documents in

references/

Supported Databases
- Examples for PostgreSQL, MySQL, Oracle with service/connection fixtures.
Complete Reference
- Fixture tables for all supported SQL, KV, Search, and Object Storage databases.
Xdist Parallel Testing
- Isolation levels (database vs server) and helper functions.
Configuration
- Fixture overrides and environment variable support.
Troubleshooting
- ARM architecture tips, port conflicts, and health checks.

如需详细指南和代码示例，请参考

references/

目录下的以下文档：

支持的数据库
- PostgreSQL、MySQL、Oracle的服务/连接fixture示例。
完整参考
- 所有支持的SQL、KV、搜索和对象存储数据库的fixture表格。
Xdist并行测试
- 隔离级别（数据库 vs 服务器）和辅助函数。
配置
- Fixture覆盖和环境变量支持。
故障排除
- ARM架构提示、端口冲突和健康检查。

Quick Start

快速开始

1. Enable in Project

1. 在项目中启用

Add to

conftest.py

python

pytest_plugins = ["pytest_databases.docker.postgres"]

添加到

conftest.py

：

python

pytest_plugins = ["pytest_databases.docker.postgres"]

2. Use Fixtures

2. 使用Fixture

python

def test_database(postgres_service):
    # Use postgres_service.host, .port, etc.
    pass

</workflow> <guardrails>

python

def test_database(postgres_service):
    # 使用postgres_service.host、.port等属性
    pass

</workflow> <guardrails>

Guardrails

约束规则

Keep fixtures container-based. Do not monkey-patch or mock the database client — prefer the real service fixture so tests cover driver behavior.
Use
xdist
isolation helpers. For parallel runs, select the
```
database
```
-level or
```
server
```
-level isolation fixtures from
```
references/xdist.md
```
instead of sharing one schema across workers.
Do not hand-roll container lifecycle. Rely on the plugin's fixtures; they handle startup, readiness, and teardown.
Scope fixtures to the smallest unit that works. A session-scoped Docker container with function-scoped schemas is almost always the right trade-off.

</guardrails> <validation>

保持fixture基于容器。 不要修改或模拟数据库客户端——优先使用真实服务fixture，这样测试可以覆盖驱动程序行为。
使用
xdist
隔离辅助工具。对于并行运行，请从
```
references/xdist.md
```
中选择
```
database
```
级或
```
server
```
级隔离fixture，而不是在多个工作进程间共享一个模式。
不要手动管理容器生命周期。 依赖插件的fixture；它们会处理启动、就绪检查和销毁。
将fixture作用域设置为最小可行单元。 会话作用域的Docker容器搭配函数作用域的模式几乎总是正确的权衡方案。

</guardrails> <validation>

Validation Checkpoint

验证检查点

```
conftest.py
```
declares only the database plugins you actually use (
```
pytest_plugins = [...]
```
)
Tests pull the correct fixture (
```
postgres_service
```
,
```
mysql_service
```
, etc.) rather than opening raw connections
Parallel runs (
```
pytest -n auto
```
) produce isolated data — verified via
```
references/xdist.md
```
CI runs Docker-in-Docker (or Podman) with enough resources for the requested fixtures

</validation> <example>

```
conftest.py
```
仅声明实际使用的数据库插件（
```
pytest_plugins = [...]
```
）
测试使用正确的fixture（
```
postgres_service
```
、
```
mysql_service
```
等）而非直接建立原始连接
并行运行（
```
pytest -n auto
```
）生成隔离的数据——通过
```
references/xdist.md
```
验证
CI运行Docker-in-Docker（或Podman）并为请求的fixture分配足够资源

</validation> <example>

Example: PostgreSQL integration test

示例：PostgreSQL集成测试

python

import pytest

pytest_plugins = ["pytest_databases.docker.postgres"]


@pytest.mark.anyio
async def test_user_insert(postgres_service, postgres_connection):
    await postgres_connection.execute(
        "INSERT INTO users (email) VALUES ($1)", "alice@example.com"
    )
    row = await postgres_connection.fetchrow(
        "SELECT email FROM users WHERE email = $1", "alice@example.com"
    )
    assert row["email"] == "alice@example.com"

</example>

python

import pytest

pytest_plugins = ["pytest_databases.docker.postgres"]


@pytest.mark.anyio
async def test_user_insert(postgres_service, postgres_connection):
    await postgres_connection.execute(
        "INSERT INTO users (email) VALUES ($1)", "alice@example.com"
    )
    row = await postgres_connection.fetchrow(
        "SELECT email FROM users WHERE email = $1", "alice@example.com"
    )
    assert row["email"] == "alice@example.com"

</example>

Cross-References

交叉引用

litestar-testing — Litestar-specific testing patterns; integrates pytest-databases fixtures with
```
AsyncTestClient
```
.

litestar-testing — 特定于Litestar的测试模式；将pytest-databases fixture与
```
AsyncTestClient
```
集成。

Official References

官方参考

Shared Styleguide Baseline

共享风格指南基准

Use shared styleguides for generic language/framework rules to reduce duplication in this skill.
General Principles
Testing
Python
Keep this skill focused on tool-specific workflows, edge cases, and integration details.

使用共享风格指南处理通用语言/框架规则，减少本技能文档中的重复内容。
通用原则
测试
Python
保持本技能专注于工具特定的工作流、边缘情况和集成细节。