测试文档

本文档描述了 Markdown MCP Servers 项目的测试结构、测试用例和使用方法。

1. 测试结构

1.1 测试目录结构

markdown-mcp/
├── tests/                          # 测试目录
│   ├── __init__.py                 # 包初始化文件
│   ├── test_config.py              # 测试配置文件
│   ├── test_extractor.py           # TOC 核心功能测试
│   ├── test_edge_cases.py          # TOC 边界情况测试
│   ├── test_server.py              # TOC 服务器功能测试
│   ├── test_yarn_integration.py    # TOC 集成测试
│   ├── test_comprehensive.py       # TOC 综合功能测试
│   ├── test_generate_toc.py        # TOC 生成功能测试
│   ├── test_consistency.py         # TOC 参数一致性测试
│   ├── editor/                     # 编辑器测试目录
│   │   ├── __init__.py
│   │   ├── test_editor_mcp_server.py    # 编辑器服务器测试
│   │   ├── test_semantic_editor.py      # 语义编辑功能测试
│   │   ├── test_ast_parser.py           # AST 解析测试
│   │   └── test_format_markdown.py      # Markdown 格式化测试
│   ├── toc/                        # TOC 测试目录
│   │   ├── __init__.py
│   │   └── test_toc_mcp_server.py       # TOC 服务器测试
│   └── fixtures/                   # 测试数据文件
│       ├── yarn.md                 # YARN 文档测试数据
│       └── sample_docs/           # 示例文档目录
├── run_tests.py                    # 统一测试运行脚本
├── run_tests_toc.py                # TOC 专用测试脚本
├── run_tests_editor.py             # 编辑器专用测试脚本
└── docs/
    └── testing.md                  # 本文档

1.2 测试文件说明

测试文件	功能描述	测试内容
`test_config.py`	测试配置文件	测试环境配置参数、常量定义、路径配置、性能配置、测试数据
`test_extractor.py`	TOC 核心功能测试	TOC 提取、编号分析、TOC 生成、汉字编号识别、便利函数、has_issues 含义验证
`test_edge_cases.py`	TOC 边界情况测试	空文件、特殊字符、极大文件、格式错误、复杂嵌套、多语言混合、内存使用
`test_server.py`	TOC 服务器功能测试	MCP 服务器的 TOC 提取、编号分析、详细编号分析、错误处理、性能测试
`test_yarn_integration.py`	TOC 集成测试	基于 yarn.md 的复杂文档处理、中英文混合内容、代码块处理、性能测试
`test_comprehensive.py`	TOC 综合功能测试	TOC 生成格式（Markdown、HTML、Text）、YARN 文档处理、健壮性、性能内存测试
`test_generate_toc.py`	TOC 生成测试	基本 TOC 生成、多格式输出、参数配置、性能测试、README 文件处理
`test_consistency.py`	TOC 参数一致性测试	核心文件间参数一致性、默认值一致性、类型定义一致性、配置文件一致性验证
`test_editor_mcp_server.py`	编辑器服务器测试	MCP 服务器的语义编辑、文档转换、标题编辑、编号检查、文档分析功能测试
`test_semantic_editor.py`	语义编辑功能测试	SIR 转换、语义编辑操作、标题重编号、章节插入、文档分析功能验证
`test_ast_parser.py`	AST 解析测试	Markdown AST 解析、节点操作、结构分析、格式转换功能测试
`test_format_markdown.py`	Markdown 格式化测试	文档格式化、缩进优化、行长度控制、格式一致性验证
`test_toc_mcp_server.py`	TOC 服务器测试	TOC MCP 服务器的功能完整性、协议兼容性、错误处理测试

2. 测试用例分类

2.1 核心功能测试

2.1.1 TOC 提取测试

目标：验证标题提取的准确性
测试内容：
- 多级标题提取
- 标题层级识别
- 行号记录
- 标题内容解析

2.1.2 编号分析测试

目标：验证编号问题检测功能
测试内容：
- 重复编号检测
- 不连续编号检测
- 编号统计分析
- has_issues 状态判断

2.1.3 TOC 生成测试

目标：验证 TOC 生成的正确性
测试内容：
- Markdown 格式生成
- HTML 格式生成
- 文本格式生成
- 生成结果验证

2.1.4 汉字编号测试

目标：验证汉字数字识别功能
测试内容：
- 基础汉字数字（一、二、三）
- 复合汉字数字（十一、二十）
- 繁体汉字数字
- 无效输入处理

