"""CLI 接口契约测试。 **为什么需要**：使用手册（``docs/user-guide.md``）里的命令就是用户看到的接口。 文档与实现脱节是极易发生且很难察觉的问题 —— 实测发现手册记载的 ``hdiv sync financial --interleaved`` 在 CLI 中根本没有暴露， 而 ``hdiv ddl verify`` 的输出格式也与手册不符。 本测试把「手册承诺的接口」变成可执行断言： 只要有人删掉一个参数或改掉命令名，测试立刻失败。 """ from __future__ import annotations import pytest from hdiv.cli import build_parser @pytest.fixture(scope="module") def parser(): return build_parser() def _subparsers(p): """取子命令表。同时支持两种声明方式： - ``add_subparsers()`` → choices 是 dict（sync/universe/...） - ``add_argument("action", choices=[...])`` → choices 是 list（ddl/report/strategy） """ for action in p._actions: ch = getattr(action, "choices", None) if not ch: continue if isinstance(ch, dict): return ch raise AssertionError("未找到子命令") def _action_choices(p) -> set[str]: """取位置参数（如 ddl 的 plan/apply/verify）的取值集合。""" for action in p._actions: ch = getattr(action, "choices", None) if isinstance(ch, (list, tuple, set)) and not action.option_strings: return set(ch) return set() def _opts(p) -> set[str]: out: set[str] = set() for a in p._actions: out.update(a.option_strings) return out # --------------------------------------------------------------------------- # 手册记载的顶层命令必须全部存在 # --------------------------------------------------------------------------- DOCUMENTED_COMMANDS = [ "ddl", "sync", "audit", "report", "universe", "profile", "strategy", "backtest", "sensitivity", "web", "site", ] def test_all_documented_commands_exist(parser) -> None: subs = _subparsers(parser) missing = [c for c in DOCUMENTED_COMMANDS if c not in subs] assert not missing, f"手册记载但 CLI 不存在的命令：{missing}" def test_no_undocumented_commands(parser) -> None: """反向检查：CLI 不应有手册未提及的命令。""" subs = set(_subparsers(parser)) extra = subs - set(DOCUMENTED_COMMANDS) assert not extra, f"CLI 存在手册未记载的命令：{sorted(extra)}" # --------------------------------------------------------------------------- # 手册记载的动作/参数必须存在 # --------------------------------------------------------------------------- @pytest.mark.parametrize( "cmd,expected", [ ("ddl", {"plan", "apply", "verify"}), ("report", {"index", "validate"}), ("strategy", {"validate", "register", "list", "diff"}), ( "sync", {"dividend", "financial", "index", "price", "trading", "backfill"}, ), ("site", {"normalize", "archive", "build", "status"}), ], ) def test_documented_actions_exist(parser, cmd: str, expected: set[str]) -> None: sub = _subparsers(parser)[cmd] actual = _action_choices(sub) if not actual: # 用 add_subparsers 声明的命令 actual = set(_subparsers(sub)) missing = expected - actual assert not missing, f"hdiv {cmd} 缺少手册记载的动作：{sorted(missing)}" @pytest.mark.parametrize( "cmd,flags", [ ("sync", {"--only-missing", "--limit", "--symbols", "--apis", "--interleaved", "--start", "--end", "--no-resume", "--no-weight"}), ("universe", {"-c", "--config", "--asof", "--no-persist", "--no-html"}), ("profile", {"--universe-run", "--symbols", "--asof", "--html-limit"}), ("backtest", {"-s", "--strategy", "--mode", "--start", "--end", "--universe-run"}), ("sensitivity", {"-s", "--strategy", "--sweep"}), ("strategy", {"-f", "--file", "--other"}), ("audit", {"--no-persist", "--no-html"}), ("report", {"--dir"}), ("web", {"--host", "--port", "--api-only", "--out-dir"}), ], ) def test_documented_flags_exist(parser, cmd: str, flags: set[str]) -> None: sub = _subparsers(parser)[cmd] have = _opts(sub) missing = flags - have assert not missing, f"hdiv {cmd} 缺少手册记载的参数：{sorted(missing)}" def test_sync_interleaved_is_a_real_flag(parser) -> None: """回归：手册要求 ``hdiv sync financial --interleaved``，CLI 必须真的支持。""" sub = _subparsers(parser)["sync"] assert "--interleaved" in _opts(sub) # 且必须真的能解析（不只是声明） args = parser.parse_args(["sync", "financial", "--interleaved"]) assert args.interleaved is True args2 = parser.parse_args(["sync", "financial"]) assert args2.interleaved is False def test_backtest_universe_run_flag(parser) -> None: """股票池 ↔ 回测 的关联入口：``--universe-run`` 必须存在且可解析。""" args = parser.parse_args(["backtest", "--universe-run", "abc123"]) assert args.universe_run == "abc123" args2 = parser.parse_args(["backtest"]) assert args2.universe_run is None @pytest.mark.db def test_frozen_universe_is_used_when_run_id_given() -> None: """指定 --universe-run 时引擎必须使用该股票池，而不是重新筛选。""" from datetime import date from hdiv.backtest.engine import BacktestEngine from hdiv.core.config import load_config from hdiv.data import db db.load_dotenv_once() try: cfg = load_config("datasource") df = db.read_sql( "SELECT run_id FROM hd_universe_run WHERE deleted_at IS NULL " "ORDER BY created_at DESC LIMIT 1", cfg=cfg, ) if df.empty: pytest.skip("没有筛选记录") rid = df["run_id"].iloc[0] except Exception as exc: pytest.skip(f"数据库不可用：{exc}") eng = BacktestEngine.from_strategy( "config/strategy/high_dividend_v1.yml", universe_run_id=rid ) assert eng.universe_run_id == rid ctx = eng._prepare(eng.repo.trading_days(date(2024, 1, 1), date(2024, 6, 28)), verbose=False) sets = list(ctx["universe_by_refresh"].values()) assert sets, "应产生股票池" assert all(x == sets[0] for x in sets), "冻结股票池在各调仓日必须完全相同" def test_backtest_mode_choices(parser) -> None: """手册只承诺 single / walkforward 两种模式。""" sub = _subparsers(parser)["backtest"] for a in sub._actions: if "--mode" in a.option_strings: assert set(a.choices) == {"single", "walkforward"} return raise AssertionError("backtest 缺少 --mode 参数") def test_price_which_choices(parser) -> None: sub = _subparsers(parser)["sync"] for a in sub._actions: if "--which" in a.option_strings: assert set(a.choices) == {"daily", "adj_factor", "daily_basic"} return raise AssertionError("sync 缺少 --which 参数") # --------------------------------------------------------------------------- # 手册记载的输出格式 # --------------------------------------------------------------------------- def test_ddl_verify_output_mentions_table_count() -> None: """手册写的是「OK：30 张 hd_* 表结构全部符合 schema 定义」，输出须含数量。""" import inspect from hdiv import cli from hdiv.data.schema import ALL_TABLES src = inspect.getsource(cli.cmd_ddl) assert "len(ddl.ALL_TABLES)" in src, "ddl verify 输出应包含表的数量" assert len(ALL_TABLES) == 30 def test_help_text_is_chinese(parser) -> None: """手册面向中文用户，所有命令都应有中文说明。""" subs = _subparsers(parser) for name in DOCUMENTED_COMMANDS: assert subs[name].description, f"hdiv {name} 缺少说明文字" # --------------------------------------------------------------------------- # 手册文件本身 # --------------------------------------------------------------------------- def test_user_guide_exists_and_covers_all_commands() -> None: from hdiv.core.paths import project_root guide = project_root() / "docs" / "user-guide.md" assert guide.is_file(), "缺少使用手册 docs/user-guide.md" text = guide.read_text(encoding="utf-8") for cmd in DOCUMENTED_COMMANDS: assert f"hdiv {cmd}" in text, f"手册未记载命令：hdiv {cmd}" # 手册必须如实记录已知限制与部署要求（这两点最容易在文档里被淡化） assert "已知限制" in text assert "echarts.min.js" in text, "手册必须说明图表库的部署依赖" assert "asset_mode" in text, "手册必须说明自包含模式的开关" # 前后端分离的部署要点必须在手册里 assert "/api" in text, "手册必须说明 API 反代" assert "nginx" in text, "手册必须给出 nginx 配置指引" # --------------------------------------------------------------------------- # 参数组合与错误呈现 # --------------------------------------------------------------------------- # 只有这三个命令同时具备 --no-persist 与 --html（audit 传内存结果，两者可共存） @pytest.mark.parametrize("cmd", ["universe", "backtest"]) def test_no_persist_with_html_is_rejected_clearly(cmd: str) -> None: """回归：--no-persist 与 --html 互相矛盾，必须给出可操作提示。 静态报告只从数据库读取（保证数字可追溯到 SQL），未落库的运行渲染不出来。 早期实现会崩在报告生成器的 ValueError 里，用户看不出是参数冲突。 """ import subprocess import sys r = subprocess.run( [sys.executable, "-m", "hdiv", cmd, "--no-persist", "--html"], capture_output=True, text=True, env={**__import__("os").environ, "PYTHONPATH": "src"}, ) assert r.returncode == 1 out = r.stdout + r.stderr assert "--no-persist 与 --html 不能同时使用" in out, out[:400] # 必须是友好提示，而不是 traceback assert "Traceback" not in out, "用户可理解的错误不应打印调用栈" def test_audit_can_combine_no_persist_and_html() -> None: """audit 传的是内存结果而非按 run_id 读库，因此两者可以共存。""" import inspect from hdiv import cli src = inspect.getsource(cli.cmd_audit) assert "_reject_no_persist_with_html" not in src, \ "audit 不需拦截该组合（报告用内存 summary 渲染）" def test_hdiv_error_is_caught_without_traceback() -> None: """main() 应优雅处理 HdivError（数据缺失/配置冲突等），不打印调用栈。""" import inspect from hdiv import cli src = inspect.getsource(cli.main) assert "except HdivError" in src, "main() 未捕获 HdivError" branch = src.split("except HdivError")[1] assert "print_exc" not in branch, "HdivError 分支不应打印调用栈" assert "return 1" in branch, "应返回非零退出码" def test_html_flag_exists_on_all_report_producing_commands() -> None: """所有会产出报告的命令都应有 --html 开关且默认关闭。""" from hdiv.cli import build_parser p = build_parser() for cmd in ("universe", "profile", "backtest", "audit", "sensitivity"): args = p.parse_args([cmd]) assert getattr(args, "html", None) is False, f"hdiv {cmd} --html 默认应为 False"