HeurAMS/tests

HeurAMS 测试指南

概览

HeurAMS 使用 pytest 作为测试框架, 测试文件统一存放在项目根目录的 tests/ 目录下。

• 测试框架: pytest >= 8.0.0
• 覆盖率: pytest-cov >= 6.0.0
• 配置: pyproject.toml 中的 [tool.pytest.ini_options]
• 所有测试纯单元测试 — 不涉及 I/O、网络或真实文件系统依赖

运行测试

# 从项目根目录运行全部测试
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 验证

示例结构:

"""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:

uv sync --all-extras     # 安装开发依赖
uv run pytest            # 运行测试