lanyuanxiaoyao/lyxy-document
1
0
Fork 0
Code Releases Activity
Files
89ffc88082b746ec204b1b451fd99faa080ecafd
lyxy-document/openspec/specs/test-fixtures/spec.md
lanyuanxiaoyao 89ffc88082 fix: 优化配置、修复测试和 temp_pdf 中文字体支持 
- 优化 config.py，为所有依赖添加版本号，为所有文件类型添加 Darwin-x86_64 配置
- 修改 run_tests.py，添加平台相关 TEST_FIXTURE_DEPENDENCIES，简化 cli 和 all 测试逻辑
- 修复 tests/conftest.py 中 temp_pdf 的中文字体支持，使用 macOS 系统字体
- 更新 tests/test_core/test_advice_generator.py 以适应 Python 3.12 的默认配置
- 更新 openspec 相关规格文档
2026-03-17 10:50:48 +08:00

7.7 KiB
Raw Blame History

Test Fixtures Specification

Purpose

定义测试 fixtures 的规范,包括临时文件创建、自动清理、fixture 组织结构等。

Requirements

Requirement: 测试运行器包含 fixtures 依赖

run_tests.py 必须定义 TEST_FIXTURE_DEPENDENCIES 常量，包含创建临时测试文件所需的所有依赖。

Scenario: TEST_FIXTURE_DEPENDENCIES 定义存在

  • WHEN 查看 run_tests.py
  • THEN 存在 TEST_FIXTURE_DEPENDENCIES 常量
  • AND 包含 python-docx（用于创建临时 DOCX）
  • AND 包含 reportlab（用于创建临时 PDF）
  • AND 包含 pandas（用于创建临时 XLSX）
  • AND 包含 openpyxl（pandas 写 XLSX 需要）
  • AND 包含 python-pptx（用于创建临时 PPTX）

Scenario: fixtures 依赖与文件类型依赖合并

  • WHEN 运行任何类型的测试
  • THEN TEST_FIXTURE_DEPENDENCIES 中的依赖自动合并到 uv run --with 参数中
  • AND 去重处理，避免重复添加

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 文件

Scenario: 提供 doc 静态文件 fixtures

  • WHEN 测试需要 doc 静态测试文件
  • THEN 可以使用 simple_doc_path、with_headings_doc_path、with_table_doc_path

Scenario: 提供 xls 静态文件 fixtures

  • WHEN 测试需要 xls 静态测试文件
  • THEN 可以使用 simple_xls_path、multiple_sheets_xls_path、with_formulas_xls_path

Scenario: 提供 ppt 静态文件 fixtures

  • WHEN 测试需要 ppt 静态测试文件
  • THEN 可以使用 simple_ppt_path、multiple_slides_ppt_path、with_images_ppt_path

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 文件

Requirement: 静态测试文件目录结构

项目 MUST 在 tests/test_readers/fixtures/ 下按格式类型组织静态测试文件。

Scenario: doc 静态文件目录

  • WHEN 查看 tests/test_readers/fixtures/doc/
  • THEN 目录存在且包含 .doc 静态测试文件

Scenario: xls 静态文件目录

  • WHEN 查看 tests/test_readers/fixtures/xls/
  • THEN 目录存在且包含 .xls 静态测试文件

Scenario: ppt 静态文件目录

  • WHEN 查看 tests/test_readers/fixtures/ppt/
  • THEN 目录存在且包含 .ppt 静态测试文件

Requirement: fixtures 目录所有文件纳入 Git LFS

tests/test_readers/fixtures/ 目录下的 ALL 文件 MUST 纳入 Git LFS 管理。

Scenario: .gitattributes 配置正确

  • WHEN 查看 .gitattributes
  • THEN 包含 tests/test_readers/fixtures/**/* 的 LFS 配置，匹配该目录下所有文件

Requirement: fixtures 目录仅存放静态文件

tests/test_readers/fixtures/ 目录 MUST 仅用于存放预先准备的静态测试文件，禁止在测试中向该目录动态生成临时文件。

Scenario: 不向 fixtures 目录写入临时文件

  • WHEN 测试运行时
  • THEN 不会在 tests/test_readers/fixtures/ 下创建或修改文件
  • AND 临时文件使用 pytest 的 tmp_path 在其他位置创建

Requirement: 静态测试文件 Fixture

tests/test_readers/conftest.py MUST 提供访问静态测试文件的 fixtures。

Scenario: 提供目录路径 fixture

  • WHEN 测试需要访问静态文件目录
  • THEN 可以使用 doc_fixture_path、xls_fixture_path、ppt_fixture_path 获取对应目录路径

Scenario: 提供单个文件 fixture

  • WHEN 测试需要访问特定静态文件
  • THEN 可以使用 simple_doc_path、with_headings_doc_path 等便捷 fixture
  • AND 文件不存在时自动 pytest.skip

Requirement: fixtures 使用规范写入开发文档

fixtures 目录的使用规范 MUST 写入 README.md 开发文档。

Scenario: README 包含 fixtures 规范

  • WHEN 查看 README.md
  • THEN 包含 fixtures 目录的用途说明
  • AND 包含静态文件与临时文件的区别说明
  • AND 包含 Git LFS 配置说明
View Git Blame Copy Permalink