droboticflow/tests/backend/operator_docs_generation_test.py
2026-06-30 01:37:23 +08:00

100 lines
4.3 KiB
Python

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()