cat-shark/wov-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 为全部代码补充中文注释并加入 AGENTS 注释规范

Browse Source
This commit is contained in:
cat-shark
2026-08-13 22:09:55 +08:00
parent 77e9ac6b7e
commit ac41a9a6da
29 changed files with 472 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/test_node_manager.py
+44
View File
@@ -1,3 +1,9 @@
"""NodeManager 单元测试。
覆盖命令解析、环境变量注入、CUDA 路径处理、进程启动失败分支、实例复用、
调用错误处理、回收线程以及停止清理等真实生命周期路径。
"""
import os
import subprocess
import sys
@@ -19,6 +25,7 @@ from app.node_manager import (
from wov_sdk.models import InvokeRequest, NodeManifest
WORKSPACE = Path(__file__).resolve().parent.parent.parent
# 从真实节点仓库加载 Echo manifest，测试使用真实协议数据。
_BASE_ECHO_MANIFEST = NodeManifest.load(WORKSPACE / "wov-node-echo" / "node.manifest.json")
FIXTURES = Path(__file__).resolve().parent / "fixtures"
@@ -29,14 +36,17 @@ def db(tmp_path) -> Database:
def _register(db: Database, manifest: NodeManifest) -> None:
"""把 manifest 写入测试数据库，模拟注册节点。"""
db.upsert_node(manifest)
def echo_manifest() -> NodeManifest:
"""返回 Echo 节点 manifest 的副本，避免测试间共享可变对象。"""
return NodeManifest.from_dict(_BASE_ECHO_MANIFEST.to_dict())
def test_time_helpers() -> None:
"""验证时间工具对正常、空与非法输入的返回。"""
now = _now_iso()
assert datetime.fromisoformat(now)
assert _idle_seconds(now) < 0.1
@@ -47,6 +57,7 @@ def test_time_helpers() -> None:
def test_resolve_command_and_env(db: Database) -> None:
"""验证 python 命令解析回退与固定命令保持原样。"""
manager = NodeManager(db)
python_command = NodeManifest(
id="x",
@@ -71,6 +82,7 @@ def test_resolve_command_and_env(db: Database) -> None:
def test_resolve_command_prefers_node_venv(db: Database, tmp_path, monkeypatch) -> None:
"""验证 Windows 与 Linux 虚拟环境解释器优先级。"""
monkeypatch.setattr("app.node_manager.WORKSPACE_ROOT", tmp_path)
repo = tmp_path / "wov-node-demo"
python_exe = repo / ".venv" / "Scripts" / "python.exe"
@@ -95,6 +107,7 @@ def test_resolve_command_prefers_node_venv(db: Database, tmp_path, monkeypatch)
def test_cuda_library_dirs_finds_unix_nvidia_libs(tmp_path) -> None:
"""验证 Linux site-packages 下的 cublas/cudnn lib 目录被发现。"""
cublas = (
tmp_path / ".venv" / "lib" / "python3.12" / "site-packages" / "nvidia" / "cublas" / "lib"
)
@@ -111,6 +124,7 @@ def test_cuda_library_dirs_finds_unix_nvidia_libs(tmp_path) -> None:
def test_cuda_library_dirs_finds_windows_nvidia_bins(tmp_path) -> None:
"""验证 Windows Lib/site-packages 下的 bin 目录被发现。"""
cublas = tmp_path / ".venv" / "Lib" / "site-packages" / "nvidia" / "cublas" / "bin"
cublas.mkdir(parents=True)
@@ -120,6 +134,7 @@ def test_cuda_library_dirs_finds_windows_nvidia_bins(tmp_path) -> None:
def test_with_cuda_library_path_prepends_on_posix(monkeypatch) -> None:
"""验证 Linux 下 CUDA 目录插入 LD_LIBRARY_PATH 开头。"""
monkeypatch.setattr(os, "name", "posix")
monkeypatch.setattr(
"app.node_manager._cuda_library_dirs",
@@ -134,6 +149,7 @@ def test_with_cuda_library_path_prepends_on_posix(monkeypatch) -> None:
def test_with_cuda_library_path_uses_path_on_windows(monkeypatch) -> None:
"""验证 Windows 下 CUDA 目录插入 PATH 开头。"""
monkeypatch.setattr(os, "name", "nt")
monkeypatch.setattr(
"app.node_manager._cuda_library_dirs",
@@ -148,6 +164,7 @@ def test_with_cuda_library_path_uses_path_on_windows(monkeypatch) -> None:
def test_with_cuda_library_path_without_existing(monkeypatch) -> None:
"""验证环境变量原本不存在时直接创建。"""
monkeypatch.setattr(os, "name", "posix")
monkeypatch.setattr(
"app.node_manager._cuda_library_dirs",
@@ -160,6 +177,7 @@ def test_with_cuda_library_path_without_existing(monkeypatch) -> None:
def test_with_cuda_library_path_deduplicates(monkeypatch) -> None:
"""验证已存在的目录不会被重复追加。"""
monkeypatch.setattr(os, "name", "posix")
monkeypatch.setattr(
"app.node_manager._cuda_library_dirs",
@@ -176,6 +194,7 @@ def test_with_cuda_library_path_deduplicates(monkeypatch) -> None:
def test_with_cuda_library_path_all_present(monkeypatch) -> None:
"""验证所有目录都已存在时环境变量保持不变。"""
monkeypatch.setattr(os, "name", "posix")
monkeypatch.setattr(
"app.node_manager._cuda_library_dirs",
@@ -189,6 +208,7 @@ def test_with_cuda_library_path_all_present(monkeypatch) -> None:
def test_with_cuda_library_path_without_libs(monkeypatch) -> None:
"""验证没有任何 CUDA 库时环境变量原样返回。"""
monkeypatch.setattr("app.node_manager._cuda_library_dirs", lambda repo_dir: [])
env = _with_cuda_library_path({"LD_LIBRARY_PATH": "/usr/lib/foo"}, Path("/repo"))
@@ -197,6 +217,7 @@ def test_with_cuda_library_path_without_libs(monkeypatch) -> None:
def test_node_env_injects_cuda_library_path(db: Database, tmp_path, monkeypatch) -> None:
"""验证 _node_env 会注入 SDK、manifest 变量与 CUDA 路径。"""
monkeypatch.setattr("app.node_manager.WORKSPACE_ROOT", tmp_path)
repo = tmp_path / "wov-node-whisper"
cublas = repo / ".venv" / "lib" / "python3.12" / "site-packages" / "nvidia" / "cublas" / "lib"
@@ -219,12 +240,14 @@ def test_node_env_injects_cuda_library_path(db: Database, tmp_path, monkeypatch)
def test_acquire_unregistered(db: Database) -> None:
"""验证未注册节点无法获取实例。"""
manager = NodeManager(db)
with pytest.raises(ValueError):
manager.acquire("missing")
def test_start_missing_repo(db: Database) -> None:
"""验证 repo_dir 不存在时启动失败并记录 error。"""
manifest = echo_manifest()
manifest.repo_dir = "missing-repo"
_register(db, manifest)
@@ -235,6 +258,7 @@ def test_start_missing_repo(db: Database) -> None:
def test_start_command_not_found(db: Database) -> None:
"""验证命令不存在时启动失败并记录 error。"""
manifest = echo_manifest()
manifest.command = ["definitely-not-a-real-wov-command"]
_register(db, manifest)
@@ -245,6 +269,7 @@ def test_start_command_not_found(db: Database) -> None:
def test_start_no_ready_timeout(db: Database, monkeypatch) -> None:
"""验证超时未打印就绪行时启动失败。"""
monkeypatch.setattr("app.node_manager.NODE_READY_TIMEOUT_SECONDS", 0.2)
manifest = echo_manifest()
manifest.command = ["python", "-c", "import time; time.sleep(0.5)"]
@@ -256,6 +281,7 @@ def test_start_no_ready_timeout(db: Database, monkeypatch) -> None:
def test_start_bad_ready_line(db: Database) -> None:
"""验证就绪行缺少端口时启动失败。"""
manifest = echo_manifest()
manifest.command = ["python", "-u", str(FIXTURES / "bad_ready_node.py")]
_register(db, manifest)
@@ -266,6 +292,7 @@ def test_start_bad_ready_line(db: Database) -> None:
def test_start_health_check_failure(db: Database) -> None:
"""验证 /health 返回错误状态码时启动失败。"""
manifest = echo_manifest()
manifest.command = ["python", "-u", str(FIXTURES / "bad_node.py")]
_register(db, manifest)
@@ -276,6 +303,7 @@ def test_start_health_check_failure(db: Database) -> None:
def test_start_health_check_bad_status(db: Database) -> None:
"""验证 /health 返回非 200 状态码时启动失败。"""
manifest = echo_manifest()
manifest.command = ["python", "-u", str(FIXTURES / "bad_status_node.py")]
_register(db, manifest)
@@ -286,6 +314,7 @@ def test_start_health_check_bad_status(db: Database) -> None:
def test_stderr_is_captured(db: Database) -> None:
"""验证节点 stderr 会被缓存到运行时供诊断。"""
manifest = echo_manifest()
manifest.command = ["python", "-u", str(FIXTURES / "stderr_node.py")]
_register(db, manifest)
@@ -301,6 +330,7 @@ def test_stderr_is_captured(db: Database) -> None:
def test_acquire_reuses_ready_instance(db: Database) -> None:
"""验证释放后的就绪实例会被再次复用。"""
_register(db, echo_manifest())
manager = NodeManager(db)
try:
@@ -315,6 +345,7 @@ def test_acquire_reuses_ready_instance(db: Database) -> None:
def test_invoke_success(db: Database, tmp_path) -> None:
"""验证真实节点调用返回完成状态与输出。"""
_register(db, echo_manifest())
manager = NodeManager(db)
try:
@@ -334,6 +365,7 @@ def test_invoke_success(db: Database, tmp_path) -> None:
def test_invoke_http_error(db: Database, tmp_path) -> None:
"""验证节点返回协议 JSON 错误时透传错误信息。"""
manifest = echo_manifest()
manifest.command = ["python", "-u", str(FIXTURES / "failing_node.py")]
_register(db, manifest)
@@ -355,6 +387,7 @@ def test_invoke_http_error(db: Database, tmp_path) -> None:
def test_invoke_http_error_invalid_json(db: Database, tmp_path) -> None:
"""验证节点返回非法 JSON 时降级为通用错误信息。"""
manifest = echo_manifest()
manifest.command = ["python", "-u", str(FIXTURES / "failing_node.py")]
manifest.env["WOV_FAIL_INVALID_JSON"] = "1"
@@ -377,6 +410,7 @@ def test_invoke_http_error_invalid_json(db: Database, tmp_path) -> None:
def test_invoke_network_error(db: Database, tmp_path) -> None:
"""验证进程退出导致连接失败时返回 failed。"""
_register(db, echo_manifest())
manager = NodeManager(db)
try:
@@ -399,6 +433,7 @@ def test_invoke_network_error(db: Database, tmp_path) -> None:
def test_invoke_uses_configured_timeout(db: Database, monkeypatch) -> None:
"""验证调用超时取自配置常量。"""
_register(db, echo_manifest())
manager = NodeManager(db)
captured = {}
@@ -444,16 +479,19 @@ def test_invoke_uses_configured_timeout(db: Database, monkeypatch) -> None:
def test_release_unknown(db: Database) -> None:
"""验证释放未知实例是无害操作。"""
manager = NodeManager(db)
manager.release("missing")
def test_stop_unknown_instance(db: Database) -> None:
"""验证停止未知实例是无害操作。"""
manager = NodeManager(db)
manager.stop_instance("missing")
def test_stop_all_for_node(db: Database) -> None:
"""验证 stop_all_for_node 会停止该节点全部实例。"""
_register(db, echo_manifest())
manager = NodeManager(db)
runtime, _ = manager.acquire("echo")
@@ -463,6 +501,7 @@ def test_stop_all_for_node(db: Database) -> None:
def test_stop_locked_without_process(db: Database) -> None:
"""验证无进程句柄的实例也能被标记停止。"""
_register(db, echo_manifest())
manager = NodeManager(db)
runtime = NodeRuntime(
@@ -478,6 +517,7 @@ def test_stop_locked_without_process(db: Database) -> None:
def test_stop_process_already_exited() -> None:
"""验证进程已退出时停止流程直接返回。"""
class FakeProcess:
def poll(self):
return 0
@@ -487,6 +527,7 @@ def test_stop_process_already_exited() -> None:
def test_stop_process_timeout() -> None:
"""验证优雅终止超时后强制 kill。"""
class FakeProcess:
def poll(self):
return None
@@ -510,6 +551,7 @@ def test_stop_process_timeout() -> None:
def test_reaper_recycles_idle(db: Database, tmp_path) -> None:
"""验证空闲超过 TTL 的实例会被回收线程停止。"""
manifest = echo_manifest()
manifest.idle_ttl_seconds = 0
_register(db, manifest)
@@ -533,6 +575,7 @@ def test_reaper_recycles_idle(db: Database, tmp_path) -> None:
def test_reaper_keeps_warm(db: Database, tmp_path) -> None:
"""验证 keep_warm 实例即使空闲也不会被回收。"""
manifest = echo_manifest()
manifest.idle_ttl_seconds = 0
manifest.keep_warm = True
@@ -557,6 +600,7 @@ def test_reaper_keeps_warm(db: Database, tmp_path) -> None:
def test_reaper_keeps_busy(db: Database) -> None:
"""验证正在被占用的实例不会被回收。"""
manifest = echo_manifest()
manifest.idle_ttl_seconds = 0
_register(db, manifest)