2.1.5 便利函数测试

目标：验证便利函数的功能
测试内容：
- extract_and_analyze 函数
- 返回结果结构验证
- 错误处理

2.1.6 has_issues 含义测试

目标：验证 has_issues 返回值的正确性
测试内容：
- 正常编号文档（has_issues: False）
- 重复编号文档（has_issues: True）
- 不连续编号文档（has_issues: True）

2.2 边界情况测试

2.2.1 空内容处理

空字符串
只有空白字符
只有换行符

2.2.2 特殊字符处理

特殊符号标题
emoji 表情符号
中英文混合
数字和符号组合

2.2.3 极端情况

极大文档（6000+ 标题）
深层嵌套（6 级标题）
格式错误的标题

2.2.4 多语言支持

中文标题
英文标题
中英文混合
其他语言字符

2.3 编辑器功能测试

2.3.1 SIR 转换测试

目标：验证结构化中间表示（SIR）转换功能
测试内容：
- Markdown 到 SIR 格式转换
- SIR 到 Markdown 格式转换
- 双向转换的一致性验证
- 复杂文档结构的保持

2.3.2 语义编辑测试

目标：验证语义级别的编辑操作
测试内容：
- 标题编辑（文本修改、级别调整）
- 章节插入和移动
- 编号重排和检查
- 文档结构分析

2.3.3 AST 解析测试

目标：验证 Markdown AST 解析功能
测试内容：
- 语法树构建准确性
- 节点操作功能
- 结构分析和遍历
- 格式转换和优化

2.4 性能测试

2.4.1 性能指标

TOC 提取性能：< 5.0 秒（6000+ 标题）
TOC 分析性能：< 2.0 秒
TOC 生成性能：< 3.0 秒
SIR 转换性能：< 2.0 秒（大型文档）
语义编辑性能：< 1.0 秒（单次操作）

2.4.2 内存使用

大文档处理时的内存占用
内存泄漏检测
并发处理的内存管理

3. 使用方法

3.1 运行所有测试

# 运行所有测试（包括 TOC 和编辑器）
python run_tests.py
python run_tests.py --all

# 运行所有测试并生成报告
python run_tests.py --report

# 详细输出模式
python run_tests.py --verbose
python run_tests.py -v

# 同时使用详细输出和生成报告
python run_tests.py --verbose --report
python run_tests.py -v -r

3.2 运行特定测试套件

# 只运行 TOC 核心功能测试
python run_tests.py --core
python run_tests_toc.py --core

# 只运行 TOC 边界情况测试
python run_tests.py --edge
python run_tests_toc.py --edge

# 只运行 TOC 服务器测试
python run_tests.py --server
python run_tests_toc.py --server

# 只运行 TOC 集成测试
python run_tests.py --integration
python run_tests_toc.py --integration

# 只运行 TOC 综合测试
python run_tests.py --comprehensive
python run_tests_toc.py --comprehensive

# 只运行 TOC 参数一致性测试
python run_tests.py --consistency
python run_tests_toc.py --consistency

# 只运行 TOC 生成功能测试
python run_tests.py --generate-toc
python run_tests_toc.py --generate-toc

# 只运行编辑器服务器测试
python run_tests_editor.py --server

# 只运行语义编辑功能测试
python run_tests_editor.py --semantic

# 只运行 AST 解析测试
python run_tests_editor.py --ast

# 只运行格式化测试
python run_tests_editor.py --format

3.3 运行单个测试文件

# TOC 相关测试
python tests/test_config.py
python tests/test_extractor.py
python tests/test_edge_cases.py
python tests/test_server.py
python tests/test_yarn_integration.py
python tests/test_comprehensive.py
python tests/test_generate_toc.py
python tests/test_consistency.py
python tests/toc/test_toc_mcp_server.py

# 编辑器相关测试
python tests/editor/test_editor_mcp_server.py
python tests/editor/test_semantic_editor.py
python tests/editor/test_ast_parser.py
python tests/editor/test_format_markdown.py

4. 测试配置

4.1 配置文件

测试配置定义在 tests/test_config.py 中，包括：

