10.3 · 测试指南（Testing Guide）

记忆管道与知识图谱构建 · 聚焦本章的模块关系、源码依据与实现要点。

项目Cognee 章节10.3 状态全文译文模块存储与持久化、测试、发布与运维、检索、召回与索引、配置治理

项目要点页2.5 参考项目项目章节目录Cognee DeepWiki 原始章节Testing Guide 上一章10.2 下一章10.4

源码线索

.github/actions/cognee_setup/action.yml
.github/workflows/basic_tests.yml
.github/workflows/db_examples_tests.yml
.github/workflows/e2e_tests.yml
.github/workflows/examples_tests.yml
.github/workflows/graph_db_tests.yml
.github/workflows/relational_db_migration_tests.yml
.github/workflows/reusable_notebook.yml
.github/workflows/search_db_tests.yml
.github/workflows/test_s3_file_storage.yml

模块标签

存储与持久化
测试、发布与运维
检索、召回与索引
配置治理
图谱与关系

章节正文

测试指南

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/10.3-testing-guide

测试指南

测试基础设施总览

Cognee 的测试套件分为多个类别，涵盖单元测试、集成测试和数据库特定测试。测试基础设施使用一个可复用的 cognee_setup 操作，该操作可以检测测试是在容器中运行还是在裸运行器上运行，并据此配置依赖项。

测试类别与位置

类别	位置	目的
单元测试	`cognee/tests/unit/`	隔离的组件测试
集成测试	`cognee/tests/*.py`	端到端工作流测试
文档测试	`cognee/tests/integration/documents/`	验证特定文件类型的处理（PDF、音频等）
数据库测试	`cognee/tests/test_{db_type}.py`	数据库适配器验证
功能测试	`cognee/tests/test_{feature}.py`	特定功能验证（例如遥测、去重）

来源：.github/workflows/basic_tests.yml:71、.github/workflows/e2e_tests.yml:69、cognee/tests/integration/documents/UnstructuredDocument_test.py:19

cognee_setup 可复用操作

cognee_setup 操作在不同持续集成运行器上提供一致的环境。

测试环境设置流程

Cognee · cognee_setup 可复用操作 · 图 1

来源：.github/actions/cognee_setup/action.yml:22-81

cognee_setup 操作提供以下功能：

在 .github/actions/cognee_setup/action.yml:22-30 处自动检测容器与裸运行器
在 .github/actions/cognee_setup/action.yml:32-42 处为裸运行器条件性地安装 Python/uv
在 .github/actions/cognee_setup/action.yml:64-75 处为预构建容器环境进行高效的依赖链接
在 .github/actions/cognee_setup/action.yml:77-80 处创建匿名遥测 ID 以实现测试隔离

在本地运行测试

基本测试执行

使用默认配置的最小测试运行：

# 设置必要的环境变量
export LLM_API_KEY=your_key
export EMBEDDING_API_KEY=your_key

# 安装依赖
uv sync --extra dev

# 运行单元测试
uv run pytest cognee/tests/unit/

# 运行特定的集成测试
uv run python cognee/tests/test_library.py

来源：.github/workflows/basic_tests.yml:70-71、cognee/tests/test_library.py:14-152

数据库特定测试执行

PGVector + PostgreSQL：

# 启动带有 pgvector 扩展的 PostgreSQL
docker run -d \
  -e POSTGRES_USER=cognee \
  -e POSTGRES_PASSWORD=cognee \
  -e POSTGRES_DB=cognee_db \
  -p 5432:5432 \
  pgvector/pgvector:pg17

# 配置并运行测试
export DB_HOST=127.0.0.1
export DB_PORT=5432
export DB_USERNAME=cognee
export DB_PASSWORD=cognee
export DB_PROVIDER=postgres
export VECTOR_DB_PROVIDER=pgvector

uv sync --extra postgres
uv run python cognee/tests/test_pgvector.py

来源：.github/workflows/e2e_tests.yml:136-170、cognee/tests/test_pgvector.py:1-90

Neo4j 图数据库：

# 配置并运行测试
export GRAPH_DATABASE_PROVIDER=neo4j
export GRAPH_DATABASE_URL=bolt://localhost:7687
export GRAPH_DATABASE_USERNAME=neo4j
export GRAPH_DATABASE_PASSWORD=password

uv run python cognee/tests/test_neo4j.py

