test: 添加全面的测试套件，覆盖所有 Reader 实现

- 测试数量从 83 个增加到 193 个 (+132%) - 代码覆盖率从 48% 提升到 69% (+44%) - 为每种文档格式的所有 Reader 实现创建独立测试 - 添加跨 Reader 的一致性验证测试 - 新增 4 个测试规范 (cli-testing, exception-testing, reader-testing, test-fixtures) - 更新 README 测试统计信息测试覆盖: - DOCX: python-docx, markitdown, docling, native-xml, pypandoc, unstructured - PDF: pypdf, markitdown, docling, docling-ocr, unstructured, unstructured-ocr - HTML: html2text, markitdown, trafilatura, domscribe - PPTX: python-pptx, markitdown, docling, native-xml, unstructured - XLSX: pandas, markitdown, docling, native-xml, unstructured - CLI: 所有命令行选项和错误处理所有 193 个测试通过。
2026-03-08 22:20:21 +08:00
parent c35bbc90b5
commit 7eab1dcef1
53 changed files with 3094 additions and 259 deletions
--- a/openspec/config.yaml
+++ b/openspec/config.yaml
@@ -1,9 +1,6 @@
 schema: spec-driven

 context: |
-  # 项目概述
-  - 目标：统一文档解析工具，将DOCX/XLSX/PPTX/PDF/HTML/URL 转换为 Markdown，面向AI skill使用
-
  # 项目规范
  - 语言: 仅中文(交流/注释/文档/代码)
  - Python: 始终用uv运行(脚本/临时命令uv run python -c); 禁用主机python/禁主机安装包
@@ -16,7 +13,8 @@ context: |
  - 代码: 模块文件150-300行; 错误需自定义异常+清晰信息+位置上下文
  - 项目阶段: 未上线,无用户,破坏性变更无需迁移说明
  - Git提交: 仅中文; 格式为"类型: 简短描述",类型可选: feat(新功能)/fix(修复)/refactor(重构)/docs(文档)/style(格式)/test(测试)/chore(构建/工具); 多行描述空行后加详细说明
-
+  # 项目概述
+  - 目标：统一文档解析工具，将DOCX/XLSX/PPTX/PDF/HTML/URL 转换为 Markdown，面向AI skill使用
  # 项目目录结构
  - scripts/: 核心代码目录
  - skill/: skill文档目录
