import json import pathlib import sys import tempfile import unittest from argparse import Namespace ROOT = pathlib.Path(__file__).resolve().parents[2] sys.path.insert(0, str(ROOT / "scripts")) import generate_operator_docs class OperatorDocsGenerationTest(unittest.TestCase): def test_builtin_handler_hints_come_from_declarative_catalog(self): catalog_path = ROOT / "internal" / "api" / "builtin_operators_catalog.json" catalog = json.loads(catalog_path.read_text(encoding="utf-8")) hints = generate_operator_docs.load_builtin_handler_hints(str(catalog_path)) builtin_ids = [str(item["id"]) for item in catalog if str(item.get("type", "")).strip() == "builtin"] self.assertGreater(len(builtin_ids), 20) self.assertEqual( hints["operator-builtin-mongodb-write"], ("operator-repos/builtin/mongodb_write/src/operator.py", "builtin_mongodb_write"), ) self.assertEqual( hints["operator-builtin-model-inference"], ("operator-repos/builtin/model_inference/src/operator.py", "builtin_model_inference"), ) self.assertEqual(sorted(hints), sorted(builtin_ids)) def test_default_operator_payload_comes_from_local_catalog(self): args = Namespace(input_json="", api_base_url="") payload, source = generate_operator_docs.load_operator_payload(args) items = generate_operator_docs.operator_items_from_payload(payload) self.assertEqual(source, "internal/api/builtin_operators_catalog.json") self.assertGreater(len(items), 20) self.assertTrue(any(item.get("name") == "视频质检" for item in items)) def test_builtin_runtime_contract_points_to_independent_operator_source(self): catalog_path = ROOT / "internal" / "api" / "builtin_operators_catalog.json" catalog = json.loads(catalog_path.read_text(encoding="utf-8")) for item in catalog: if str(item.get("type", "")).strip() != "builtin": continue with self.subTest(operator=item["id"]): lines = generate_operator_docs.operator_runtime_contract(item) rendered = "\n".join(lines) self.assertIn(str(item["runtimeSource"]), rendered) self.assertIn("`run(...)`", rendered) self.assertIn(str(item["runtimeHandler"]), rendered) self.assertNotIn("`backend/operator-runner/main.py` 中的", rendered) def test_external_api_operator_docs_keep_runtime_secret_contract(self): operator = { "externalApi": { "sourceRepo": "https://example.test/repo", "fatRoute": "/api/example", "acceptanceProbe": {"method": "GET", "endpoint": "/api/example/health"}, } } lines = generate_operator_docs.render_external_api_block(operator) rendered = "\n".join(lines) self.assertIn("外部 API 契约", rendered) self.assertIn("不允许在算子源码或 metadata 中硬编码", rendered) def test_builtin_operator_docs_are_generated_from_current_catalog(self): args = Namespace(input_json="", api_base_url="") items = generate_operator_docs.choose_builtin_records(generate_operator_docs.load_operator_items(args)) docs_dir = ROOT / "docs" / "operators" with tempfile.TemporaryDirectory() as temp_dir: temp_path = pathlib.Path(temp_dir) generate_operator_docs.write_builtin_docs(items, temp_path) generated = sorted(path.name for path in temp_path.glob("*.md")) checked_in = sorted(path.name for path in docs_dir.glob("*.md")) self.assertEqual(generated, checked_in) for name in generated: with self.subTest(doc=name): self.assertEqual( (temp_path / name).read_text(encoding="utf-8"), (docs_dir / name).read_text(encoding="utf-8"), ) def test_operator_payload_source_must_be_explicitly_unique(self): args = Namespace(input_json="operators.json", api_base_url="http://api.example.test") with self.assertRaisesRegex(SystemExit, "set only one"): generate_operator_docs.load_operator_payload(args) if __name__ == "__main__": unittest.main()