docs: 更新文档

tests/README.md

@@ -0,0 +1,150 @@
+# HeurAMS 测试指南
+
+## 概览
+
+HeurAMS 使用 [pytest](https://docs.pytest.org/) 作为测试框架, 测试文件统一存放在项目根目录的 `tests/` 目录下。
+
+- **测试框架**: pytest >= 8.0.0
+- **覆盖率**: pytest-cov >= 6.0.0
+- **配置**: `pyproject.toml` 中的 `[tool.pytest.ini_options]`
+- **所有测试纯单元测试** — 不涉及 I/O、网络或真实文件系统依赖
+
+## 运行测试
+
+```bash
+# 从项目根目录运行全部测试
+uv run pytest
+
+# 显示详细测试名
+uv run pytest -v
+
+# 运行单个测试文件
+uv run pytest tests/test_sm2.py
+
+# 按关键词筛选
+uv run pytest -k "revisor"
+
+# 带覆盖率报告
+uv run pytest --cov=heurams
+
+# 生成 HTML 覆盖率报告
+uv run pytest --cov=heurams --cov-report=html
+```
+
+当前全部 **128 个测试** 通过 (0.2s)。
+
+## 测试套件结构
+
+所有 9 个测试文件平铺在 `tests/` 目录下:
+
+| 文件 | 用例数 | 测试对象 |
+|---|---|---|
+| `test_base_algorithm.py` | 7 | `kernel.algorithms.base.BaseAlgorithm` |
+| `test_sm2.py` | 16 | `kernel.algorithms.sm2.SM2Algorithm` |
+| `test_nsp0.py` | 9 | `kernel.algorithms.nsp0.NSP0Algorithm` |
+| `test_electron.py` | 18 | `kernel.particles.electron.Electron` |
+| `test_lict.py` | 29 | `kernel.auxiliary.lict.Lict` |
+| `test_evalizor.py` | 8 | `kernel.auxiliary.evalizor.Evalizer` |
+| `test_epath.py` | 11 | `services.epath` |
+| `test_hasher.py` | 5 | `services.hasher` |
+| `test_textproc.py` | 7 | `services.textproc` |
+
+## 共享 Fixtures (`conftest.py`)
+
+`tests/conftest.py` 提供了四个全局 fixture:
+
+- **`timer_config`** — 返回一个 `ConfigDict`, 其中计时器被覆写为确定值 (`daystamp=20000`, `timestamp=1e9`), 使算法测试不依赖系统时钟
+- **`timer_context`** — 通过 `ConfigContext` 上下文管理器在测试期间应用计时器覆写
+- **`sample_algodata_sm2`** — 一份预激活状态的 SM-2 `algodata` 字典 (deepcopy, 防止 fixture 污染)
+- **`sample_algodata_nsp0`** — 同上, 针对 NSP-0
+
+## 测试模式与约定
+
+### 组织方式
+
+- 测试全部使用 **class-based 组织** (例如 `TestSM2Revisor`, `TestElectronInit`)
+- 每个测试类聚焦一个模块的一个方面 (默认值、方法、边界情况、属性等)
+- 类名以 `Test` 开头, 方法名以 `test_` 开头
+
+### 数据隔离
+
+- 使用 `deepcopy(algodata)` 防止 fixture 突变在测试间泄漏
+- 算法测试依赖 `timer_context` fixture 以获得确定性日期/时间
+
+### 断言风格
+
+- 仅使用标准 `assert` 语句, 无第三方断言库
+- 异常测试使用 `pytest.raises()`
+
+### 自定义标记
+
+`pyproject.toml` 中定义了以下 pytest 标记 (当前尚未使用):
+
+- `slow` — 慢速测试, 可用 `-m "not slow"` 跳过
+- `integration` — 集成测试
+
+## 覆盖率现状
+
+**已有测试覆盖的模块:**
+
+- `kernel.algorithms.base` — 完整
+- `kernel.algorithms.sm2` — 完整
+- `kernel.algorithms.nsp0` — 完整
+- `kernel.particles.electron` — 完整
+- `kernel.auxiliary.lict` — 完整
+- `kernel.auxiliary.evalizor` — 完整
+- `services.epath` — 完整
+- `services.hasher` — 完整
+- `services.textproc` — 完整
+
+**尚无测试覆盖的模块 (欢迎贡献):**
+
+- `kernel.particles.atom`, `nucleon`, `orbital`
+- `kernel.reactor` (router, procession, expander)
+- `kernel.puzzles` (所有题型)
+- `kernel.algorithms.sm15m`, `kernel.algorithms.fsrs`
+- `services.config`, `services.timer`, `services.logger`, `services.audio_service`, `services.tts_service`,
+  `services.favorite_service`, `services.attic`
+- `interface/` (完整 TUI)
+- `providers/` (所有提供者后端)
+- `repolib.repo`
+
+## 编写新测试
+
+1. 在 `tests/` 下创建 `test_<模块名>.py` 文件
+2. 文件头部加模块文档字符串
+3. 按功能划分测试类 (每个类一个测试主题)
+4. 算法相关测试使用 `timer_context` fixture 保证确定性
+5. 使用 `deepcopy` 保护共享 fixture
+6. 运行 `uv run pytest tests/test_<模块名>.py -v` 验证
+
+示例结构:
+
+```python
+"""Tests for heurams.module.submodule.SomeClass"""
+
+import pytest
+from heurams.module.submodule import SomeClass
+
+
+class TestSomeClassInit:
+    def test_defaults(self):
+        ...
+
+
+class TestSomeClassMethod:
+    def test_normal_case(self):
+        ...
+
+    def test_edge_case(self):
+        ...
+```
+
+## 开发环境设置
+
+参考 [CONTRIBUTING.md](../CONTRIBUTING.md):
+
+```bash
+uv sync --all-extras     # 安装开发依赖
+uv run pytest            # 运行测试
+```