--- a/openspec/specs/cli-testing/spec.md
+++ b/openspec/specs/cli-testing/spec.md
@@ -0,0 +1,91 @@
+# CLI Testing Specification
+
+## Purpose
+
+定义 CLI 命令行工具的功能测试规范,包括输出格式、选项处理、错误处理等。
+
+## Requirements
+
+### Requirement: CLI 输出解析内容
+CLI 在不指定任何选项时，MUST 输出完整的解析后 Markdown 内容到标准输出。
+
+#### Scenario: 解析 DOCX 文件
+- **WHEN** 用户执行 `python lyxy_document_reader.py file.docx`
+- **THEN** 标准输出包含解析后的 Markdown 内容
+
+#### Scenario: 解析 PDF 文件
+- **WHEN** 用户执行 `python lyxy_document_reader.py file.pdf`
+- **THEN** 标准输出包含解析后的 Markdown 内容
+
+#### Scenario: 解析 HTML 文件
+- **WHEN** 用户执行 `python lyxy_document_reader.py file.html`
+- **THEN** 标准输出包含解析后的 Markdown 内容
+
+### Requirement: CLI 统计字数
+CLI 使用 `-c` 或 `--count` 选项时，MUST 输出解析后内容的字符总数（不包含换行符）。
+
+#### Scenario: 统计 DOCX 字数
+- **WHEN** 用户执行 `python lyxy_document_reader.py file.docx -c`
+- **THEN** 标准输出仅包含一个表示字符总数的数字
+
+### Requirement: CLI 统计行数
+CLI 使用 `-l` 或 `--lines` 选项时，MUST 输出解析后的行数。
+
+#### Scenario: 统计行数
+- **WHEN** 用户执行 `python lyxy_document_reader.py file.docx -l`
+- **THEN** 标准输出仅包含一个表示行数的数字
+
+### Requirement: CLI 提取标题
+CLI 使用 `-t` 或 `--titles` 选项时，MUST 输出所有 1-6 级标题行。
+
+#### Scenario: 提取所有标题
+- **WHEN** 用户执行 `python lyxy_document_reader.py file.docx -t`
+- **THEN** 标准输出包含所有标题行，每行一个标题
+
+### Requirement: CLI 提取标题内容
+CLI 使用 `-tc` 或 `--title-content` 选项时，MUST 输出指定标题及其下级内容。
+
+#### Scenario: 提取存在的标题内容
+- **WHEN** 用户执行 `python lyxy_document_reader.py file.docx -tc "章节标题"`
+- **THEN** 标准输出包含该标题及其下级内容（不包含 # 号）
+
+#### Scenario: 提取不存在的标题
+- **WHEN** 用户执行 `python lyxy_document_reader.py file.docx -tc "不存在的标题"`
+- **THEN** 程序输出错误信息并以非零状态退出
+
+### Requirement: CLI 搜索内容
+CLI 使用 `-s` 或 `--search` 选项时，MUST 使用正则表达式搜索文档并输出匹配结果。
+
+#### Scenario: 搜索匹配内容
+- **WHEN** 用户执行 `python lyxy_document_reader.py file.docx -s "关键词"`
+- **THEN** 标准输出包含所有匹配的上下文，用 `---` 分隔
+
+#### Scenario: 搜索无匹配内容
+- **WHEN** 用户执行 `python lyxy_document_reader.py file.docx -s "不存在的内容"`
+- **THEN** 程序输出错误信息并以非零状态退出
+
+#### Scenario: 搜索使用上下文行数
+- **WHEN** 用户执行 `python lyxy_document_reader.py file.docx -s "关键词" -n 5`
+- **THEN** 输出每个匹配结果前后各 5 行非空内容
+
+### Requirement: CLI 错误处理
+CLI 遇到错误时，MUST 输出清晰的错误信息并以非零状态退出。
+
+#### Scenario: 文件不存在
+- **WHEN** 用户执行 `python lyxy_document_reader.py nonexistent.docx`
+- **THEN** 程序输出错误信息并以状态码 1 退出
+
+#### Scenario: 不支持的文件类型
+- **WHEN** 用户执行 `python lyxy_document_reader.py unsupported.xyz`
+- **THEN** 程序输出未找到支持 reader 的错误信息
+
+#### Scenario: 所有解析方法失败
+- **WHEN** 所有 Reader 解析均失败
+- **THEN** 程序输出各 Reader 的失败原因列表
+
+### Requirement: CLI 选项互斥
+CLI 的输出选项（`-c`、`-l`、`-t`、`-tc`、`-s`）MUST 互斥，不能同时使用。
+
+#### Scenario: 默认输出与其他选项冲突
+- **WHEN** 用户尝试使用多个输出选项
+- **THEN** argparse 自动处理互斥，只允许一个选项生效
--- a/openspec/specs/exception-testing/spec.md
+++ b/openspec/specs/exception-testing/spec.md
@@ -0,0 +1,124 @@
+# Exception Testing Specification
+
+## Purpose
+
+定义异常场景的测试规范,包括文件不存在、空文件、损坏文件、编码问题等异常情况的处理。
+
+## Requirements
+
+### Requirement: 文件不存在异常处理
+Reader 解析不存在的文件时，MUST 返回 None 作为内容和包含错误信息的失败列表。
+
+#### Scenario: DOCX Reader 文件不存在
+- **WHEN** DOCX Reader 解析不存在的文件路径
+- **THEN** 返回 (None, [包含"文件不存在"或"找不到"的失败信息])
+
+#### Scenario: PDF Reader 文件不存在
+- **WHEN** PDF Reader 解析不存在的文件路径
+- **THEN** 返回 (None, [包含错误信息的失败列表])
+
+#### Scenario: HTML Reader 文件不存在
+- **WHEN** HTML Reader 解析不存在的文件路径
+- **THEN** 返回 (None, [包含错误信息的失败列表])
+
+### Requirement: 空文件异常处理
+Reader 解析空文件时，MUST 返回 None 或空字符串作为内容，并包含失败信息。
+
+#### Scenario: DOCX Reader 空文件
+- **WHEN** DOCX Reader 解析没有任何内容的 DOCX 文件
+- **THEN** 返回 (None 或空字符串, [包含"空"或"无内容"的失败信息])
+
+#### Scenario: PDF Reader 空文件
+- **WHEN** PDF Reader 解析空白 PDF 文件
+- **THEN** 返回 (None 或空字符串, [包含错误信息的失败列表])
+
+### Requirement: 损坏文件异常处理
+Reader 解析损坏的文件时，MUST 返回 None 作为内容和包含解析失败原因的失败列表。
+
+#### Scenario: DOCX Reader 损坏文件
+- **WHEN** DOCX Reader 解析文件头被破坏的 DOCX 文件
+- **THEN** 返回 (None, [包含"解析失败"或"损坏"的失败信息])
+
+#### Scenario: PDF Reader 损坏文件
+- **WHEN** PDF Reader 解析结构损坏的 PDF 文件
+- **THEN** 返回 (None, [包含"解析失败"的失败信息])
+
+#### Scenario: 损坏文件创建方式
+- **WHEN** 测试需要损坏文件
+- **THEN** 创建正常文件后以二进制方式破坏部分内容（如覆盖文件头）
+
+### Requirement: 编码问题异常处理
+Reader 解析包含编码问题的文件时，MUST 能正确处理或返回明确的错误信息。
+
+#### Scenario: HTML Reader 编码声明与实际不符
+- **WHEN** HTML 文件声明的编码与实际内容编码不一致
+- **THEN** Reader 能够检测并正确解析，或返回明确的编码错误信息
+
+#### Scenario: HTML Reader 处理 GBK 编码
+- **WHEN** HTML 文件使用 GBK 编码
+- **THEN** Reader 能够正确解析中文内容
+
+#### Scenario: HTML Reader 处理 UTF-8 BOM
+- **WHEN** HTML 文件包含 UTF-8 BOM 标记
+- **THEN** Reader 能够正确解析
+
+### Requirement: 异常测试跟随功能测试
+异常场景测试 MUST 与对应的功能测试放在同一个测试类中，不单独建立测试类。
+
+#### Scenario: 文件不存在测试在 Parse 类中
+- **WHEN** 查看 Reader 的测试文件
+- **THEN** `test_file_not_exists` 位于 `TestXxxReaderParse` 类中
+
+#### Scenario: 空文件测试在 Parse 类中
+- **WHEN** 查看 Reader 的测试文件
+- **THEN** `test_empty_file` 位于 `TestXxxReaderParse` 类中
+
+#### Scenario: 损坏文件测试在 Parse 类中
+- **WHEN** 查看 Reader 的测试文件
+- **THEN** `test_corrupted_file` 位于 `TestXxxReaderParse` 类中
+
+#### Scenario: 特殊字符测试在 Parse 类中
+- **WHEN** 查看 Reader 的测试文件
+- **THEN** `test_special_chars` 位于 `TestXxxReaderParse` 类中
+
+### Requirement: CLI 异常处理
+CLI 遇到错误时，MUST 输出清晰的错误信息并以非零状态退出。
+
+#### Scenario: CLI 文件不存在
+- **WHEN** 用户执行 CLI 指定不存在的文件
+- **THEN** 程序输出错误信息并以状态码 1 退出
+
+#### Scenario: CLI 不支持的文件类型
+- **WHEN** 用户执行 CLI 指定不支持的文件类型
+- **THEN** 程序输出"未找到支持的 reader"错误信息
+
+#### Scenario: CLI 所有解析失败
+- **WHEN** 所有 Reader 解析均失败
+- **THEN** 程序输出"所有解析方法均失败"并列出各 Reader 的失败原因
+
+#### Scenario: CLI 无效的正则表达式
+- **WHEN** 用户使用 `-s` 选项提供无效的正则表达式
+- **THEN** 程序输出"正则表达式无效"错误信息
+
+#### Scenario: CLI 标题不存在
+- **WHEN** 用户使用 `-tc` 选项指定不存在的标题
+- **THEN** 程序输出"未找到标题"错误信息
+
+### Requirement: 自定义异常使用
+代码中定义的自定义异常 MUST 在适当场景中被抛出和捕获。
+
+#### Scenario: FileDetectionError 抛出
+- **WHEN** 输入路径为空或无法检测文件类型
+- **THEN** 抛出 FileDetectionError 异常
+
+#### Scenario: ReaderNotFoundError 抛出
+- **WHEN** 没有找到支持该格式的 Reader
+- **THEN** 抛出 ReaderNotFoundError 异常
+
+#### Scenario: ParseError 抛出
+- **WHEN** 文件解析过程中发生错误
+- **THEN** Reader 可以在内部捕获异常并返回失败信息
+
+#### Scenario: DownloadError 抛出
+- **WHEN** HTML 下载器下载 URL 内容失败
+- **THEN** 抛出 DownloadError 异常（或返回失败信息）
--- a/openspec/specs/reader-testing/spec.md
+++ b/openspec/specs/reader-testing/spec.md
@@ -0,0 +1,119 @@
+# Reader Testing Specification
+
+## Purpose
+
+定义 Reader 实现的测试规范,包括 supports 方法验证、parse 方法测试、特殊字符处理、多 Reader 一致性等。
+
+## Requirements
+
+### Requirement: Reader supports 方法验证
+每个 Reader MUST 实现 `supports(file_path: str) -> bool` 方法，正确判断是否支持给定输入。
+
+#### Scenario: DOCX Reader 识别标准扩展名
+- **WHEN** 调用 DOCX Reader 的 `supports("file.docx")`
+- **THEN** 返回 True
+
+#### Scenario: DOCX Reader 识别大写扩展名
+- **WHEN** 调用 DOCX Reader 的 `supports("FILE.DOCX")`
+- **THEN** 返回 True
+
+#### Scenario: DOCX Reader 识别 .doc 扩展名
+- **WHEN** 调用 DOCX Reader 的 `supports("file.doc")`
+- **THEN** 返回 True
+
+#### Scenario: DOCX Reader 拒绝不支持格式
+- **WHEN** 调用 DOCX Reader 的 `supports("file.pdf")`
+- **THEN** 返回 False
+
+#### Scenario: DOCX Reader 支持 URL
+- **WHEN** 调用 DOCX Reader 的 `supports("http://example.com/file.docx")`
+- **THEN** 返回 True
+
+#### Scenario: PDF Reader 识别 PDF 文件
+- **WHEN** 调用 PDF Reader 的 `supports("file.pdf")`
+- **THEN** 返回 True
+
+#### Scenario: HTML Reader 识别 HTML 文件
+- **WHEN** 调用 HTML Reader 的 `supports("file.html")`
+- **THEN** 返回 True
+
+### Requirement: Reader parse 方法正常解析
+每个 Reader MUST 实现 `parse(file_path: str) -> Tuple[Optional[str], List[str]]` 方法，成功解析时返回 Markdown 内容和空失败列表。
+
+#### Scenario: DOCX Reader 解析包含段落
+- **WHEN** DOCX Reader 解析包含段落的文件
+- **THEN** 返回的 Markdown 内容包含段落文字
+- **AND** 失败列表为空
+
+#### Scenario: DOCX Reader 解析包含标题
+- **WHEN** DOCX Reader 解析包含标题的文件
+- **THEN** 返回的 Markdown 内容包含 `# ` 标记的标题
+
+#### Scenario: DOCX Reader 解析包含表格
+- **WHEN** DOCX Reader 解析包含表格的文件
+- **THEN** 返回的 Markdown 内容包含表格中的关键文字
+
+#### Scenario: DOCX Reader 解析包含列表
+- **WHEN** DOCX Reader 解析包含列表的文件
+- **THEN** 返回的 Markdown 内容包含列表项文字
+
+#### Scenario: PDF Reader 解析基本内容
+- **WHEN** PDF Reader 解析包含文字的 PDF
+- **THEN** 返回的 Markdown 内容包含关键文字
+
+#### Scenario: HTML Reader 解析网页内容
+- **WHEN** HTML Reader 解析包含内容的 HTML 文件
+- **THEN** 返回的 Markdown 内容包含网页关键文字
+
+### Requirement: Reader 解析结果核心文字一致性
+同一文件使用不同 Reader 解析时，MUST 保持核心文字内容一致（样式和格式可以不同）。
+
+#### Scenario: DOCX 多 Reader 一致性
+- **WHEN** 同一 DOCX 文件被 python-docx、markitdown、docling 等 Reader 解析
+- **THEN** 所有输出的 Markdown 都包含相同的核心文字内容
+
+#### Scenario: PDF 多 Reader 一致性
+- **WHEN** 同一 PDF 文件被 pypdf、markitdown、docling 等 Reader 解析
+- **THEN** 所有输出的 Markdown 都包含相同的核心文字内容
+
+### Requirement: Reader 处理特殊字符
+Reader MUST 正确处理包含特殊字符的内容。
+
+#### Scenario: 处理中文字符
+- **WHEN** 文件包含中文内容
+- **THEN** 解析后的 Markdown 正确包含中文
+
+#### Scenario: 处理 Emoji 表情
+- **WHEN** 文件包含 Emoji（如 😀🎉）
+- **THEN** 解析后的 Markdown 正确包含 Emoji
+
+#### Scenario: 处理特殊符号
+- **WHEN** 文件包含特殊符号（©®™°±）
+- **THEN** 解析后的 Markdown 正确包含这些符号
+
+#### Scenario: 处理 RTL 文本
+- **WHEN** 文件包含阿拉伯文等 RTL 文本
+- **THEN** 解析后的 Markdown 正确包含 RTL 文本
+
+#### Scenario: 处理混合文本
+- **WHEN** 文件包含混合内容（如 "Hello你好🎉"）
+- **THEN** 解析后的 Markdown 正确包含混合内容
+
+#### Scenario: 处理零宽字符
+- **WHEN** 文件包含零宽字符（\u200b\u200c\u200d）
+- **THEN** 解析后的 Markdown 正确处理这些字符
+
+#### Scenario: 处理超长文本
+- **WHEN** 文件包含超长文本（如 100000 个字符）
+- **THEN** Reader 能够成功解析
+
+### Requirement: Reader 独立测试
+每个 Reader 实现 MUST 有独立的测试文件，不使用参数化测试。
+
+#### Scenario: 每个 DOCX Reader 有独立测试
+- **WHEN** 查看 test_readers/test_docx/ 目录
+- **THEN** 存在 test_python_docx.py、test_markitdown.py、test_docling.py 等独立文件
+
+#### Scenario: 每个 PDF Reader 有独立测试
+- **WHEN** 查看 test_readers/test_pdf/ 目录
+- **THEN** 存在 test_pypdf.py、test_markitdown.py、test_docling.py 等独立文件
--- a/openspec/specs/test-fixtures/spec.md
+++ b/openspec/specs/test-fixtures/spec.md
@@ -0,0 +1,108 @@
+# Test Fixtures Specification
+
+## Purpose
+
+定义测试 fixtures 的规范,包括临时文件创建、自动清理、fixture 组织结构等。
+
+## Requirements
+
+### Requirement: 临时文件自动清理
+测试使用的临时文件 MUST 在测试完成后自动清理，使用 pytest 的 tmp_path fixture。
+
+#### Scenario: 测试完成后临时文件被删除
+- **WHEN** 测试使用 tmp_path 创建临时文件
+- **THEN** 测试结束后临时文件自动删除
+
+#### Scenario: 测试失败时可保留文件
+- **WHEN** 使用 `--tmp-path-retention-count` 参数运行测试
+- **THEN** 失败测试的临时文件被保留用于调试
+
+### Requirement: 临时文件独立创建
+每个测试 MUST 独立创建自己的临时文件，不共享文件，保证测试隔离。
+
+#### Scenario: 每个测试独立创建文件
+- **WHEN** 多个测试使用相同 fixture
+- **THEN** 每个测试获得独立的临时文件实例
+
+#### Scenario: 测试间无文件共享
+- **WHEN** 测试 A 创建并修改临时文件
+- **THEN** 测试 B 的临时文件不受影响
+
+### Requirement: 全局 conftest fixtures
+tests/conftest.py MUST 提供全局可用的 fixtures。
+
+#### Scenario: 提供 all_readers fixture
+- **WHEN** 测试需要所有 Reader 实例
+- **THEN** 可以使用 `all_readers` fixture 获取完整的 Reader 列表
+
+### Requirement: Reader 专用 fixtures
+tests/test_readers/conftest.py MUST 提供 Reader 测试专用的 fixtures。
+
+#### Scenario: 提供 temp_docx fixture
+- **WHEN** 测试需要临时 DOCX 文件
+- **THEN** 可以使用 `temp_docx` fixture 创建临时 DOCX 文件
+- **AND** fixture 接受参数（如 paragraphs、table_data）自定义内容
+
+#### Scenario: 提供 temp_pdf fixture
+- **WHEN** 测试需要临时 PDF 文件
+- **THEN** 可以使用 `temp_pdf` fixture 创建临时 PDF 文件
+
+#### Scenario: 提供 temp_html fixture
+- **WHEN** 测试需要临时 HTML 文件
+- **THEN** 可以使用 `temp_html` fixture 创建临时 HTML 文件
+
+#### Scenario: 提供 temp_pptx fixture
+- **WHEN** 测试需要临时 PPTX 文件
+- **THEN** 可以使用 `temp_pptx` fixture 创建临时 PPTX 文件
+
+#### Scenario: 提供 temp_xlsx fixture
+- **WHEN** 测试需要临时 XLSX 文件
+- **THEN** 可以使用 `temp_xlsx` fixture 创建临时 XLSX 文件
+
+### Requirement: CLI 专用 fixtures
+tests/test_cli/conftest.py MUST 提供 CLI 测试专用的 fixtures。
+
+#### Scenario: 提供 cli_runner fixture
+- **WHEN** 测试需要运行 CLI
+- **THEN** 可以使用 `cli_runner` fixture 调用 main() 函数并捕获输出
+- **AND** 返回 (stdout, stderr) 元组
+
+#### Scenario: 提供 temp_test_file fixture
+- **WHEN** CLI 测试需要临时测试文件
+- **THEN** 可以使用 `temp_test_file` fixture 根据格式类型创建对应文件
+
+### Requirement: Fixture 返回文件路径
+所有创建临时文件的 fixtures MUST 返回文件路径字符串，而非 Path 对象或文件对象。
+
+#### Scenario: temp_docx 返回路径字符串
+- **WHEN** 调用 `temp_docx(paragraphs=["test"])`
+- **THEN** 返回临时文件的路径字符串（如 "/tmp/pytest-of-user/test.docx"）
+
+### Requirement: DOCX 文件创建能力
+temp_docx fixture MUST 支持创建包含段落、标题、表格、列表的 DOCX 文件。
+
+#### Scenario: 创建包含段落的 DOCX
+- **WHEN** 调用 `temp_docx(paragraphs=["第一段", "第二段"])`
+- **THEN** 创建包含指定段落的 DOCX 文件
+
+#### Scenario: 创建包含表格的 DOCX
+- **WHEN** 调用 `temp_docx(table_data=[["A1", "B1"], ["A2", "B2"]])`
+- **THEN** 创建包含 2x2 表格的 DOCX 文件
+
+#### Scenario: 创建包含混合内容的 DOCX
+- **WHEN** 调用 `temp_docx(paragraphs=["标题"], table_data=[["A", "B"]])`
+- **THEN** 创建包含段落和表格的 DOCX 文件
+
+### Requirement: PDF 文件创建能力
+temp_pdf fixture MUST 支持创建包含基本文本的 PDF 文件。
+
+#### Scenario: 创建包含文本的 PDF
+- **WHEN** 调用 `temp_pdf(text="测试内容")`
+- **THEN** 创建包含指定文本的 PDF 文件
+
+### Requirement: HTML 文件创建能力
+temp_html fixture MUST 支持创建包含各种元素的 HTML 文件。
+
+#### Scenario: 创建包含标题和段落的 HTML
+- **WHEN** 调用 `temp_html(content="<h1>标题</h1><p>段落</p>")`
+- **THEN** 创建包含指定内容的 HTML 文件