12.2 · 测试框架（Testing Framework）

测试框架（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/getzep/graphiti/12.2-testing-framework

翻译时间：2026-05-27T08:44:56.231Z

翻译模型：deepseek-chat

原文字符数：10165

项目：Graphiti (graphiti)

---

测试框架

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

• .github/workflows/release-graphiti-core.yml
• .github/workflows/typecheck.yml
• .github/workflows/unit_tests.yml
• Makefile
• pytest.ini
• tests/evals/data/longmemeval_data/README.md
• tests/evals/data/longmemeval_data/longmemeval_oracle.json
• tests/evals/eval_cli.py
• tests/evals/eval_e2e_graph_building.py
• tests/evals/pytest.ini
• tests/evals/utils.py
• tests/helpers_test.py
• tests/test_add_triplet.py

本文档记录了用于测试 graphiti-core 库的结构、约定和工具。它涵盖了单元测试与集成测试的区别、使用的 pytest 标记和夹具、如何为集成测试配置数据库服务、评估框架（LongMemEval）以及可用于本地开发的 make 目标。

---

测试目录结构

测试位于仓库根目录下的 tests/ 目录中，其结构镜像了 graphiti_core/ 的结构。

tests/
├── helpers_test.py                    # 共享的夹具和断言辅助函数
├── test_node_int.py                   # 节点 CRUD 集成测试 [tests/test_node_int.py:1-213]()
├── test_edge_int.py                   # 边 CRUD 集成测试 [tests/test_edge_int.py:1-203]()
├── test_graphiti_int.py               # 完整的 add_episode 集成测试
├── cross_encoder/
│   └── test_bge_reranker_client_int.py # 重排序器集成测试 [tests/cross_encoder/test_bge_reranker_client_int.py:1-79]()
├── utils/
│   └── maintenance/
│       └── test_entity_extraction.py  # 节点提取逻辑的单元测试 [tests/utils/maintenance/test_entity_extraction.py:1-226]()
└── evals/                             # 评估框架（LongMemEval）
    ├── data/                          # 数据集文件（longmemeval_oracle.json）
    ├── eval_e2e_graph_building.py     # 端到端图构建评估逻辑 [tests/evals/eval_e2e_graph_building.py:1-181]()
    └── eval_cli.py                    # 运行评估的 CLI 入口点 [tests/evals/eval_cli.py:1-41]()

来源：tests/test_node_int.py:22-27, tests/test_edge_int.py:24-25, tests/evals/eval_cli.py:4-5, tests/cross_encoder/test_bge_reranker_client_int.py:19-20

---

测试分类

测试根据外部依赖需求分为不同类别。

类别	pytest 标记	所需外部服务	运行内容
单元测试	not integration	无	使用模拟的大语言模型（LLM）、嵌入向量生成器和图驱动的逻辑测试
数据库集成测试	not integration（但需要数据库）	Neo4j、FalkorDB、Kuzu	节点/边 CRUD、使用模拟大语言模型（LLM）的完整管线
完整大语言模型（LLM）集成测试	integration	Neo4j/FalkorDB + 真实大语言模型（LLM）API	端到端的情节入库
评估	不适用	Neo4j + 真实大语言模型（LLM）API	针对数据集的性能基准测试

测试类别决策流程

基于外部依赖的测试类别选择：

flowchart TD
    T["测试文件"] --> Q1{"需要真实\n大语言模型（LLM）API？"}
    Q1 -- "是" --> Q3{"是否用于\n基准测试？"}
    Q3 -- "是" --> M4["评估框架\n(tests/evals/)"]
    Q3 -- "否" --> M1["@pytest.mark.integration\n(tests/test_graphiti_int.py)"]
    Q1 -- "否" --> Q2{"需要运行中的\n数据库？"}
    Q2 -- "否" --> M2["单元测试\n（模拟的 GraphDriver）"]
    Q2 -- "是" --> M3["数据库集成测试\n(tests/helpers_test.py:graph_driver)"]

来源：pytest.ini:3-3, tests/evals/eval_e2e_graph_building.py:125-128

---

评估框架（LongMemEval）

Graphiti 包含一个专门的评估框架，位于 tests/evals/ 目录中。它使用 LongMemEval 数据集来衡量图构建质量和时间推理能力。

关键组件

• 数据集：使用 longmemeval_oracle.json，这是一个用于长期记忆评估的开源数据集 tests/evals/data/longmemeval_data/longmemeval_oracle.json:1-56。
• 评估逻辑：eval_e2e_graph_building.py 实现了 build_graph 和 eval_graph 函数。它将"候选"图（使用当前代码构建）与"基线"图（先前生成并存储在 baseline_graph_results.json 中）进行比较 tests/evals/eval_e2e_graph_building.py:73-102。
• 评判大语言模型（LLM）：一个大语言模型（LLM）（通常是 GPT-4.1-mini）充当评判者，使用 eval_add_episode_results 提示来确定候选提取结果是否比基线质量更高 tests/evals/eval_e2e_graph_building.py:168-174。

评估流程

评估系统遵循特定流程来比较图构建性能：

1. 基线生成：运行 build_baseline_graph 来入库情节并将结果保存为 JSON 文件 tests/evals/eval_e2e_graph_building.py:105-123。
2. 候选构建：使用当前候选配置运行 build_graph tests/evals/eval_e2e_graph_building.py:136-138。
3. 大语言模型（LLM）评判：使用 EvalAddEpisodeResults 模型对候选结果与基线进行评分 tests/evals/eval_e2e_graph_building.py:168-171。

