EverOS 测试规范实战指南：目录镜像、pytest-asyncio 与 80% 覆盖率门禁

EverOS 测试规范实战指南目录镜像、pytest-asyncio 与 80% 覆盖率门禁【免费下载链接】EverOSOne portable memory layer for every AI agent: local-first, Markdown-native, user-owned, and self-evolving across apps, tools, and workflows.项目地址: https://gitcode.com/gh_mirrors/ev/EverOS本指南基于 EverOS 仓库.claude/rules/testing.md测试规则结合仓库中真实的Makefile、pyproject.toml、conftest.py与测试用例系统讲解 EverOS 的测试分层结构、异步测试写法、Marker 分级策略、fixture 隔离机制与覆盖率门禁帮助你在提交代码前一次性通过本地与 CI 的双重检验。EverOS 是一个面向 AI Agent 的本地优先、Markdown 原生的记忆层框架见 README.md其测试体系直接映射了源码的三层架构。.claude/rules/testing.md是该仓库对 AI 编码助手与人类开发者统一的测试约束文件本文以它为骨架深入仓库源码与测试用例给出可复现、可验证的完整实践。一、测试金字塔与目录镜像约定规则原文要求Tests mirror the source layout即测试目录与源码目录逐包镜像tests/unit/test_layer/... # 单元测试镜像 src/everos/ tests/integration/... # 集成测试 tests/e2e/... # 端到端测试tests/unit/镜像src/everos/包结构源码在src/everos/memory/cascade/worker.py测试就在tests/unit/test_memory/test_cascade/test_worker.py源码src/everos/component/embedding/对应tests/unit/test_component/test_embedding/。Put a test next to where its subject lives in the mirror——测试与被测对象在镜像中一一对应查找测试时无需猜测路径。从仓库实际布局看tests/tests/unit/下与src/everos/顶层包一一对应有test_component/、test_config/、test_core/、test_entrypoints/、test_infra/、test_memory/、test_service/等目录而tests/integration/下则是跨层场景如test_memorize_integration.py驱动service.memorize.memorize()全链路、tests/e2e/下是完整应用生命周期测试如test_add_flush_agent_pipeline_e2e.py。三层金字塔从单模块快速验证到全链路真实依赖层层递进。二、pytest-asyncio auto 模式无需装饰器的异步测试EverOS 的核心链路记忆写入、Cascade 扫描、OME 调度几乎全部是异步代码因此规则明确约定pytest-asyncio处于auto模式写法直接写async def test_*无需任何pytest.mark.asyncio标记。配置依据见 pyproject.toml 中的[tool.pytest.ini_options]asyncio_mode auto。仓库中大量用例印证了这一点例如 tests/unit/test_memory/test_events.py 中def test_user_pipeline_started_topic_is_module_qualified()这类同步断言以及 tests/unit/test_memory/test_cascade/test_worker.py 中大量直接async def test_...的用例。配套的 pytest 基础配置同样在 pyproject.toml[tool.pytest.ini_options] testpaths [tests] python_files [test_*.py] python_functions [test_*] asyncio_mode auto addopts -v --tbshort -m not slow and not live_llm要点说明addopts默认排除了slow与live_llm两组标记普通pytest/make test默认只跑快速且无外部凭据的用例filterwarnings [error, ...]将警告升级为错误强制依赖库的已知无害告警必须显式ignore如 jieba 0.42.1 的转义序列警告、aiosqlite 生命周期警告保证套件在严格模式下依然绿。三、Marker 分级slow 与 live_llm规则规定两个自定义标记均在 pyproject.toml 中登记标记含义默认运行手动运行pytest.mark.slow耗时 ≥ ~10 秒的用例排除pytest -m slowpytest.mark.live_llm需要真实 LLM/embedder/reranker 凭据消耗 token排除pytest -m live_llm核心纪律单元测试必须快速且零凭据任何需要真实外部服务的用例要么打上标记要么下沉到integration/e2e目录。例如 tests/e2e/test_search_endpoint_e2e.py 中 21 处标记组合slowlive_llm这类用例依赖 tests/e2e/conftest.py 在导入期load_dotenv读取真实.env凭据——与单元测试的无凭据原则形成互补。四、Fixtures 与隔离根 conftest 的缓存重置规则指出Shared fixtures live in the nearestconftest.py. The root conftest resets module caches (settings/logging/datetime) per test. 仓库 tests/conftest.py 用一组autouseTrue的 fixture 实现了全局隔离_isolate_everos_root通过monkeypatch.setenv(EVEROS_ROOT, str(tmp_path))将每个测试钉在独立的临时内存根上防止测试误读开发者本机的everos.toml_reset_settings_cache清空load_settings.cache_clear()与dt_module._display_tz.cache_clear()生产热路径用functools.cache缓存并structlog.reset_defaults()避免日志配置跨用例泄漏_reset_embedding_capability_singleton/_reset_rerank_capability_singleton/_reset_multimodal_capability_singleton将三个 capability 惰性单例预置为availableFalse保证套件密闭性hermetic不随宿主环境变化而翻转测试结果。这解释了规则中rely on that for isolation rather than mutating globals的含义——不要在自己测试里改全局状态交给根 conftest 的自动 fixture 处理即可。跨套件共享的数据 fixture如 LoCoMolong_conversation也按最近 conftest原则放在根 tests/conftest.pyscopesession因为tests/e2e/与tests/integration/search/都需要它而 conftest 只能向子目录级联。五、模块 Docstring钉住测试契约每个测试文件顶部都必须有模块级 docstring说明该文件钉住了什么契约contract。这是规则明确要求、仓库处处落实的风格tests/unit/test_memory/test_cascade/test_worker.py 开头声明Tests forCascadeWorkerretry classification optimize scheduler随后列出五个分支行为重试上限、非服务错误立即失败、成功标记、未知 kind 等tests/integration/test_memorize_integration.py 声明用FakeLLMClient驱动service.memorize.memorize()全链路且明确OME strategies 通过mock_aextract静默本文件聚焦同步边界 管线 md 路径tests/e2e/conftest.py 的 docstring 详述了各 fixture 的职责与命名约定如本文件不定义cascade_runtime避免与test_cascade_integration.py的本地 fixture 撞名。写新测试时第一行就回答这个文件钉住什么行为审阅者与后续维护者能立刻判断测试的边界与意图。六、覆盖率门禁make cov 与 80% 底线规则要求make covenforces 80% (--cov-fail-under80)。对应的 Makefile 目标在 Makefilecov: uv run pytest tests/unit tests/integration --covsrc/everos --cov-reportterm-missing --cov-branch --cov-fail-under80注意细节同时跑 unit integration注释说明当前 unit-only 覆盖率约 87%unitintegration 约 91%80% 阈值保留约 10 个百分点余量供正常波动分支覆盖率--cov-branch开启分支覆盖pyproject.toml 的[tool.coverage.run]设branch true、omit [**/__init__.py][tool.coverage.report]设fail_under 80且show_missing true同时排除if TYPE_CHECKING:、abstractmethod、pragma: no cover行。因此新代码不应把覆盖率拉到门禁以下是硬约束——CI 与本地同一套阈值本地红了 CI 必红。七、提交前检查清单make test / make integration / ci规则的收尾要求Runmake test(unit) andmake integrationbefore pushing; both run in CI. 对应的目标test: uv run pytest tests/unit -v integration: uv run pytest tests/integration -v ci: lint test integration package完整 CI 编排见 Makefile 与 Makefile 的lintruff 检查 格式化 import-linter 资源/文件大小/命名/时区纪律扫描 OpenAPI 漂移校验。推荐的最小提交前流程make format统一格式make test跑单元测试默认已排除 slow/live_llm快速make integration跑跨层集成测试make cov确认覆盖率不低于 80%有把握时直接make ci复刻 CI 全流程lint test integration package。其中make integration的幂等性、并发安全等行为在 tests/integration/ 中有大量专项用例覆盖例如 test_memorize_concurrent_session_lock.py会话锁、test_memorize_window_segmentation.py窗口切分与单元层形成互补。总结EverOS 的测试体系可以用一句话概括目录镜像定位、auto 异步免装饰、双 marker 分级、autouse fixture 全局隔离、docstring 钉契约、80% 分支覆盖率兜底、本地与 CI 同一条命令链。无论你是为 EverOS 贡献新特性、编写新的记忆策略还是仅仅想跑通这套测试来理解框架行为遵循.claude/rules/testing.md都能让你的改动稳定、快速、可审计地合入。快速参考规则文件.claude/rules/testing.mdpytest 配置与 marker 定义pyproject.toml测试命令与覆盖率门禁Makefile根级 fixture隔离与共享数据tests/conftest.py单元测试示例docstring asynctests/unit/test_memory/test_cascade/test_worker.py集成测试示例FakeLLM 全链路tests/integration/test_memorize_integration.pye2e 依赖与 marker 组合tests/e2e/conftest.py、tests/e2e/test_search_endpoint_e2e.py【免费下载链接】EverOSOne portable memory layer for every AI agent: local-first, Markdown-native, user-owned, and self-evolving across apps, tools, and workflows.项目地址: https://gitcode.com/gh_mirrors/ev/EverOS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考