路径配置：基础目录、项目根目录、fixtures 目录、报告目录
性能配置：提取时间限制（5.0s）、分析时间限制（2.0s）、生成时间限制（3.0s）
测试数据：标准测试内容、重复编号内容、不连续编号内容、汉字编号内容、混合编号内容、特殊字符内容、深层嵌套内容
期望结果：各种测试内容的预期标题数量和层级
输出格式：支持 markdown、html、text 格式
超时配置：默认超时（30s）、性能测试超时（60s）、集成测试超时（120s）

4.2 环境要求

Python 3.8+
项目依赖包已安装（参考 requirements.txt）
测试数据文件存在于 tests/fixtures/ 目录
编辑器功能需要额外的 Markdown 处理库支持

4.3 测试数据

测试使用的数据文件位于 tests/fixtures/ 目录：

yarn.md：复杂的真实文档，用于集成测试和综合功能验证
sample_docs/：示例文档目录，包含各种格式的 Markdown 文档
- basic.md：基础文档结构
- complex_nested.md：复杂嵌套结构
- multilingual.md：多语言混合内容
- formatting_issues.md：格式问题文档

注：其他测试数据（如标准测试内容、重复编号内容等）直接定义在 test_config.py 的 TEST_CONFIG["test_data"] 中。

5. 测试报告

5.1 报告格式

测试报告以 JSON 格式保存在 tests/reports/ 目录，包含：

{
  "timestamp": "2024-01-01T12:00:00",
  "summary": {
    "total_tests": 5,
    "passed_tests": 5,
    "failed_tests": 0,
    "success_rate": 100.0,
    "total_duration": 15.23
  },
  "test_results": {
    "test_extractor.py": {
      "status": "PASSED",
      "details": {
        "duration": 3.45,
        "output": "..."
      }
    }
  }
}

5.2 报告类型

综合报告：run_tests.py --report 生成的总体测试报告
单独报告：各测试文件生成的专项报告
- core_functions_test_report.json：核心功能测试报告
- edge_cases_test_report.json：边界情况测试报告
- markdown_toc_test_report.json：服务器功能测试报告
- yarn_integration_test_report.json：集成测试报告
- comprehensive_test_report.json：综合功能测试报告
- generate_toc_test_report.json：TOC 生成功能测试报告

5.3 报告内容

测试总结：总测试数、通过数、失败数、成功率、总耗时
详细结果：每个测试文件的状态、耗时、输出信息
时间戳：测试运行时间
测试环境：Python 版本、系统信息等

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

测试文档

1. 测试结构

1.1 测试目录结构

1.2 测试文件说明

2. 测试用例分类

2.1 核心功能测试

2.1.1 TOC 提取测试

2.1.2 编号分析测试

2.1.3 TOC 生成测试

2.1.4 汉字编号测试

2.1.5 便利函数测试

2.1.6 has_issues 含义测试

2.2 边界情况测试

2.2.1 空内容处理

2.2.2 特殊字符处理

2.2.3 极端情况

2.2.4 多语言支持

2.3 编辑器功能测试

2.3.1 SIR 转换测试

2.3.2 语义编辑测试

2.3.3 AST 解析测试

2.4 性能测试

2.4.1 性能指标

2.4.2 内存使用

3. 使用方法

3.1 运行所有测试

3.2 运行特定测试套件

3.3 运行单个测试文件

4. 测试配置

4.1 配置文件

4.2 环境要求

4.3 测试数据

5. 测试报告

5.1 报告格式

5.2 报告类型

5.3 报告内容

FilesExpand file tree

testing.md

Latest commit

History

testing.md

File metadata and controls

测试文档

1. 测试结构

1.1 测试目录结构

1.2 测试文件说明

2. 测试用例分类

2.1 核心功能测试

2.1.1 TOC 提取测试

2.1.2 编号分析测试

2.1.3 TOC 生成测试

2.1.4 汉字编号测试

2.1.5 便利函数测试

2.1.6 has_issues 含义测试

2.2 边界情况测试

2.2.1 空内容处理

2.2.2 特殊字符处理

2.2.3 极端情况

2.2.4 多语言支持

2.3 编辑器功能测试

2.3.1 SIR 转换测试

2.3.2 语义编辑测试

2.3.3 AST 解析测试

2.4 性能测试

2.4.1 性能指标

2.4.2 内存使用

3. 使用方法

3.1 运行所有测试

3.2 运行特定测试套件

3.3 运行单个测试文件

4. 测试配置

4.1 配置文件

4.2 环境要求

4.3 测试数据

5. 测试报告

5.1 报告格式

5.2 报告类型

5.3 报告内容