运行评估

通过 tests/evals/eval_cli.py 触发评估。

# 构建基线结果
uv run python -m tests.evals.eval_cli --multi-session-count 5 --session-length 10 --build-baseline

# 针对现有基线运行评估
uv run python -m tests.evals.eval_cli --multi-session-count 5 --session-length 10

来源：tests/evals/eval_cli.py:7-36

---

pytest 夹具和辅助函数

共享的测试夹具和断言辅助函数定义在 tests/helpers_test.py 中。

驱动选择

tests/helpers_test.py 中的 graph_driver 夹具会根据环境变量动态选择和初始化图驱动 tests/helpers_test.py:116-127。这使得测试可以针对不同的图数据库运行。

graph TD
    A[pytest 测试] --> B{graph_driver 夹具};
    B --> C{检查 DISABLE_NEO4J 环境变量};
    C -- 否 --> D[初始化 Neo4jDriver];
    C -- 是 --> E{检查 DISABLE_FALKORDB 环境变量};
    E -- 否 --> F[初始化 FalkorDriver];
    E -- 是 --> G{检查 DISABLE_KUZU 环境变量};
    G -- 否 --> H[初始化 KuzuDriver];
    G -- 是 --> I{检查 DISABLE_NEPTUNE 环境变量};
    I -- 否 --> J[初始化 NeptuneDriver];
    I -- 是 --> K[抛出 ValueError: 无可用驱动];
    D --> L[返回 GraphDriver 实例];
    F --> L;
    H --> L;
    J --> L;

标题：图驱动选择流程

来源：tests/helpers_test.py:33-66, tests/helpers_test.py:87-114

模拟嵌入向量生成器

mock_embedder 夹具提供了一个模拟的 EmbedderClient，它会为给定的输入返回确定性的、随机生成的嵌入向量 tests/helpers_test.py:165-180。这确保了依赖嵌入向量的测试运行快速且不需要外部服务。

代码实体交互图

如何使用模拟对象测试内部提取逻辑：

flowchart TD
    subgraph "单元测试套件"
        UT["test_entity_extraction.py"]
    end

    subgraph "被测试函数"
        EF["extract_nodes\n(graphiti_core/utils/maintenance/node_operations.py)"]
    end

    subgraph "模拟对象"
        MC["_make_clients\n(tests/utils/maintenance/test_entity_extraction.py:33)"]
        LLM["llm_generate\n(AsyncMock)"]
    end

    UT -- "调用" --> EF
    EF -- "使用" --> MC
    MC -- "包含" --> LLM
    LLM -- "返回" --> RD["extracted_entities\n(JSON)"]

来源：tests/utils/maintenance/test_entity_extraction.py:33-49, tests/utils/maintenance/test_entity_extraction.py:70-96, tests/utils/maintenance/test_entity_extraction.py:110-124

---

必需的环境变量

集成测试需要支持的图数据库和 AI 提供商的连接详情。

数据库凭证

• NEO4J_URI、NEO4J_USER、NEO4J_PASSWORD：由 Neo4jDriver 使用 tests/helpers_test.py:68-70。
• FALKORDB_HOST、FALKORDB_PORT、FALKORDB_USER、FALKORDB_PASSWORD：由 FalkorDriver 使用 tests/helpers_test.py:72-75。
• KUZU_DB：由 KuzuDriver 使用 tests/helpers_test.py:81-81。
• NEPTUNE_HOST、NEPTUNE_PORT、AOSS_HOST：由 NeptuneDriver 使用 tests/helpers_test.py:77-79。

这些变量可以在 .env 文件中设置，也可以直接在环境中设置。对于持续集成（CI），它们在 GitHub Actions 工作流中配置 /.github/workflows/unit_tests.yml:87-91。

AI 提供商密钥

• OPENAI_API_KEY：与 OpenAI 模型交互的测试所需。
• 其他大语言模型（LLM）/嵌入向量生成器提供商的密钥（例如 ANTHROPIC_API_KEY、GOOGLE_API_KEY）可能特定提供商集成测试所需。

来源：tests/helpers_test.py:31-31, tests/helpers_test.py:68-81, /.github/workflows/unit_tests.yml:87-91

---

本地运行测试

使用标准的 pytest 命令或 make 目标来执行测试套件。

Make 目标

• make test：仅运行单元测试，排除标记为 integration 的测试。它会通过设置环境变量来禁用 FalkorDB、Kuzu 和 Neptune 驱动 Makefile:28-29。
• make check：依次执行 format、lint 和 test 目标 Makefile:32-32。

pytest 命令

# 运行所有测试（如果设置了环境变量，则包括集成测试）
uv run pytest

# 运行特定的集成测试
uv run pytest tests/test_node_int.py

# 运行单元测试，排除标记为集成测试的测试
uv run pytest -m "not integration"

# 仅运行集成测试
uv run pytest -m "integration"

异步配置

异步测试通过 pytest.ini 中的 asyncio_mode = auto 设置自动运行 pytest.ini:5-5。夹具循环作用域设置为 function pytest.ini:4-4。

来源：Makefile:10-33, pytest.ini:1-6