## Context

yaml2pptx 项目目前没有测试代码。项目采用模块化架构，包含以下模块：
- core/: 核心领域模型（elements、presentation、template）
- loaders/: YAML 加载层
- validators/: 验证层（geometry、resource、result、validator）
- renderers/: PPTX 和 HTML 渲染
- preview/: Flask 预览服务器

约束条件：
1. 必须使用 pytest 框架
2. PPTX 文件需要实际生成和验证（Level 2：文件结构、元素数量、内容匹配、位置范围）
3. Preview 测试不启动真实服务器
4. 临时文件使用系统临时目录并自动清理

## Goals / Non-Goals

**Goals:**
- 建立全面的测试体系，覆盖单元、集成、端到端三个层级
- 确保核心功能的正确性和稳定性
- 为未来重构提供安全网
- 测试代码结构清晰、易于维护

**Non-Goals:**
- 性能测试
- UI/视觉对比测试（像素级）
- 100% 代码覆盖率（追求合理覆盖而非完美数字）

## Decisions

### D1: 测试目录结构

采用三层测试结构：
```
tests/
├── unit/          # 单元测试 - 测试独立函数/类
├── integration/   # 集成测试 - 测试模块间协作
├── e2e/           # 端到端测试 - 测试完整用户场景
└── fixtures/      # 测试数据
```

**理由**：清晰的分层便于理解和维护，符合测试最佳实践。

### D2: Fixtures 策略

使用 pytest 的 conftest.py 集中管理共享 fixtures：
- `temp_dir`: 临时目录（使用 pytest 内置 tmp_path）
- `sample_yaml`: 最小可用 YAML 文件
- `sample_image`: 测试图片（使用 Pillow 创建）
- `sample_template`: 测试模板文件和目录
- `pptx_validator`: PPTX 验证工具实例

**理由**：集中管理避免重复，便于维护。

### D3: PPTX 验证方案

创建专门的 PptxFileValidator 工具类（Level 2 验证）：
- 文件级：存在、可打开
- 幻灯片级：数量、尺寸
- 元素级：类型、数量、内容、位置（容差 0.1 英寸）

**理由**：Level 2 平衡了覆盖度和复杂度，无需图像对比库。

### D4: Preview 测试方案

不启动真实 Flask 服务器，测试以下内容：
- `generate_preview_html()` 函数的 HTML 生成
- `create_flask_app()` 的路由配置
- `YAMLChangeHandler` 的文件变化检测（Mock watchdog）

**理由**：避免异步服务器的复杂性，测试核心逻辑。

### D5: Mock 边界

**需要 Mock:**
- `webbrowser.open()`（避免打开浏览器）
- `watchdog.Observer`（避免文件监听）
- CLI 的 `sys.argv`（使用 CliRunner）

**不 Mock:**
- `python-pptx`（实际生成和验证）
- 文件系统（使用临时目录）
- `yaml.safe_load()`（实际解析）

**理由**：核心生成逻辑必须真实测试，外部依赖可以 Mock。

### D6: 测试数据组织

```
tests/fixtures/
├── yaml_samples/
│   ├── minimal.yaml          # 最小示例
│   ├── full_features.yaml    # 包含所有功能
│   ├── edge_cases/           # 边界情况
│   └── invalid/              # 无效样本（测试错误处理）
├── templates/                # 测试模板
└── images/                   # 测试图片
```

**理由**：测试数据与代码分离，便于复用和维护。

### D7: 临时文件清理

方案：使用 pytest 内置 `tmp_path` fixture，自动管理临时目录。

**理由**：pytest 原生支持，无需手动清理代码。

## Risks / Trade-offs

### Risk 1: PPTX 验证可能不够精确
**描述**：Level 2 验证不检查像素级渲染效果。

**缓解措施**：手动验证关键用例的视觉效果，自动化测试覆盖结构正确性。

### Risk 2: 测试运行时间较长
**描述**：实际生成 PPTX 文件会增加测试时间。

**缓解措施**：不考虑时间限制，优先保证测试覆盖度。

### Risk 3: 全局变量影响测试
**描述**：preview/server.py 使用全局变量（app、change_queue 等）。

**缓解措施**：在测试中显式重置全局状态，或重构代码减少全局变量依赖。

### Risk 4: CLI 测试复杂性
**描述**：yaml2pptx.py 是单体脚本，难以单独导入测试。

**缓解措施**：使用 `subprocess` 运行命令并检查输出/退出码。

## Migration Plan

### 步骤

1. **配置测试环境**
   - 更新 pyproject.toml 添加测试依赖
   - 创建 tests/conftest.py

2. **实现测试基础设施**
   - 创建 tests/conftest_pptx.py（PPTX 验证工具）
   - 创建 tests/fixtures/ 目录和测试数据

3. **实现单元测试**
   - test_elements.py
   - test_template.py
   - test_validators/*.py
   - test_loaders/test_yaml_loader.py
   - test_utils.py

4. **实现集成测试**
   - test_presentation.py
   - test_rendering_flow.py
   - test_validation_flow.py

5. **实现端到端测试**
   - test_convert_cmd.py
   - test_check_cmd.py
   - test_preview_cmd.py

6. **更新文档**
   - README.md 添加测试运行说明
   - README_DEV.md 添加测试开发指南

### 回滚策略

如果测试引入问题：
1. 测试代码位于独立目录，不影响生产代码
2. 可以通过删除 tests/ 目录完全移除
3. pyproject.toml 的测试依赖是可选的

## Open Questions

无。所有技术决策已明确。