10.3 · 测试指南（Testing Guide）

记忆管道与知识图谱构建 · 本章是 Cognee DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目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

翻译时间：2026-05-27T08:45:22.541Z

翻译模型：deepseek-chat

原文字符数：13286

项目：Cognee (cognee)

---

测试指南

测试基础设施总览

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 操作在不同持续集成运行器上提供一致的环境。

测试环境设置流程

graph TB
    START["测试任务开始"]
    DETECT["检测环境<br/>（容器 vs 裸运行器）"]

    subgraph "容器环境"
        CONT_CHECK["检查 /app/.anon_id<br/>和预构建的 .venv"]
        CONT_LINK["将项目链接到<br/>/app/.venv"]
        CONT_SYNC["uv sync --frozen --inexact"]
    end

    subgraph "裸运行器环境"
        BARE_PYTHON["通过 actions/setup-python<br/>设置 Python"]
        BARE_UV["通过 astral-sh/setup-uv<br/>安装 uv"]
        BARE_SYNC["使用所有额外依赖<br/>执行 uv sync"]
    end

    TELEMETRY["创建 .anon_id<br/>'test-machine'"]
    READY["环境就绪"]

    START --> DETECT
    DETECT -->|"in-container=true"| CONT_CHECK
    DETECT -->|"in-container=false"| BARE_PYTHON

    CONT_CHECK --> CONT_LINK
    CONT_LINK --> CONT_SYNC
    CONT_SYNC --> TELEMETRY

    BARE_PYTHON --> BARE_UV
    BARE_UV --> BARE_SYNC
    BARE_SYNC --> TELEMETRY

    TELEMETRY --> READY

来源：.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）：

graph TB
    subgraph "自然语言空间"
        PDF["artificial-intelligence.pdf"]
        TEXT["LLM 描述文本"]
        QUERY["'你包含什么信息？'"]
    end

    subgraph "代码实体空间"
        ADD["cognee.add()"]
        COGNIFY["cognee.cognify()"]
        SEARCH["cognee.search()"]
        PRUNE["cognee.prune.prune_system()"]
        REL_ENG["get_relational_engine()"]
        VEC_ENG["get_vector_engine()"]
    end

    PDF --> ADD
    TEXT --> ADD
    ADD --> COGNIFY
    COGNIFY --> SEARCH
    QUERY --> SEARCH
    SEARCH --> PRUNE
    PRUNE --> REL_ENG
    PRUNE --> VEC_ENG

来源：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。

文档读取器测试模式：

graph TB
    subgraph "自然语言空间"
        DOC["example.docx"]
        CSV["example.csv"]
    end

    subgraph "代码实体空间"
        UD["UnstructuredDocument"]
        TC["TextChunker"]
        READ["UnstructuredDocument.read()"]
    end

    DOC --> UD
    CSV --> UD
    UD --> READ
    TC --> READ
    READ -->|"生成"| CHUNK["paragraph_data"]

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

多数据库测试矩阵

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

持续集成矩阵流程：

graph TD
    subgraph "操作系统"
        UBUNTU["Ubuntu 22.04"]
        MACOS["macOS 15"]
        WIN["Windows 最新版"]
    end

    subgraph "Python 版本"
        P311["3.11"]
        P312["3.12"]
    end

    subgraph "数据库提供者"
        V_LANCE["LanceDB"]
        V_PG["PGVector"]
        G_KUZU["Kuzu"]
        G_NEO["Neo4j"]
        G_POSTGRES["Postgres 图"]
    end

    UBUNTU & MACOS & WIN --> P311 & P312
    P311 & P312 --> V_LANCE & V_PG & G_KUZU & G_NEO & G_POSTGRES

来源：.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