来源：cognee/tests/test_neo4j.py:15-28、.github/workflows/examples_tests.yml:95-98

Kuzu 图数据库：

export GRAPH_DATABASE_PROVIDER=kuzu
uv run python cognee/tests/test_kuzu.py

来源：cognee/tests/test_kuzu.py:31-34、.github/workflows/graph_db_tests.yml:57

测试类别

单元测试

单元测试用于隔离验证单个组件。它们通过 pytest 执行。

uv run pytest cognee/tests/unit/

来源：.github/workflows/basic_tests.yml:71

集成测试（端到端）

集成测试用于验证完整的 add -> cognify -> search 工作流。

库测试工作流（test_library.py）：

Cognee · 集成测试（端到端） · 图 2

来源：cognee/tests/test_library.py:14-152

功能特定测试

遥测： 验证遥测数据是否根据配置正确发送或阻止。来源：.github/workflows/e2e_tests.yml:71-95
去重： 验证重复数据条目是否被正确处理。来源：.github/workflows/e2e_tests.yml:128-170、cognee/tests/test_deduplication.py
加权边： 使用 get_graph_from_model 对具有加权关系的图模型进行专门测试。来源：.github/workflows/weighted_edges_tests.yml:1-171、cognee/tests/unit/interfaces/graph/test_weighted_edges.py
时间感知： 通过 temporal_awareness_example.py 验证基于时间的知识图谱提取和检索。来源：.github/workflows/examples_tests.yml:101-127
本体： 使用 ontology_as_reference_vocabulary_example.py 验证本体引导的实体提取。来源：.github/workflows/examples_tests.yml:129-156

测试模式与夹具

设置与清理模式

大多数集成测试遵循在执行前后清理系统的模式，以确保幂等性，这通过 cognee.prune 实现。

async def main():
    # 1. 为隔离配置本地存储
    cognee.config.data_root_directory(data_path)
    cognee.config.system_root_directory(system_path)

    # 2. 清理现有数据
    await cognee.prune.prune_data()
    await cognee.prune.prune_system(metadata=True)

    # 3. 运行测试逻辑
    ...

    # 4. 最终清理
    await cognee.prune.prune_data()
    await cognee.prune.prune_system(metadata=True)

来源：cognee/tests/test_library.py:14-30、cognee/tests/test_kuzu.py:30-37

数据库状态验证

测试经常断言底层数据库的状态，以验证 prune 或 delete_data_entity 等操作。

向量引擎验证：

vector_engine = get_vector_engine()
connection = await vector_engine.get_connection()
collection_names = await connection.table_names()
assert len(collection_names) == 0 # 验证清理后为空

来源：cognee/tests/test_library.py:143-145

关系引擎验证：

db_path = get_relational_engine().db_path
file_storage = get_file_storage(os.path.dirname(db_path))
assert not await file_storage.file_exists(os.path.basename(db_path))

来源：cognee/tests/test_library.py:147-155

文档处理测试

cognee/tests/integration/documents/ 中的测试验证不同文件类型如何被读取和切分。它们经常使用 pytest.mark.parametrize 和 unittest.mock.patch 来模拟 get_embedding_engine。

文档读取器测试模式：

Cognee · 文档处理测试 · 图 3

来源：cognee/tests/integration/documents/UnstructuredDocument_test.py:46-110

多数据库测试矩阵

Cognee 在持续集成中使用矩阵策略，以确保在不同操作系统和数据库提供者之间的兼容性。

持续集成矩阵流程：

Cognee · 多数据库测试矩阵 · 图 4

来源：.github/workflows/weighted_edges_tests.yml:30-31、.github/workflows/graph_db_tests.yml:10-24、.github/workflows/vector_db_tests.yml:10-24

测试多租户

多租户和后端访问控制（基于角色的访问控制，RBAC）通过启用特定标志并验证数据集隔离来进行测试。test_pgvector.py 中的测试专门验证当数据实体从数据集中删除时，本地文件是否被正确删除。

# 启用访问控制
os.environ["ENABLE_BACKEND_ACCESS_CONTROL"] = "true"

# 测试获取特定用户和数据集的文档 ID
user = await get_default_user()
document_ids = await get_document_ids_for_user(user.id, [dataset_name])
assert len(document_ids) == 1

来源：cognee/tests/test_pgvector.py:53-69、.github/workflows/examples_tests.yml:84