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

编写新测试

在 tests/ 下创建 test_<模块名>.py 文件
文件头部加模块文档字符串
按功能划分测试类 (每个类一个测试主题)
算法相关测试使用 timer_context fixture 保证确定性
使用 deepcopy 保护共享 fixture
运行 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            # 运行测试

4.3 KiB Raw Blame History