chore: 纳入本地 Dify 1.19.0 源码及品牌与免登改动
演示目录只保留可重建的源码。运行密钥、数据卷、依赖和带口令的本地配置不进入仓库。 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
60158935f4
commit
6519682885
15831 files changed
+3063428
No files matched your search
@@ -0,0 +1,56 @@
|
||||
"""Collect coverage from the OpenAPI tools' real process boundaries."""
|
||||
|
||||
import os
|
||||
from pathlib import Path
|
||||
|
||||
import coverage
|
||||
import pytest
|
||||
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def openapi_subprocess_coverage(
|
||||
request: pytest.FixtureRequest, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
|
||||
) -> None:
|
||||
if request.path.name not in {"test_cached_console_openapi.py", "test_generate_swagger_specs.py"}:
|
||||
return
|
||||
current = coverage.Coverage.current()
|
||||
if current is None:
|
||||
return
|
||||
# Scope process instrumentation to these CLI tests instead of changing how
|
||||
# every backend test launches subprocesses. pytest-cov combines the parallel
|
||||
# data files with its own report after all fixtures have torn down.
|
||||
config = tmp_path / "subprocess-coverage.ini"
|
||||
api_root = Path(__file__).resolve().parents[3]
|
||||
data_file = current.get_option("run:data_file")
|
||||
assert isinstance(data_file, str)
|
||||
data_file = str(Path(data_file).absolute())
|
||||
omitted = current.get_option("run:omit") or []
|
||||
assert isinstance(omitted, list)
|
||||
# Children run from temporary directories. Preserve the parent report's
|
||||
# exclusions, resolving repository-relative patterns before changing cwd.
|
||||
isolated_dev = tmp_path / "api/dev"
|
||||
sources = [str(api_root)]
|
||||
if request.path.name == "test_cached_console_openapi.py":
|
||||
sources.append(str(isolated_dev))
|
||||
omit = "\n ".join(
|
||||
[str(Path(pattern).absolute()) for pattern in omitted]
|
||||
+ [
|
||||
str(isolated_dev / name)
|
||||
for name in ("__init__.py", "generate_swagger_specs.py", "export_console_openapi.py")
|
||||
]
|
||||
)
|
||||
patches = ["subprocess", "_exit"]
|
||||
if hasattr(os, "fork"):
|
||||
patches.extend(["fork", "execv"])
|
||||
config.write_text(
|
||||
"[run]\n"
|
||||
f"data_file = {data_file}\n"
|
||||
f"branch = {current.get_option('run:branch')}\n"
|
||||
"parallel = true\n"
|
||||
"source =\n " + "\n ".join(sources) + "\n"
|
||||
f"omit =\n {omit}\n"
|
||||
f"patch = {', '.join(patches)}\n"
|
||||
)
|
||||
monkeypatch.setenv("COVERAGE_PROCESS_START", str(config))
|
||||
# CI supplies a relative COVERAGE_FILE, which takes precedence over the ini.
|
||||
monkeypatch.setenv("COVERAGE_FILE", data_file)
|
||||
@@ -0,0 +1,233 @@
|
||||
"""Exercise the actual cache client/server, with small isolated backend modules."""
|
||||
|
||||
import concurrent.futures
|
||||
import json
|
||||
import os
|
||||
import py_compile
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
from collections.abc import Iterator
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
pytestmark = pytest.mark.skipif(not hasattr(os, "fork"), reason="The memory export server uses POSIX isolation")
|
||||
|
||||
|
||||
@dataclass
|
||||
class CacheClient:
|
||||
api: Path
|
||||
env: dict[str, str]
|
||||
used_envs: list[dict[str, str]] = field(default_factory=list)
|
||||
|
||||
def request(self, *, setting: str | None = None, check: bool = True) -> subprocess.CompletedProcess[str]:
|
||||
request_env = self.env if setting is None else {**self.env, "OPENAPI_TEST_SETTING": setting}
|
||||
self.used_envs.append(request_env)
|
||||
return subprocess.run(
|
||||
[sys.executable, str(self.api / "dev/cached_console_openapi.py")],
|
||||
cwd=self.api.parent,
|
||||
env=request_env,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=30,
|
||||
check=check,
|
||||
)
|
||||
|
||||
def export(self, *, setting: str | None = None) -> dict[str, str | int | None]:
|
||||
return json.loads(self.request(setting=setting).stdout)["console"]
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def backend(tmp_path: Path) -> Iterator[CacheClient]:
|
||||
api = tmp_path / "api"
|
||||
(api / "dev").mkdir(parents=True)
|
||||
script = api / "dev/cached_console_openapi.py"
|
||||
original = Path(__file__).resolve().parents[3] / "dev/cached_console_openapi.py"
|
||||
shutil.copyfile(original, script)
|
||||
modules = {
|
||||
"dev/__init__.py": "",
|
||||
"dev/generate_swagger_specs.py": "def apply_runtime_defaults(): pass\n",
|
||||
"models.py": "import secrets\nVALUE = 'v1'\nSNAPSHOT = secrets.token_hex(8)\n",
|
||||
"controllers/fixture.py": "FIELD = 'integer'\n",
|
||||
"core/mcp/types.py": "",
|
||||
"dify_agent/protocol/schemas.py": "",
|
||||
"graphon/nodes/parameter_extractor/entities.py": "",
|
||||
"services/knowledge_fs/product_dto.py": "",
|
||||
"dev/export_console_openapi.py": """
|
||||
import json, os
|
||||
def main():
|
||||
from controllers.fixture import FIELD
|
||||
from models import VALUE, SNAPSHOT
|
||||
print(json.dumps({'console': {'field': FIELD, 'model': VALUE, 'pid': os.getpid(),
|
||||
'snapshot': SNAPSHOT, 'setting': os.getenv('OPENAPI_TEST_SETTING')}, 'fast': {}}))
|
||||
if __name__ == '__main__': main()
|
||||
""",
|
||||
}
|
||||
for filename, content in modules.items():
|
||||
path = api / filename
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
for parent in path.parents:
|
||||
if parent == api:
|
||||
break
|
||||
(parent / "__init__.py").touch()
|
||||
path.write_text(content)
|
||||
client = CacheClient(api, {**os.environ, "PYTHONPATH": str(api)})
|
||||
yield client
|
||||
for request_env in client.used_envs:
|
||||
subprocess.run(
|
||||
[sys.executable, str(script), "--stop"],
|
||||
cwd=tmp_path,
|
||||
env=request_env,
|
||||
capture_output=True,
|
||||
timeout=10,
|
||||
check=True,
|
||||
)
|
||||
|
||||
|
||||
def test_memory_cache_is_shared_and_ignores_test_files(backend: CacheClient) -> None:
|
||||
api, call = backend.api, backend.export
|
||||
first = call()
|
||||
assert call() == first
|
||||
(api / "tests").mkdir()
|
||||
(api / "tests/test_unrelated.py").write_text("# unrelated test\n")
|
||||
assert call() == first
|
||||
with concurrent.futures.ThreadPoolExecutor(max_workers=4) as pool:
|
||||
assert all(result == first for result in pool.map(lambda _: call(), range(4)))
|
||||
assert not list(api.rglob("*.json"))
|
||||
assert not list(api.rglob("*.pyc"))
|
||||
|
||||
|
||||
def test_changed_controller_is_fresh_and_preloaded_dependency_restarts_snapshot(backend: CacheClient) -> None:
|
||||
api, call = backend.api, backend.export
|
||||
first = call()
|
||||
controller = api / "controllers/fixture.py"
|
||||
controller.write_text("FIELD = 'number'\n")
|
||||
second = call()
|
||||
assert second["field"] == "number"
|
||||
assert second["pid"] != first["pid"]
|
||||
assert second["snapshot"] == first["snapshot"]
|
||||
# Same-size edit with unchanged mtime must not revive a stale .pyc or snapshot.
|
||||
model = api / "models.py"
|
||||
stat = model.stat()
|
||||
model.write_text(model.read_text().replace("'v1'", "'v2'"))
|
||||
os.utime(model, ns=(stat.st_atime_ns, stat.st_mtime_ns))
|
||||
third = call()
|
||||
assert third["model"] == "v2"
|
||||
assert third["snapshot"] != second["snapshot"]
|
||||
assert third["field"] == "number"
|
||||
|
||||
|
||||
def test_export_errors_never_return_old_contracts_and_recover_after_fix(backend: CacheClient) -> None:
|
||||
api, call = backend.api, backend.export
|
||||
first = call()
|
||||
controller = api / "controllers/fixture.py"
|
||||
controller.write_text("FIELD = syntax error\n")
|
||||
failure = backend.request(check=False)
|
||||
assert failure.returncode != 0
|
||||
assert not failure.stdout
|
||||
assert "SyntaxError" in failure.stderr
|
||||
controller.write_text("FIELD = 'string'\n")
|
||||
fixed = call()
|
||||
assert fixed["field"] == "string"
|
||||
assert fixed["pid"] != first["pid"]
|
||||
|
||||
|
||||
def test_environment_and_file_additions_invalidate_memory_cache(backend: CacheClient) -> None:
|
||||
api, call = backend.api, backend.export
|
||||
first = call()
|
||||
variant = call(setting="variant")
|
||||
assert variant["setting"] == "variant"
|
||||
assert variant["snapshot"] != first["snapshot"]
|
||||
(api / "new_dependency.py").write_text("VALUE = 1\n")
|
||||
added = call()
|
||||
assert added["snapshot"] != first["snapshot"]
|
||||
(api / "new_dependency.py").unlink()
|
||||
assert call()["snapshot"] != added["snapshot"]
|
||||
|
||||
|
||||
def test_sibling_python_models_refresh_cached_exports_without_stale_bytecode(backend: CacheClient) -> None:
|
||||
package = backend.api.parent / "dify-agent/src/citation_fixture"
|
||||
package.mkdir(parents=True)
|
||||
(package / "__init__.py").touch()
|
||||
model = package / "model.py"
|
||||
model.write_text("FIELD = 'string'\n")
|
||||
compiled = py_compile.compile(str(model), doraise=True)
|
||||
assert compiled is not None
|
||||
bytecode = Path(compiled).read_bytes()
|
||||
# This module is imported by the export worker, not by the preloaded snapshot.
|
||||
(backend.api / "controllers/fixture.py").write_text("from citation_fixture.model import FIELD\n")
|
||||
backend.env["PYTHONPATH"] = os.pathsep.join([str(backend.api), str(package.parent)])
|
||||
first = backend.export()
|
||||
assert first["field"] == "string"
|
||||
assert backend.export() == first
|
||||
stat = model.stat()
|
||||
model.write_text("FIELD = 'number'\n")
|
||||
os.utime(model, ns=(stat.st_atime_ns, stat.st_mtime_ns))
|
||||
changed = backend.export()
|
||||
assert changed["field"] == "number"
|
||||
assert changed["pid"] != first["pid"]
|
||||
added = package / "new_model.py"
|
||||
added.write_text("VALUE = 1\n")
|
||||
with_added = backend.export()
|
||||
assert with_added["pid"] != changed["pid"]
|
||||
added.unlink()
|
||||
assert backend.export()["pid"] != with_added["pid"]
|
||||
assert Path(compiled).read_bytes() == bytecode
|
||||
|
||||
|
||||
def test_native_threads_use_fresh_exports_and_propagate_failures(backend: CacheClient) -> None:
|
||||
model = backend.api / "models.py"
|
||||
model.write_text(
|
||||
model.read_text()
|
||||
+ "import threading, time\n"
|
||||
+ "threading.Thread(target=time.sleep, args=(60,), daemon=True).start()\n"
|
||||
)
|
||||
first = backend.export()
|
||||
controller = backend.api / "controllers/fixture.py"
|
||||
controller.write_text("FIELD = 'string'\n")
|
||||
changed = backend.export()
|
||||
assert changed["field"] == "string"
|
||||
assert changed["snapshot"] != first["snapshot"]
|
||||
controller.write_text("FIELD = syntax error\n")
|
||||
failure = backend.request(check=False)
|
||||
assert failure.returncode != 0
|
||||
assert not failure.stdout
|
||||
assert "SyntaxError" in failure.stderr
|
||||
|
||||
|
||||
def test_invalid_export_payload_does_not_replace_a_valid_contract(backend: CacheClient) -> None:
|
||||
first = backend.export()
|
||||
exporter = backend.api / "dev/export_console_openapi.py"
|
||||
original = exporter.read_text()
|
||||
exporter.write_text("def main(): print('{\"unexpected\": {}}')\n")
|
||||
failure = backend.request(check=False)
|
||||
assert failure.returncode != 0
|
||||
assert not failure.stdout
|
||||
assert "Invalid Console export response" in failure.stderr
|
||||
exporter.write_text(original)
|
||||
assert backend.export()["field"] == first["field"]
|
||||
|
||||
|
||||
def test_failed_preload_falls_back_to_fresh_exports(backend: CacheClient) -> None:
|
||||
(backend.api / "core/mcp/types.py").write_text("raise RuntimeError('Cannot preload this dependency')\n")
|
||||
first = backend.export()
|
||||
(backend.api / "controllers/fixture.py").write_text("FIELD = 'string'\n")
|
||||
changed = backend.export()
|
||||
assert changed["field"] == "string"
|
||||
assert changed["snapshot"] != first["snapshot"]
|
||||
|
||||
|
||||
def test_socket_directory_must_be_private(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
from dev.cached_console_openapi import socket_path
|
||||
|
||||
# Keep this short enough for the Unix socket path limit on macOS.
|
||||
with tempfile.TemporaryDirectory(prefix="dify-ipc-", dir="/tmp") as directory:
|
||||
monkeypatch.setattr(tempfile, "tempdir", directory)
|
||||
path = socket_path()
|
||||
assert path.parent.stat().st_mode & 0o077 == 0
|
||||
path.parent.chmod(0o755)
|
||||
with pytest.raises(PermissionError, match="private to the current user"):
|
||||
socket_path()
|
||||
@@ -0,0 +1,337 @@
|
||||
"""Tests for the focused Dify KnowledgeFS Python coverage gate."""
|
||||
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
from dev.check_knowledge_fs_coverage import (
|
||||
CoverageFile,
|
||||
CoverageGateError,
|
||||
CoverageReport,
|
||||
CoverageSummary,
|
||||
collect_changed_glue_lines,
|
||||
is_core_coverage_path,
|
||||
load_glue_coverage_paths,
|
||||
parse_added_lines,
|
||||
resolve_diff_base,
|
||||
validate_changed_glue_coverage,
|
||||
validate_core_coverage,
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"path",
|
||||
[
|
||||
"api/commands/knowledge_fs.py",
|
||||
"api/configs/extra/knowledge_fs_config.py",
|
||||
"api/controllers/console/knowledge_fs/resources.py",
|
||||
"api/controllers/inner_api/knowledge_fs/storage.py",
|
||||
"api/controllers/openapi/knowledge_fs.py",
|
||||
"api/controllers/service_api/knowledge_fs/resources.py",
|
||||
"api/events/event_handlers/sync_knowledge_fs_bindings_when_app_published_workflow_updated.py",
|
||||
"api/extensions/ext_knowledge_fs_observability.py",
|
||||
"api/models/knowledge_fs.py",
|
||||
"api/repositories/sqlalchemy_knowledge_fs_cutover_repository.py",
|
||||
"api/services/dataset_knowledge_fs_upgrade_file_lease.py",
|
||||
"api/services/dataset_knowledge_fs_upgrade_service.py",
|
||||
"api/services/knowledge_fs/builtin_tool/knowledge_fs/knowledge_fs.py",
|
||||
"api/services/knowledge_fs/knowledge_retrieval_v2/knowledge_retrieval_v2_node.py",
|
||||
"api/services/knowledge_fs/retrieval_contracts.py",
|
||||
"api/services/knowledge_fs/runtime.py",
|
||||
"api/services/knowledge_fs_capability.py",
|
||||
"api/tasks/knowledge_fs_lifecycle_tasks.py",
|
||||
],
|
||||
)
|
||||
def test_core_coverage_scope_includes_every_required_layer(path: str) -> None:
|
||||
assert is_core_coverage_path(path)
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"path",
|
||||
[
|
||||
"api/app_factory.py",
|
||||
"api/dev/check_knowledge_fs_coverage.py",
|
||||
"api/migrations/versions/revision_knowledge_fs.py",
|
||||
"api/tests/unit_tests/services/knowledge_fs/test_runtime.py",
|
||||
],
|
||||
)
|
||||
def test_core_coverage_scope_excludes_glue_migrations_and_tests(path: str) -> None:
|
||||
assert not is_core_coverage_path(path)
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"owned_path", ["api/services/knowledge_fs/runtime.py", "api/services/knowledge_fs/resource.py"]
|
||||
)
|
||||
def test_core_coverage_aggregates_lines_and_branches_and_fails_closed(tmp_path: Path, owned_path: str) -> None:
|
||||
service_path = tmp_path / owned_path
|
||||
model_path = tmp_path / "api/models/knowledge_fs.py"
|
||||
service_path.parent.mkdir(parents=True)
|
||||
model_path.parent.mkdir(parents=True)
|
||||
service_path.touch()
|
||||
model_path.touch()
|
||||
report = coverage_report(
|
||||
{
|
||||
owned_path: coverage_file(
|
||||
covered_lines=8,
|
||||
num_statements=10,
|
||||
covered_branches=1,
|
||||
num_branches=2,
|
||||
),
|
||||
"api/models/knowledge_fs.py": coverage_file(
|
||||
covered_lines=10,
|
||||
num_statements=10,
|
||||
covered_branches=2,
|
||||
num_branches=2,
|
||||
),
|
||||
}
|
||||
)
|
||||
|
||||
totals = validate_core_coverage(report, workspace_root=tmp_path, minimum=87.5)
|
||||
|
||||
assert totals.covered == 21
|
||||
assert totals.total == 24
|
||||
assert totals.percent == pytest.approx(87.5)
|
||||
with pytest.raises(CoverageGateError, match=r"87\.50%.*minimum 88\.00%"):
|
||||
validate_core_coverage(report, workspace_root=tmp_path, minimum=88)
|
||||
|
||||
del report["files"]["api/models/knowledge_fs.py"]
|
||||
with pytest.raises(CoverageGateError, match="coverage report is missing.*api/models/knowledge_fs.py"):
|
||||
validate_core_coverage(report, workspace_root=tmp_path, minimum=0)
|
||||
|
||||
|
||||
def test_core_coverage_rejects_unclassified_knowledge_fs_production_files(tmp_path: Path) -> None:
|
||||
core_path = tmp_path / "api/services/knowledge_fs/runtime.py"
|
||||
escaped_path = tmp_path / "api/experimental/knowledge_fs_escape.py"
|
||||
core_path.parent.mkdir(parents=True)
|
||||
escaped_path.parent.mkdir(parents=True)
|
||||
core_path.touch()
|
||||
escaped_path.touch()
|
||||
report = coverage_report(
|
||||
{
|
||||
"api/services/knowledge_fs/runtime.py": coverage_file(
|
||||
covered_lines=1,
|
||||
num_statements=1,
|
||||
covered_branches=0,
|
||||
num_branches=0,
|
||||
)
|
||||
}
|
||||
)
|
||||
|
||||
with pytest.raises(CoverageGateError, match="unclassified.*api/experimental/knowledge_fs_escape.py"):
|
||||
validate_core_coverage(report, workspace_root=tmp_path, minimum=0)
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"migration",
|
||||
[
|
||||
"api/migrations/versions/2026_07_21_1500-d4f6e8a1c305_add_knowledge_fs_remote_freeze_evidence.py",
|
||||
"api/migrations/versions/2026_07_21_1600-e5a7c9b2d416_add_knowledge_fs_cleanup_completion.py",
|
||||
"api/migrations/versions/2026_08_13_1200-9d4e6f8a1b2c_add_knowledge_fs_space_tag_bindings.py",
|
||||
"api/migrations/versions/2026_08_17_1200-4f8b2c7d9e10_add_knowledge_fs_icon_background.py",
|
||||
"api/migrations/versions/2026_08_17_1200-f3a8c1d7e920_add_knowledge_fs_upgrade_jobs.py",
|
||||
"api/migrations/versions/2026_08_18_1200-e6b4a2c9d731_limit_active_knowledge_fs_upgrades.py",
|
||||
],
|
||||
)
|
||||
def test_core_coverage_allows_explicit_non_core_migrations(tmp_path: Path, migration: str) -> None:
|
||||
core_path = tmp_path / "api/services/knowledge_fs/runtime.py"
|
||||
migration_path = tmp_path / migration
|
||||
core_path.parent.mkdir(parents=True)
|
||||
migration_path.parent.mkdir(parents=True)
|
||||
core_path.touch()
|
||||
migration_path.touch()
|
||||
report = coverage_report(
|
||||
{
|
||||
"api/services/knowledge_fs/runtime.py": coverage_file(
|
||||
covered_lines=1,
|
||||
num_statements=1,
|
||||
covered_branches=0,
|
||||
num_branches=0,
|
||||
)
|
||||
}
|
||||
)
|
||||
|
||||
totals = validate_core_coverage(report, workspace_root=tmp_path, minimum=100)
|
||||
|
||||
assert totals.percent == 100
|
||||
|
||||
|
||||
def test_parse_added_lines_and_validate_changed_glue_coverage() -> None:
|
||||
changed_lines = parse_added_lines(
|
||||
"""diff --git a/api/app_factory.py b/api/app_factory.py
|
||||
--- a/api/app_factory.py
|
||||
+++ b/api/app_factory.py
|
||||
@@ -10,0 +11,3 @@
|
||||
+covered_call()
|
||||
+missing_call()
|
||||
+# non-executable note
|
||||
diff --git a/api/services/account_service.py b/api/services/account_service.py
|
||||
--- a/api/services/account_service.py
|
||||
+++ b/api/services/account_service.py
|
||||
@@ -40 +42 @@
|
||||
-old_call()
|
||||
+replacement_call()
|
||||
"""
|
||||
)
|
||||
report = coverage_report(
|
||||
{
|
||||
"api/app_factory.py": coverage_file(
|
||||
covered_lines=1,
|
||||
num_statements=2,
|
||||
covered_branches=0,
|
||||
num_branches=0,
|
||||
executed_lines=[11],
|
||||
missing_lines=[12],
|
||||
),
|
||||
"api/services/account_service.py": coverage_file(
|
||||
covered_lines=1,
|
||||
num_statements=1,
|
||||
covered_branches=0,
|
||||
num_branches=0,
|
||||
executed_lines=[42],
|
||||
),
|
||||
}
|
||||
)
|
||||
|
||||
assert changed_lines == {
|
||||
"api/app_factory.py": {11, 12, 13},
|
||||
"api/services/account_service.py": {42},
|
||||
}
|
||||
totals = validate_changed_glue_coverage(report, changed_lines=changed_lines, minimum=66)
|
||||
assert totals.covered == 2
|
||||
assert totals.total == 3
|
||||
assert totals.percent == pytest.approx(200 / 3)
|
||||
with pytest.raises(CoverageGateError, match=r"66\.67%.*minimum 90\.00%"):
|
||||
validate_changed_glue_coverage(report, changed_lines=changed_lines, minimum=90)
|
||||
|
||||
del report["files"]["api/app_factory.py"]
|
||||
with pytest.raises(CoverageGateError, match="coverage report is missing changed glue file"):
|
||||
validate_changed_glue_coverage(report, changed_lines=changed_lines, minimum=0)
|
||||
|
||||
|
||||
def test_glue_manifest_is_authoritative_and_fail_closed(tmp_path: Path) -> None:
|
||||
first = tmp_path / "api/app_factory.py"
|
||||
second = tmp_path / "api/extensions/ext_celery.py"
|
||||
first.parent.mkdir(parents=True)
|
||||
second.parent.mkdir(parents=True)
|
||||
first.touch()
|
||||
second.touch()
|
||||
manifest = tmp_path / "glue-files"
|
||||
manifest.write_bytes(b"api/app_factory.py\0api/extensions/ext_celery.py\0")
|
||||
|
||||
assert load_glue_coverage_paths(manifest, workspace_root=tmp_path) == (
|
||||
"api/app_factory.py",
|
||||
"api/extensions/ext_celery.py",
|
||||
)
|
||||
|
||||
manifest.write_bytes(b"")
|
||||
with pytest.raises(CoverageGateError, match="glue coverage target set is empty"):
|
||||
load_glue_coverage_paths(manifest, workspace_root=tmp_path)
|
||||
|
||||
manifest.write_bytes(b"api/missing.py\0")
|
||||
with pytest.raises(CoverageGateError, match="glue coverage paths are invalid.*api/missing.py"):
|
||||
load_glue_coverage_paths(manifest, workspace_root=tmp_path)
|
||||
|
||||
|
||||
def test_diff_base_resolution_is_explicit_and_fail_closed_for_a_single_commit(tmp_path: Path) -> None:
|
||||
subprocess.run(["git", "init", "--quiet"], cwd=tmp_path, check=True)
|
||||
source = tmp_path / "source.py"
|
||||
source.write_text("value = 1\n")
|
||||
subprocess.run(["git", "add", "source.py"], cwd=tmp_path, check=True)
|
||||
subprocess.run(
|
||||
[
|
||||
"git",
|
||||
"-c",
|
||||
"user.email=coverage-test@example.com",
|
||||
"-c",
|
||||
"user.name=Coverage Test",
|
||||
"commit",
|
||||
"--quiet",
|
||||
"-m",
|
||||
"fixture",
|
||||
],
|
||||
cwd=tmp_path,
|
||||
check=True,
|
||||
)
|
||||
head = subprocess.run(
|
||||
["git", "rev-parse", "HEAD"],
|
||||
cwd=tmp_path,
|
||||
check=True,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
).stdout.strip()
|
||||
|
||||
assert resolve_diff_base(tmp_path, head) == head
|
||||
with pytest.raises(CoverageGateError, match=r"cannot resolve coverage diff base HEAD\^"):
|
||||
resolve_diff_base(tmp_path, "")
|
||||
with pytest.raises(CoverageGateError, match="cannot resolve coverage diff base missing-base"):
|
||||
resolve_diff_base(tmp_path, "missing-base")
|
||||
|
||||
|
||||
@pytest.mark.parametrize("configuration", ["diff.mnemonicPrefix", "diff.noprefix"])
|
||||
def test_changed_glue_collection_ignores_user_diff_prefix_configuration(tmp_path: Path, configuration: str) -> None:
|
||||
subprocess.run(["git", "init", "--quiet"], cwd=tmp_path, check=True)
|
||||
subprocess.run(["git", "config", configuration, "true"], cwd=tmp_path, check=True)
|
||||
source = tmp_path / "api/app_factory.py"
|
||||
source.parent.mkdir()
|
||||
source.write_text("value = 1\n")
|
||||
subprocess.run(["git", "add", "."], cwd=tmp_path, check=True)
|
||||
subprocess.run(
|
||||
[
|
||||
"git",
|
||||
"-c",
|
||||
"user.email=coverage@example.com",
|
||||
"-c",
|
||||
"user.name=Coverage Test",
|
||||
"commit",
|
||||
"--quiet",
|
||||
"-m",
|
||||
"fixture",
|
||||
],
|
||||
cwd=tmp_path,
|
||||
check=True,
|
||||
)
|
||||
source.write_text("value = 2\n")
|
||||
|
||||
changed_lines = collect_changed_glue_lines(tmp_path, "HEAD", glue_paths=("api/app_factory.py",))
|
||||
|
||||
assert changed_lines == {"api/app_factory.py": {1}}
|
||||
report = coverage_report(
|
||||
{
|
||||
"api/app_factory.py": coverage_file(
|
||||
covered_lines=0,
|
||||
num_statements=1,
|
||||
covered_branches=0,
|
||||
num_branches=0,
|
||||
missing_lines=[1],
|
||||
)
|
||||
}
|
||||
)
|
||||
with pytest.raises(CoverageGateError, match="changed-glue line coverage is 0.00%"):
|
||||
validate_changed_glue_coverage(report, changed_lines=changed_lines, minimum=90)
|
||||
|
||||
|
||||
def coverage_report(files: dict[str, CoverageFile]) -> CoverageReport:
|
||||
return {"files": files}
|
||||
|
||||
|
||||
def coverage_file(
|
||||
*,
|
||||
covered_lines: int,
|
||||
num_statements: int,
|
||||
covered_branches: int,
|
||||
num_branches: int,
|
||||
executed_lines: list[int] | None = None,
|
||||
missing_lines: list[int] | None = None,
|
||||
) -> CoverageFile:
|
||||
summary = CoverageSummary(
|
||||
covered_lines=covered_lines,
|
||||
num_statements=num_statements,
|
||||
covered_branches=covered_branches,
|
||||
num_branches=num_branches,
|
||||
)
|
||||
return {
|
||||
"executed_lines": executed_lines or [],
|
||||
"missing_lines": missing_lines or [],
|
||||
"summary": summary,
|
||||
}
|
||||
@@ -0,0 +1,280 @@
|
||||
import pytest
|
||||
|
||||
from dev import generate_billing_client as generator
|
||||
|
||||
PREFIX = "#/components/schemas/dify.saas.api.billing."
|
||||
|
||||
|
||||
def _source_spec() -> generator.JsonObject:
|
||||
reply = {"$ref": f"{PREFIX}GetSubscriptionInfoReply"}
|
||||
return {
|
||||
"openapi": "3.0.3",
|
||||
"info": {"title": "", "version": "0.0.1"},
|
||||
"paths": {
|
||||
"/v1/subscription/info": {
|
||||
"get": {
|
||||
"operationId": "BillingSubscription_GetSubscriptionInfo",
|
||||
"responses": {"200": {"content": {"application/json": {"schema": reply}}}},
|
||||
}
|
||||
},
|
||||
"/v1/coupons/stripe": {
|
||||
"get": {
|
||||
"operationId": "BillingCoupon_ListStripeCoupons",
|
||||
"responses": {
|
||||
"200": {"content": {"application/json": {"schema": {"$ref": f"{PREFIX}ListCouponsReply"}}}}
|
||||
},
|
||||
}
|
||||
},
|
||||
},
|
||||
"components": {
|
||||
"schemas": {
|
||||
"dify.saas.api.billing.GetSubscriptionInfoReply": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"plan": {"type": "string", "enum": ["sandbox", "team"]},
|
||||
"paid_period_end": {"type": "string", "format": "int64"},
|
||||
"members": {"$ref": f"{PREFIX}Quota"},
|
||||
"usage_unknown": {"type": "boolean", "nullable": True},
|
||||
"tags": {"type": "array", "items": {"type": "string"}},
|
||||
"renewed_at": {"type": "string", "format": "date-time"},
|
||||
},
|
||||
},
|
||||
"dify.saas.api.billing.Quota": {"type": "object", "properties": {"limit": {"type": "integer"}}},
|
||||
"dify.saas.api.billing.ListCouponsReply": {
|
||||
"type": "object",
|
||||
"properties": {"coupon_id": {"type": "string"}},
|
||||
},
|
||||
"dify.saas.api.billing.Error": {
|
||||
"required": ["code", "reason", "message", "metadata"],
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"code": {"type": "integer", "description": "HTTP status code.", "format": "int32"},
|
||||
"reason": {"type": "string", "description": "See <Service>ErrorReason."},
|
||||
"message": {"type": "string"},
|
||||
"metadata": {"type": "object", "additionalProperties": {"type": "string"}},
|
||||
},
|
||||
},
|
||||
"dify.saas.api.billing.BillingSubscriptionErrorReason": {
|
||||
"enum": ["", "CODEC", "MISSING_PLAN"],
|
||||
"type": "string",
|
||||
},
|
||||
"dify.saas.api.billing.BillingCouponErrorReason": {
|
||||
"enum": ["", "CODEC", "BILLING_COUPON_NOT_FOUND"],
|
||||
"type": "string",
|
||||
},
|
||||
}
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def subscription_info_only(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
monkeypatch.setitem(
|
||||
generator.ALLOWED_OPERATIONS,
|
||||
"billing",
|
||||
(generator.AllowedOperation("GET", "/v1/subscription/info", "BILLING"),),
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.usefixtures("subscription_info_only")
|
||||
def test_snapshot_keeps_only_allowlisted_operations_and_reachable_schemas() -> None:
|
||||
snapshot = generator.build_snapshot("billing", _source_spec(), "abc123")
|
||||
|
||||
assert snapshot[generator.SNAPSHOT_COMMIT_KEY] == "abc123"
|
||||
assert list(snapshot["paths"]) == ["/v1/subscription/info"]
|
||||
assert sorted(snapshot["components"]["schemas"]) == [
|
||||
"BillingSubscriptionErrorReason",
|
||||
"Error",
|
||||
"GetSubscriptionInfoReply",
|
||||
"Quota",
|
||||
]
|
||||
assert "coupon" not in generator.render_snapshot(snapshot).lower()
|
||||
|
||||
|
||||
@pytest.mark.usefixtures("subscription_info_only")
|
||||
def test_snapshot_marks_presence_from_protojson_rules() -> None:
|
||||
schema = generator.build_snapshot("billing", _source_spec(), "abc123")["components"]["schemas"][
|
||||
"GetSubscriptionInfoReply"
|
||||
]
|
||||
|
||||
# Proto3 optional fields are omitted when unset, so only they stay out of required.
|
||||
assert schema["required"] == ["plan", "paid_period_end", "members", "tags", "renewed_at"]
|
||||
assert schema["properties"]["members"] == {"allOf": [{"$ref": "#/components/schemas/Quota"}], "nullable": True}
|
||||
assert "nullable" not in schema["properties"]["plan"]
|
||||
|
||||
|
||||
@pytest.mark.usefixtures("subscription_info_only")
|
||||
def test_rendered_module_types_fields_and_operations() -> None:
|
||||
snapshot = generator.build_snapshot("billing", _source_spec(), "abc123")
|
||||
|
||||
source = generator.render_module("billing", snapshot)
|
||||
|
||||
assert 'plan: Literal["sandbox", "team"]' in source
|
||||
assert "paid_period_end: int\n" in source
|
||||
assert "members: Quota | None\n" in source
|
||||
assert "usage_unknown: bool | None = None\n" in source
|
||||
assert "renewed_at: datetime\n" in source
|
||||
assert "def subscription_get_subscription_info() -> GetSubscriptionInfoReply:" in source
|
||||
assert '"/subscription/info",' in source
|
||||
assert 'type BillingSubscriptionErrorReason = Literal["", "CODEC", "MISSING_PLAN"]' in source
|
||||
assert "def _is_billing_subscription_error_reason(value: str) -> TypeIs[BillingSubscriptionErrorReason]:" in source
|
||||
assert "errors=BILLING_SUBSCRIPTION_ERRORS," in source
|
||||
assert "class BillingSubscriptionUpstreamError(BillingUpstreamError):" in source
|
||||
assert "reason: BillingSubscriptionErrorReason | UnknownErrorReason | None = None," in source
|
||||
assert (
|
||||
"class BillingSubscriptionUpstreamUnavailableError(BillingSubscriptionUpstreamError, "
|
||||
"BillingUpstreamUnavailableError):"
|
||||
) in source
|
||||
assert "BILLING_SUBSCRIPTION_ERRORS = ServiceErrors(" in source
|
||||
assert "Coupon" not in source
|
||||
assert "class Error(" not in source
|
||||
assert "ErrorReason =" not in source.replace("BillingSubscriptionErrorReason =", "")
|
||||
|
||||
|
||||
def test_rendered_module_gives_each_service_its_own_errors(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
monkeypatch.setitem(
|
||||
generator.ALLOWED_OPERATIONS,
|
||||
"billing",
|
||||
(
|
||||
generator.AllowedOperation("GET", "/v1/subscription/info", "BILLING"),
|
||||
generator.AllowedOperation("GET", "/v1/coupons/stripe", "BILLING"),
|
||||
),
|
||||
)
|
||||
snapshot = generator.build_snapshot("billing", _source_spec(), "abc123")
|
||||
|
||||
source = generator.render_module("billing", snapshot)
|
||||
|
||||
assert {"BillingCouponErrorReason", "BillingSubscriptionErrorReason"} <= set(snapshot["components"]["schemas"])
|
||||
subscription, coupon = (
|
||||
source.partition(f"def {name}(")[2].partition("\n\n\n")[0]
|
||||
for name in ("subscription_get_subscription_info", "coupon_list_stripe_coupons")
|
||||
)
|
||||
assert "errors=BILLING_SUBSCRIPTION_ERRORS," in subscription
|
||||
assert "errors=BILLING_COUPON_ERRORS," in coupon
|
||||
assert "class BillingCouponUpstreamError(BillingUpstreamError):" in source
|
||||
|
||||
|
||||
def test_long_operation_docstring_is_wrapped() -> None:
|
||||
allowed = generator.AllowedOperation("GET", f"/v1/subscription/{'x' * 80}", "BILLING")
|
||||
operation = {
|
||||
"operationId": "BillingSubscription_GetSubscriptionInfo",
|
||||
"responses": {"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/Reply"}}}}},
|
||||
}
|
||||
|
||||
lines = generator.render_operation("billing", allowed, operation)
|
||||
|
||||
assert lines[1] == f' """GET {allowed.path}\n\n BillingSubscription_GetSubscriptionInfo\n """'
|
||||
assert all(len(line) <= generator.LINE_LENGTH for line in "\n".join(lines).splitlines())
|
||||
|
||||
|
||||
@pytest.mark.usefixtures("subscription_info_only")
|
||||
def test_upstream_required_message_field_is_non_null() -> None:
|
||||
source = _source_spec()
|
||||
source["components"]["schemas"]["dify.saas.api.billing.GetSubscriptionInfoReply"]["required"] = ["members"]
|
||||
|
||||
snapshot = generator.build_snapshot("billing", source, "abc123")
|
||||
schema = snapshot["components"]["schemas"]["GetSubscriptionInfoReply"]
|
||||
|
||||
assert schema["properties"]["members"] == {"$ref": "#/components/schemas/Quota"}
|
||||
assert schema["required"] == ["plan", "paid_period_end", "members", "tags", "renewed_at"]
|
||||
assert "members: Quota\n" in generator.render_module("billing", snapshot)
|
||||
|
||||
|
||||
@pytest.mark.usefixtures("subscription_info_only")
|
||||
def test_snapshot_rejects_allowlisted_operation_missing_from_spec() -> None:
|
||||
source = _source_spec()
|
||||
del source["paths"]["/v1/subscription/info"]
|
||||
|
||||
with pytest.raises(generator.GenerationError, match="not in the dify-saas spec"):
|
||||
generator.build_snapshot("billing", source, "abc123")
|
||||
|
||||
|
||||
@pytest.mark.usefixtures("subscription_info_only")
|
||||
def test_snapshot_rejects_spec_without_error_schema() -> None:
|
||||
source = _source_spec()
|
||||
del source["components"]["schemas"]["dify.saas.api.billing.Error"]
|
||||
|
||||
with pytest.raises(generator.GenerationError, match="error schema dify.saas.api.billing.Error "):
|
||||
generator.build_snapshot("billing", source, "abc123")
|
||||
|
||||
|
||||
@pytest.mark.usefixtures("subscription_info_only")
|
||||
def test_snapshot_rejects_operation_without_its_service_reason_schema() -> None:
|
||||
source = _source_spec()
|
||||
del source["components"]["schemas"]["dify.saas.api.billing.BillingSubscriptionErrorReason"]
|
||||
|
||||
with pytest.raises(
|
||||
generator.GenerationError,
|
||||
match=r"BillingSubscription_GetSubscriptionInfo\) has no dify.saas.api.billing.BillingSubscriptionErrorReason",
|
||||
):
|
||||
generator.build_snapshot("billing", source, "abc123")
|
||||
|
||||
|
||||
@pytest.mark.usefixtures("subscription_info_only")
|
||||
@pytest.mark.parametrize("operation_id", ["GetSubscriptionInfo", "_GetSubscriptionInfo", "BillingSubscription_", ""])
|
||||
def test_snapshot_rejects_operation_id_without_service_prefix(operation_id: str) -> None:
|
||||
source = _source_spec()
|
||||
source["paths"]["/v1/subscription/info"]["get"]["operationId"] = operation_id
|
||||
|
||||
with pytest.raises(generator.GenerationError, match="has no `<Service>_` prefix"):
|
||||
generator.build_snapshot("billing", source, "abc123")
|
||||
|
||||
|
||||
@pytest.mark.usefixtures("subscription_info_only")
|
||||
def test_rendering_rejects_snapshot_whose_reason_schemas_drift_from_its_operations() -> None:
|
||||
snapshot = generator.build_snapshot("billing", _source_spec(), "abc123")
|
||||
schemas = snapshot["components"]["schemas"]
|
||||
schemas["BillingCouponErrorReason"] = {"enum": [""], "type": "string"}
|
||||
|
||||
with pytest.raises(generator.GenerationError, match=r"unused \['BillingCouponErrorReason'\]"):
|
||||
generator.render_module("billing", snapshot)
|
||||
|
||||
del schemas["BillingCouponErrorReason"], schemas["BillingSubscriptionErrorReason"]
|
||||
|
||||
with pytest.raises(generator.GenerationError, match=r"missing \['BillingSubscriptionErrorReason'\]"):
|
||||
generator.render_module("billing", snapshot)
|
||||
|
||||
|
||||
@pytest.mark.usefixtures("subscription_info_only")
|
||||
def test_rendering_rejects_error_body_that_drifts_from_the_transport() -> None:
|
||||
source = _source_spec()
|
||||
source["components"]["schemas"]["dify.saas.api.billing.Error"]["properties"]["details"] = {"type": "string"}
|
||||
snapshot = generator.build_snapshot("billing", source, "abc123")
|
||||
|
||||
with pytest.raises(generator.GenerationError, match="update UpstreamErrorBody"):
|
||||
generator.render_module("billing", snapshot)
|
||||
|
||||
|
||||
def test_committed_snapshots_keep_only_the_reasons_of_called_services() -> None:
|
||||
reason_schemas = {
|
||||
service: {
|
||||
name: schema["enum"]
|
||||
for name, schema in generator.load_snapshot(service)["components"]["schemas"].items()
|
||||
if name.endswith("ErrorReason")
|
||||
}
|
||||
for service in generator.SERVICES
|
||||
}
|
||||
|
||||
assert sorted(reason_schemas["billing"]) == [
|
||||
"BillingComplianceErrorReason",
|
||||
"BillingEducationErrorReason",
|
||||
"BillingInvoiceErrorReason",
|
||||
"BillingModelProviderErrorReason",
|
||||
"BillingQuotaErrorReason",
|
||||
"BillingSubscriptionErrorReason",
|
||||
]
|
||||
assert sorted(reason_schemas["saas"]) == [
|
||||
"AccountErrorReason",
|
||||
"SaasNetworkAccessPolicyErrorReason",
|
||||
"SaasNotificationErrorReason",
|
||||
"UtmErrorReason",
|
||||
]
|
||||
education = reason_schemas["billing"]["BillingEducationErrorReason"]
|
||||
assert "EDUCATION_VERIFY_FAILED" in education
|
||||
assert "COMPLIANCE_DOCUMENT_NOT_FOUND" not in education
|
||||
assert "NETWORK_ACCESS_VERSION_CONFLICT" in reason_schemas["saas"]["SaasNetworkAccessPolicyErrorReason"]
|
||||
assert "NETWORK_ACCESS_VERSION_CONFLICT" not in reason_schemas["saas"]["AccountErrorReason"]
|
||||
|
||||
|
||||
def test_committed_client_matches_snapshots() -> None:
|
||||
assert generator.check(generator.expected_files({s: generator.load_snapshot(s) for s in generator.SERVICES})) == 0
|
||||
@@ -0,0 +1,766 @@
|
||||
"""Tests for pinned KnowledgeFS declaration validation."""
|
||||
|
||||
import json
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
from copy import deepcopy
|
||||
from pathlib import Path
|
||||
from typing import cast
|
||||
|
||||
import pytest
|
||||
|
||||
from dev import generate_knowledge_fs_contract as contract_validator
|
||||
from dev.generate_knowledge_fs_contract import ContractDeclaration, validate_declarations
|
||||
from dev.knowledge_fs_product_contract import (
|
||||
CapabilityOperationRuntimeContract,
|
||||
ProductOperationRuntimeContract,
|
||||
parse_capability_operation_policy,
|
||||
parse_product_operation_gap_manifest,
|
||||
parse_product_operation_manifest,
|
||||
validate_product_operation_contracts,
|
||||
)
|
||||
|
||||
|
||||
def test_contract_cli_updates_checks_and_detects_openapi_drift(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
workspace = tmp_path / "dify"
|
||||
repository = tmp_path / "standalone-private-knowledge-fs"
|
||||
contracts = repository / "contracts"
|
||||
api_root = workspace / "api"
|
||||
contracts.mkdir(parents=True)
|
||||
api_root.mkdir(parents=True)
|
||||
subprocess.run(["git", "init", "--quiet"], cwd=repository, check=True)
|
||||
(repository / "package.json").write_text('{"scripts":{"capability:export":"fixture","openapi:export":"fixture"}}\n')
|
||||
repository_contracts = Path(__file__).resolve().parents[3] / "knowledge-fs-contract"
|
||||
for name in ("dify-capability-v2-auth-profile.json", "dify-capability-v2-test-vector.json"):
|
||||
(contracts / name).write_bytes((repository_contracts / name).read_bytes())
|
||||
product_path = api_root / "knowledge-fs-product-operations.json"
|
||||
product_path.write_text(json.dumps(fixture_product_manifest()) + "\n")
|
||||
gaps_path = api_root / "knowledge-fs-product-operation-gaps.json"
|
||||
gaps_path.write_text(json.dumps(fixture_product_gap_manifest()) + "\n")
|
||||
subprocess.run(["git", "add", "."], cwd=repository, check=True)
|
||||
subprocess.run(
|
||||
[
|
||||
"git",
|
||||
"-c",
|
||||
"user.email=contract-test@example.com",
|
||||
"-c",
|
||||
"user.name=Contract Test",
|
||||
"commit",
|
||||
"--quiet",
|
||||
"-m",
|
||||
"fixture",
|
||||
],
|
||||
cwd=repository,
|
||||
check=True,
|
||||
)
|
||||
source_commit = contract_validator.run("git", "rev-parse", "HEAD", cwd=repository).strip()
|
||||
source_tree = contract_validator.run("git", "rev-parse", "HEAD^{tree}", cwd=repository).strip()
|
||||
executable_directory = tmp_path / "bin"
|
||||
executable_directory.mkdir()
|
||||
fake_pnpm = executable_directory / "pnpm"
|
||||
write_fake_pnpm(fake_pnpm, complete_contract_document(), fixture_capability_policy_document())
|
||||
monkeypatch.setenv("PATH", f"{executable_directory}{os.pathsep}{os.environ['PATH']}")
|
||||
monkeypatch.setattr(contract_validator, "product_operation_runtime_contracts", fixture_product_operations)
|
||||
monkeypatch.setattr(contract_validator, "capability_operation_runtime_contracts", fixture_capability_operations)
|
||||
monkeypatch.setattr(
|
||||
sys,
|
||||
"argv",
|
||||
["generate", "--workspace-root", str(workspace), "--update-lock", "--knowledge-fs-root", str(repository)],
|
||||
)
|
||||
contract_validator.main()
|
||||
lock_path = api_root / "knowledge-fs-contract.lock.json"
|
||||
updated_lock = json.loads(lock_path.read_text())
|
||||
assert updated_lock["schemaVersion"] == 6
|
||||
assert updated_lock["sourceCommit"] == source_commit
|
||||
assert updated_lock["sourceTree"] == source_tree
|
||||
contract_validator.parse_contract_lock(updated_lock)
|
||||
pin_root = workspace / contract_validator.PIN_RELATIVE_PATH
|
||||
assert {path.suffix for path in pin_root.iterdir()} == {".json"}
|
||||
|
||||
monkeypatch.setattr(sys, "argv", ["generate", "--workspace-root", str(workspace), "--check"])
|
||||
# A consumer's Dify checkout has neither the private source checkout nor pnpm/git access.
|
||||
repository.rename(tmp_path / "unavailable-source")
|
||||
|
||||
def disallow_subprocess(*_args: object, **_kwargs: object) -> None:
|
||||
raise AssertionError("--check must use only pinned artifacts and Python runtime declarations")
|
||||
|
||||
monkeypatch.setattr(subprocess, "run", disallow_subprocess)
|
||||
contract_validator.main()
|
||||
|
||||
with monkeypatch.context() as registry_drift:
|
||||
registry_drift.setattr(
|
||||
contract_validator, "console_contract_declarations", lambda: (declaration(method="DELETE"),)
|
||||
)
|
||||
with pytest.raises(ValueError, match="listKnowledgeSpaces.*method.*expected.*received"):
|
||||
contract_validator.main()
|
||||
|
||||
# Every artifact is byte-pinned, including policy bindings and exact source provenance.
|
||||
for path, field in (
|
||||
(pin_root / contract_validator.OPENAPI_FILENAME, "openapiSha256"),
|
||||
(pin_root / contract_validator.CAPABILITY_POLICY_FILENAME, "capabilityPolicySha256"),
|
||||
(pin_root / contract_validator.PROVENANCE_FILENAME, "sourceProvenanceSha256"),
|
||||
(pin_root / "dify-capability-v2-auth-profile.json", "capabilityV2AuthManifestSha256"),
|
||||
(pin_root / "dify-capability-v2-test-vector.json", "capabilityV2AuthTestVectorSha256"),
|
||||
(product_path, "productOperationManifestSha256"),
|
||||
(gaps_path, "productOperationGapManifestSha256"),
|
||||
):
|
||||
original = path.read_bytes()
|
||||
path.write_bytes(original + b"\n")
|
||||
with pytest.raises(RuntimeError, match=f"contract lock field {field} drifted"):
|
||||
contract_validator.main()
|
||||
path.write_bytes(original)
|
||||
|
||||
openapi_path = pin_root / contract_validator.OPENAPI_FILENAME
|
||||
original = openapi_path.read_bytes()
|
||||
for change in ("schema", "query", "body", "response", "security", "deprecation"):
|
||||
document = complete_contract_document()
|
||||
if change == "schema":
|
||||
document["components"] = {"schemas": {"KnowledgeSpace": {"type": "object"}}}
|
||||
elif change == "query":
|
||||
openapi_operation(document, "get")["parameters"].append(
|
||||
{"in": "query", "name": "limit", "schema": {"maximum": 200, "type": "integer"}}
|
||||
)
|
||||
elif change == "body":
|
||||
openapi_operation(document, "post")["requestBody"] = {
|
||||
"content": {"application/json": {"schema": {"required": ["name"], "type": "object"}}}
|
||||
}
|
||||
elif change == "response":
|
||||
responses = openapi_operation(document, "post")["responses"]
|
||||
responses["201"] = responses.pop("200")
|
||||
elif change == "security":
|
||||
openapi_operation(document, "get")["security"] = []
|
||||
else:
|
||||
openapi_operation(document, "get")["deprecated"] = True
|
||||
openapi_path.write_text(json.dumps(document))
|
||||
with pytest.raises(RuntimeError, match="contract lock field openapiSha256 drifted"):
|
||||
contract_validator.main()
|
||||
openapi_path.write_bytes(original)
|
||||
contract_validator.main()
|
||||
|
||||
|
||||
def test_capability_v2_contract_rejects_cross_language_security_drift() -> None:
|
||||
contracts = Path(__file__).resolve().parents[3] / "knowledge-fs-contract"
|
||||
manifest = json.loads((contracts / "dify-capability-v2-auth-profile.json").read_text())
|
||||
vector = json.loads((contracts / "dify-capability-v2-test-vector.json").read_text())
|
||||
|
||||
contract_validator.validate_capability_v2_auth_manifest(manifest)
|
||||
contract_validator.validate_capability_v2_auth_test_vector(vector, manifest)
|
||||
|
||||
drift_cases = (
|
||||
("control space", ("expectedClaims", "control_space_id"), "other-control-space"),
|
||||
("caller", ("expectedClaims", "caller_kind"), "service"),
|
||||
("parent", ("expectedClaims", "resource", "parent_id"), "other-space"),
|
||||
("kid", ("protectedHeader", "kid"), "other-key"),
|
||||
)
|
||||
for _label, path, replacement in drift_cases:
|
||||
drifted = deepcopy(vector)
|
||||
target = drifted
|
||||
for segment in path[:-1]:
|
||||
target = target[segment]
|
||||
target[path[-1]] = replacement
|
||||
with pytest.raises(ValueError, match="Capability v2 test vector"):
|
||||
contract_validator.validate_capability_v2_auth_test_vector(drifted, manifest)
|
||||
|
||||
signature_drift = deepcopy(vector)
|
||||
signature_drift["token"] = f"{signature_drift['token'][:-1]}A"
|
||||
with pytest.raises(ValueError, match="signature is invalid"):
|
||||
contract_validator.validate_capability_v2_auth_test_vector(signature_drift, manifest)
|
||||
|
||||
|
||||
def test_capability_v2_is_the_only_pinned_production_auth_profile() -> None:
|
||||
contracts = Path(__file__).resolve().parents[3] / "knowledge-fs-contract"
|
||||
active = json.loads((contracts / "dify-capability-v2-auth-profile.json").read_text())
|
||||
|
||||
contract_validator.validate_capability_v2_auth_manifest(active)
|
||||
assert active["active"] is True
|
||||
assert active["schemaVersion"] == 3
|
||||
assert "replacesProfile" not in active
|
||||
assert not (contracts / "dify-auth-profile.json").exists()
|
||||
assert not (contracts / "dify-auth-test-vector.json").exists()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("change", ["unstaged", "staged", "untracked"])
|
||||
def test_contract_update_rejects_uncommitted_source(tmp_path: Path, change: str) -> None:
|
||||
subprocess.run(["git", "init", "--quiet"], cwd=tmp_path, check=True)
|
||||
source = tmp_path / "source.ts"
|
||||
source.write_text("export const value = 1;\n")
|
||||
subprocess.run(["git", "add", "."], cwd=tmp_path, check=True)
|
||||
subprocess.run(
|
||||
[
|
||||
"git",
|
||||
"-c",
|
||||
"user.email=contract-test@example.com",
|
||||
"-c",
|
||||
"user.name=Contract Test",
|
||||
"commit",
|
||||
"--quiet",
|
||||
"-m",
|
||||
"fixture",
|
||||
],
|
||||
cwd=tmp_path,
|
||||
check=True,
|
||||
)
|
||||
contract_validator.ensure_clean_knowledge_fs_worktree(tmp_path)
|
||||
if change == "untracked":
|
||||
(tmp_path / "untracked.ts").write_text("export const x = true;\n")
|
||||
else:
|
||||
source.write_text("export const value = 2;\n")
|
||||
if change == "staged":
|
||||
subprocess.run(["git", "add", "."], cwd=tmp_path, check=True)
|
||||
with pytest.raises(RuntimeError, match="staged, unstaged or untracked changes"):
|
||||
contract_validator.export_contract(tmp_path, tmp_path / "output")
|
||||
|
||||
|
||||
def test_contract_update_requires_explicit_source_and_check_rejects_source(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
for arguments in (["--update-lock"], ["--check", "--knowledge-fs-root", "/private/source"]):
|
||||
monkeypatch.setattr(sys, "argv", ["generate", *arguments])
|
||||
with pytest.raises(SystemExit):
|
||||
contract_validator.main()
|
||||
|
||||
|
||||
def test_product_operation_manifest_must_cover_ready_and_gap_runtime_registry() -> None:
|
||||
manifest = fixture_product_manifest()
|
||||
manifest["operations"] = manifest["operations"][:-1]
|
||||
|
||||
with pytest.raises(ValueError, match="completeness drifted.*createUploadSession"):
|
||||
validate_fixture_product_contracts(manifest=manifest)
|
||||
|
||||
|
||||
def test_product_operation_manifest_must_match_capability_and_openapi_fields() -> None:
|
||||
manifest = fixture_product_manifest()
|
||||
manifest["operations"][0]["method"] = "POST"
|
||||
|
||||
with pytest.raises(ValueError, match="getSpace field method drifted"):
|
||||
validate_fixture_product_contracts(manifest=manifest)
|
||||
|
||||
|
||||
def test_internal_capability_operation_requires_an_explicit_exclusion() -> None:
|
||||
gap_manifest = fixture_product_gap_manifest()
|
||||
gap_manifest["internalKfsOperationExclusions"] = []
|
||||
|
||||
with pytest.raises(ValueError, match="lifecycle operations must be explicit internal exclusions"):
|
||||
validate_fixture_product_contracts(gap_manifest=gap_manifest)
|
||||
|
||||
|
||||
def test_required_product_operation_must_exist_exactly_once() -> None:
|
||||
document = {
|
||||
"paths": {
|
||||
"/knowledge-spaces": {
|
||||
"get": operation("knowledge-spaces:read", "listKnowledgeSpaces"),
|
||||
},
|
||||
"/spaces": {
|
||||
"get": operation("knowledge-spaces:read", "listKnowledgeSpaces"),
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
with pytest.raises(ValueError, match="listKnowledgeSpaces.*exactly once.*found 2"):
|
||||
contract_validator.validate_required_product_operations(document, ["listKnowledgeSpaces"])
|
||||
|
||||
|
||||
def test_contract_script_loads_runtime_registry_outside_api_directory(tmp_path: Path) -> None:
|
||||
script_path = Path(contract_validator.__file__).resolve()
|
||||
command = (
|
||||
"import runpy; "
|
||||
f"namespace = runpy.run_path({str(script_path)!r}); "
|
||||
"print(len(namespace['console_contract_declarations']()))"
|
||||
)
|
||||
|
||||
result = subprocess.run(
|
||||
[sys.executable, "-c", command],
|
||||
cwd=tmp_path,
|
||||
check=True,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
|
||||
assert result.stdout.strip() == "0"
|
||||
|
||||
|
||||
def test_validate_declarations_accepts_matching_contract() -> None:
|
||||
route = operation("knowledge-spaces:read", "listKnowledgeSpaces")
|
||||
route["parameters"] = [{"in": "header", "name": "X-Trace-Id"}]
|
||||
route["responses"] = {
|
||||
"200": {
|
||||
"content": {"application/json": {}},
|
||||
"headers": {"X-Trace-Id": {}},
|
||||
}
|
||||
}
|
||||
document = {"paths": {"/knowledge-spaces": {"get": route}}}
|
||||
|
||||
validate_declarations(
|
||||
document,
|
||||
(
|
||||
declaration(
|
||||
request_headers=("x-trace-id",),
|
||||
response_headers=("x-trace-id",),
|
||||
),
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
def test_raw_console_proxy_registry_is_removed() -> None:
|
||||
assert contract_validator.console_contract_declarations() == ()
|
||||
|
||||
|
||||
def fixture_product_operations() -> tuple[ProductOperationRuntimeContract, ...]:
|
||||
return (
|
||||
ProductOperationRuntimeContract(
|
||||
action="knowledge_spaces.read",
|
||||
kfs_operation_id="getKnowledgeSpace",
|
||||
max_request_bytes=0,
|
||||
max_response_bytes=262_144,
|
||||
method="GET",
|
||||
path="/knowledge-spaces/{id}",
|
||||
product_operation_id="getSpace",
|
||||
ready=True,
|
||||
resource="knowledge_space",
|
||||
stream_kind="json",
|
||||
transport="json",
|
||||
),
|
||||
ProductOperationRuntimeContract(
|
||||
action="upload_sessions.create",
|
||||
kfs_operation_id="createUploadSession",
|
||||
max_request_bytes=65_536,
|
||||
max_response_bytes=65_536,
|
||||
method="POST",
|
||||
path="/knowledge-spaces/{id}/upload-sessions",
|
||||
product_operation_id="createUploadSession",
|
||||
ready=True,
|
||||
resource="knowledge_space",
|
||||
stream_kind="json",
|
||||
transport="json",
|
||||
),
|
||||
ProductOperationRuntimeContract(
|
||||
action="documents.create",
|
||||
kfs_operation_id="uploadDocument",
|
||||
max_request_bytes=0,
|
||||
max_response_bytes=0,
|
||||
method="POST",
|
||||
path="/knowledge-spaces/{id}/documents",
|
||||
product_operation_id="createDocument",
|
||||
ready=False,
|
||||
resource="knowledge_space",
|
||||
stream_kind="buffered-multipart",
|
||||
transport="multipart",
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
def fixture_capability_operations() -> tuple[CapabilityOperationRuntimeContract, ...]:
|
||||
return (
|
||||
CapabilityOperationRuntimeContract(
|
||||
action="knowledge_spaces.read",
|
||||
allowed_caller_kinds=("interactive", "service"),
|
||||
method="GET",
|
||||
operation_id="getKnowledgeSpace",
|
||||
path="/knowledge-spaces/{id}",
|
||||
resource="knowledge_space",
|
||||
),
|
||||
CapabilityOperationRuntimeContract(
|
||||
action="upload_sessions.create",
|
||||
allowed_caller_kinds=("interactive", "service"),
|
||||
method="POST",
|
||||
operation_id="createUploadSession",
|
||||
path="/knowledge-spaces/{id}/upload-sessions",
|
||||
resource="knowledge_space",
|
||||
),
|
||||
CapabilityOperationRuntimeContract(
|
||||
action="documents.create",
|
||||
allowed_caller_kinds=("interactive", "service"),
|
||||
method="POST",
|
||||
operation_id="uploadDocument",
|
||||
path="/knowledge-spaces/{id}/documents",
|
||||
resource="knowledge_space",
|
||||
),
|
||||
CapabilityOperationRuntimeContract(
|
||||
action="dify_integration.activate",
|
||||
allowed_caller_kinds=("internal_worker",),
|
||||
method="POST",
|
||||
operation_id="activateDifyWorkspaceIntegration",
|
||||
path="/internal/dify-integration/activate",
|
||||
resource="namespace",
|
||||
),
|
||||
CapabilityOperationRuntimeContract(
|
||||
action="dify_integration.freeze",
|
||||
allowed_caller_kinds=("internal_worker",),
|
||||
method="POST",
|
||||
operation_id="freezeDifyWorkspaceIntegration",
|
||||
path="/internal/dify-integration/freeze",
|
||||
resource="namespace",
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
def fixture_product_manifest() -> dict[str, object]:
|
||||
return {
|
||||
"schemaVersion": 2,
|
||||
"operations": [
|
||||
{
|
||||
"productOperationId": "getSpace",
|
||||
"kfsOperationId": "getKnowledgeSpace",
|
||||
"method": "GET",
|
||||
"path": "/knowledge-spaces/{id}",
|
||||
"action": "knowledge_spaces.read",
|
||||
"resource": "knowledge_space",
|
||||
"transport": "json",
|
||||
"stream": {"productKind": "json", "kfsResponseKind": "buffered"},
|
||||
"limits": {
|
||||
"productMaxRequestBytes": 0,
|
||||
"productMaxResponseBytes": 262_144,
|
||||
"kfsMaxResponseBytes": 1_048_576,
|
||||
},
|
||||
},
|
||||
{
|
||||
"productOperationId": "createUploadSession",
|
||||
"kfsOperationId": "createUploadSession",
|
||||
"method": "POST",
|
||||
"path": "/knowledge-spaces/{id}/upload-sessions",
|
||||
"action": "upload_sessions.create",
|
||||
"resource": "knowledge_space",
|
||||
"transport": "json",
|
||||
"stream": {"productKind": "json", "kfsResponseKind": "buffered"},
|
||||
"limits": {
|
||||
"productMaxRequestBytes": 65_536,
|
||||
"productMaxResponseBytes": 65_536,
|
||||
"kfsMaxResponseBytes": 1_048_576,
|
||||
},
|
||||
},
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
def fixture_product_gap_manifest() -> dict[str, object]:
|
||||
return {
|
||||
"schemaVersion": 2,
|
||||
"gaps": [
|
||||
{
|
||||
"productOperationId": "createDocument",
|
||||
"kfsOperationId": "uploadDocument",
|
||||
"method": "POST",
|
||||
"path": "/knowledge-spaces/{id}/documents",
|
||||
"action": "documents.create",
|
||||
"resource": "knowledge_space",
|
||||
"transport": "multipart",
|
||||
"stream": {"productKind": "buffered-multipart", "kfsResponseKind": "buffered"},
|
||||
"limits": {
|
||||
"productMaxRequestBytes": 0,
|
||||
"productMaxResponseBytes": 0,
|
||||
"kfsMaxResponseBytes": 1_048_576,
|
||||
},
|
||||
"reasonCode": "NON_HOMOMORPHIC_MULTIPART_TRANSPORT",
|
||||
"reason": "The fixture models the legacy multipart gap.",
|
||||
"replacementProductOperationIds": ["createUploadSession"],
|
||||
}
|
||||
],
|
||||
"internalKfsOperationExclusions": [
|
||||
{
|
||||
"kfsOperationId": "activateDifyWorkspaceIntegration",
|
||||
"reasonCode": "INTERNAL_CONTROL_PLANE_ONLY",
|
||||
"reason": "The fixture keeps activation internal-only.",
|
||||
},
|
||||
{
|
||||
"kfsOperationId": "freezeDifyWorkspaceIntegration",
|
||||
"reasonCode": "INTERNAL_CONTROL_PLANE_ONLY",
|
||||
"reason": "The fixture keeps freeze internal-only.",
|
||||
},
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
def fixture_capability_policy_document() -> dict[str, object]:
|
||||
bindings = {
|
||||
"getKnowledgeSpace": {"pathParameter": "id"},
|
||||
"createUploadSession": {"pathParameter": "id"},
|
||||
"uploadDocument": {"pathParameter": "id"},
|
||||
"activateDifyWorkspaceIntegration": {"namespace": True},
|
||||
"freezeDifyWorkspaceIntegration": {"namespace": True},
|
||||
}
|
||||
return {
|
||||
"schemaVersion": 1,
|
||||
"operations": [
|
||||
{
|
||||
"action": operation.action,
|
||||
"allowedCallerKinds": list(operation.allowed_caller_kinds),
|
||||
"method": operation.method,
|
||||
"operationId": operation.operation_id,
|
||||
"parentResourceBinding": None,
|
||||
"path": operation.path,
|
||||
"resourceBinding": bindings[operation.operation_id],
|
||||
"resourceType": operation.resource,
|
||||
}
|
||||
for operation in fixture_capability_operations()
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
def validate_fixture_product_contracts(
|
||||
*,
|
||||
gap_manifest: dict[str, object] | None = None,
|
||||
manifest: dict[str, object] | None = None,
|
||||
) -> None:
|
||||
validate_product_operation_contracts(
|
||||
capability_operations=fixture_capability_operations(),
|
||||
capability_policy=parse_capability_operation_policy(fixture_capability_policy_document()),
|
||||
document=complete_contract_document(),
|
||||
gap_manifest=parse_product_operation_gap_manifest(gap_manifest or fixture_product_gap_manifest()),
|
||||
manifest=parse_product_operation_manifest(manifest or fixture_product_manifest()),
|
||||
product_operations=fixture_product_operations(),
|
||||
)
|
||||
|
||||
|
||||
def console_registry_document() -> dict[str, object]:
|
||||
list_route = operation("knowledge-spaces:read", "listKnowledgeSpaces")
|
||||
create_route = operation("knowledge-spaces:write", "createKnowledgeSpace")
|
||||
for route in (list_route, create_route):
|
||||
route["parameters"] = [{"in": "header", "name": "X-Trace-Id"}]
|
||||
route["responses"] = {
|
||||
"200": {
|
||||
"content": {"application/json": {}},
|
||||
"headers": {"X-Trace-Id": {}},
|
||||
}
|
||||
}
|
||||
return {"paths": {"/knowledge-spaces": {"get": list_route, "post": create_route}}}
|
||||
|
||||
|
||||
def complete_contract_document() -> dict[str, object]:
|
||||
document = console_registry_document()
|
||||
paths = cast(dict[str, dict[str, dict[str, object]]], document["paths"])
|
||||
paths["/knowledge-spaces/{id}"] = {
|
||||
"get": operation("knowledge-spaces:read", "getKnowledgeSpace"),
|
||||
}
|
||||
paths["/knowledge-spaces/{id}/upload-sessions"] = {
|
||||
"post": operation("knowledge-spaces:write", "createUploadSession"),
|
||||
}
|
||||
paths["/knowledge-spaces/{id}/documents"] = {
|
||||
"post": operation("knowledge-spaces:write", "uploadDocument"),
|
||||
}
|
||||
paths["/internal/dify-integration/activate"] = {
|
||||
"post": operation(None, "activateDifyWorkspaceIntegration"),
|
||||
}
|
||||
paths["/internal/dify-integration/freeze"] = {
|
||||
"post": operation(None, "freezeDifyWorkspaceIntegration"),
|
||||
}
|
||||
return document
|
||||
|
||||
|
||||
def openapi_operation(document: dict[str, object], method: str) -> dict[str, object]:
|
||||
paths = cast(dict[str, dict[str, dict[str, object]]], document["paths"])
|
||||
return paths["/knowledge-spaces"][method]
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("field", "value"),
|
||||
[
|
||||
("method", "POST"),
|
||||
("path", "spaces"),
|
||||
("required_scope", "knowledge-spaces:write"),
|
||||
("response_kind", "stream"),
|
||||
("max_response_bytes", 2_097_152),
|
||||
("request_headers", ("authorization",)),
|
||||
("response_headers", ("cache-control",)),
|
||||
("response_media_types", ("text/event-stream",)),
|
||||
],
|
||||
)
|
||||
def test_validate_declarations_reports_contract_field_drift(field: str, value: object) -> None:
|
||||
document = {
|
||||
"paths": {
|
||||
"/knowledge-spaces": {
|
||||
"get": operation("knowledge-spaces:read", "listKnowledgeSpaces"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
with pytest.raises(ValueError, match=rf"listKnowledgeSpaces.*{field}.*expected.*received"):
|
||||
validate_declarations(document, (declaration(**{field: value}),))
|
||||
|
||||
|
||||
def test_validate_declarations_rejects_unknown_operation_id() -> None:
|
||||
with pytest.raises(ValueError, match="no operationId: listKnowledgeSpaces"):
|
||||
validate_declarations({"paths": {}}, (declaration(),))
|
||||
|
||||
|
||||
def test_validate_declarations_rejects_duplicate_declared_operation_ids() -> None:
|
||||
document = {
|
||||
"paths": {
|
||||
"/knowledge-spaces": {
|
||||
"get": operation("knowledge-spaces:read", "listKnowledgeSpaces"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
with pytest.raises(ValueError, match="registry has duplicate operationId: listKnowledgeSpaces"):
|
||||
validate_declarations(document, (declaration(), declaration()))
|
||||
|
||||
|
||||
def test_validate_declarations_rejects_duplicate_upstream_operation_ids() -> None:
|
||||
document = {
|
||||
"paths": {
|
||||
"/knowledge-spaces": {
|
||||
"get": operation("knowledge-spaces:read", "listKnowledgeSpaces"),
|
||||
},
|
||||
"/spaces": {
|
||||
"get": operation("knowledge-spaces:read", "listKnowledgeSpaces"),
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
with pytest.raises(ValueError, match="OpenAPI has duplicate operationId: listKnowledgeSpaces"):
|
||||
validate_declarations(document, (declaration(),))
|
||||
|
||||
|
||||
def test_validate_declarations_ignores_undeclared_operations() -> None:
|
||||
document = {
|
||||
"paths": {
|
||||
"/knowledge-spaces": {
|
||||
"get": operation("knowledge-spaces:read", "listKnowledgeSpaces"),
|
||||
},
|
||||
"/internal-maintenance": {
|
||||
"head": {"responses": {"200": {}}},
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
validate_declarations(document, (declaration(),))
|
||||
|
||||
|
||||
def test_validate_declarations_preserves_public_operation_scope() -> None:
|
||||
document = {"paths": {"/health": {"get": operation(None, "getHealth", security=[])}}}
|
||||
|
||||
validate_declarations(
|
||||
document,
|
||||
(
|
||||
declaration(
|
||||
operation_id="getHealth",
|
||||
path="health",
|
||||
required_scope=None,
|
||||
),
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
def test_validate_declarations_accepts_inherited_bearer_security() -> None:
|
||||
route = operation("knowledge-spaces:read", "listKnowledgeSpaces")
|
||||
route.pop("security")
|
||||
document = {
|
||||
"paths": {"/knowledge-spaces": {"get": route}},
|
||||
"security": [{"bearerAuth": []}],
|
||||
}
|
||||
|
||||
validate_declarations(document, (declaration(),))
|
||||
|
||||
|
||||
@pytest.mark.parametrize("security", [None, [{"apiKeyAuth": []}]])
|
||||
def test_validate_declarations_rejects_missing_or_replaced_bearer_security(security: object) -> None:
|
||||
route = operation("knowledge-spaces:read", "listKnowledgeSpaces")
|
||||
route.pop("security")
|
||||
document = {"paths": {"/knowledge-spaces": {"get": route}}}
|
||||
if security is not None:
|
||||
document["security"] = security
|
||||
|
||||
with pytest.raises(ValueError, match="effective security.*bearerAuth"):
|
||||
validate_declarations(document, (declaration(),))
|
||||
|
||||
|
||||
def test_validate_declarations_rejects_required_scope_on_a_public_operation() -> None:
|
||||
route = operation(
|
||||
"knowledge-spaces:read",
|
||||
"listKnowledgeSpaces",
|
||||
security=[],
|
||||
)
|
||||
|
||||
with pytest.raises(ValueError, match="public.*required scope"):
|
||||
validate_declarations({"paths": {"/knowledge-spaces": {"get": route}}}, (declaration(),))
|
||||
|
||||
|
||||
def test_validate_declarations_rejects_unsupported_declared_method() -> None:
|
||||
document = {
|
||||
"paths": {
|
||||
"/knowledge-spaces": {
|
||||
"head": operation("knowledge-spaces:read", "listKnowledgeSpaces"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
with pytest.raises(ValueError, match="does not support HEAD /knowledge-spaces"):
|
||||
validate_declarations(document, (declaration(method="HEAD"),))
|
||||
|
||||
|
||||
def test_validate_declarations_rejects_non_absolute_upstream_path() -> None:
|
||||
document = {
|
||||
"paths": {
|
||||
"knowledge-spaces": {
|
||||
"get": operation("knowledge-spaces:read", "listKnowledgeSpaces"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
with pytest.raises(ValueError, match="path must be absolute: knowledge-spaces"):
|
||||
validate_declarations(document, (declaration(),))
|
||||
|
||||
|
||||
@pytest.mark.parametrize("value", [None, True, 0, "1048576"])
|
||||
def test_validate_declarations_rejects_invalid_response_byte_limits(value: object) -> None:
|
||||
route = operation("knowledge-spaces:read", "listKnowledgeSpaces")
|
||||
route["x-knowledge-fs-max-response-bytes"] = value
|
||||
|
||||
with pytest.raises(ValueError, match="no valid response byte limit"):
|
||||
validate_declarations({"paths": {"/knowledge-spaces": {"get": route}}}, (declaration(),))
|
||||
|
||||
|
||||
def test_validate_declarations_rejects_request_header_references() -> None:
|
||||
route = operation("knowledge-spaces:read", "listKnowledgeSpaces")
|
||||
route["parameters"] = [{"$ref": "#/components/parameters/TraceId"}]
|
||||
|
||||
with pytest.raises(ValueError, match="request header references are not supported"):
|
||||
validate_declarations({"paths": {"/knowledge-spaces": {"get": route}}}, (declaration(),))
|
||||
|
||||
|
||||
def operation(scope: str | None, operation_id: str, **overrides: object) -> dict[str, object]:
|
||||
value: dict[str, object] = {
|
||||
"operationId": operation_id,
|
||||
"responses": {"200": {"content": {"application/json": {}}}},
|
||||
"x-knowledge-fs-max-response-bytes": 1_048_576,
|
||||
}
|
||||
if scope is not None:
|
||||
value["x-knowledge-fs-required-scope"] = scope
|
||||
value["security"] = [{"bearerAuth": []}]
|
||||
value.update(overrides)
|
||||
return value
|
||||
|
||||
|
||||
def declaration(**overrides: object) -> ContractDeclaration:
|
||||
value: dict[str, object] = {
|
||||
"operation_id": "listKnowledgeSpaces",
|
||||
"method": "GET",
|
||||
"path": "knowledge-spaces",
|
||||
"required_scope": "knowledge-spaces:read",
|
||||
"response_kind": "buffered",
|
||||
"max_response_bytes": 1_048_576,
|
||||
"request_headers": (),
|
||||
"response_headers": (),
|
||||
"response_media_types": ("application/json",),
|
||||
}
|
||||
value.update(overrides)
|
||||
return cast(ContractDeclaration, value)
|
||||
|
||||
|
||||
def write_fake_pnpm(
|
||||
path: Path,
|
||||
document: dict[str, object],
|
||||
capability_policy: dict[str, object],
|
||||
) -> None:
|
||||
documents = {
|
||||
"capability:export": json.dumps(capability_policy),
|
||||
"openapi:export": json.dumps(document),
|
||||
}
|
||||
path.write_text(
|
||||
"#!/usr/bin/env python3\n"
|
||||
"import sys\n"
|
||||
"from pathlib import Path\n"
|
||||
"output = Path(sys.argv[sys.argv.index('--output') + 1])\n"
|
||||
f"documents = {documents!r}\n"
|
||||
"output.write_text(documents[sys.argv[1]])\n"
|
||||
)
|
||||
path.chmod(0o755)
|
||||
@@ -0,0 +1,600 @@
|
||||
"""Unit tests for the Markdown API docs generator."""
|
||||
|
||||
import importlib.util
|
||||
import json
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from types import ModuleType
|
||||
|
||||
import pytest
|
||||
|
||||
|
||||
def _load_generate_swagger_markdown_docs_module() -> ModuleType:
|
||||
api_dir = Path(__file__).resolve().parents[3]
|
||||
script_path = api_dir / "dev" / "generate_swagger_markdown_docs.py"
|
||||
|
||||
spec = importlib.util.spec_from_file_location("generate_swagger_markdown_docs", script_path)
|
||||
assert spec
|
||||
assert spec.loader
|
||||
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
sys.modules[spec.name] = module
|
||||
spec.loader.exec_module(module) # type: ignore[attr-defined]
|
||||
return module
|
||||
|
||||
|
||||
def test_generate_markdown_docs_keeps_split_docs_and_merges_fastopenapi_into_console(
|
||||
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
|
||||
) -> None:
|
||||
module = _load_generate_swagger_markdown_docs_module()
|
||||
openapi_dir = tmp_path / "openapi"
|
||||
markdown_dir = tmp_path / "markdown"
|
||||
stale_combined_doc = markdown_dir / "api-reference.md"
|
||||
markdown_dir.mkdir()
|
||||
stale_combined_doc.write_text("stale", encoding="utf-8")
|
||||
|
||||
def write_specs(output_dir: Path) -> list[Path]:
|
||||
output_dir.mkdir(parents=True, exist_ok=True)
|
||||
paths = []
|
||||
for target in module.SPEC_TARGETS:
|
||||
path = output_dir / target.filename
|
||||
path.write_text("{}", encoding="utf-8")
|
||||
paths.append(path)
|
||||
return paths
|
||||
|
||||
def write_fastopenapi_specs(output_dir: Path) -> list[Path]:
|
||||
output_dir.mkdir(parents=True, exist_ok=True)
|
||||
path = output_dir / module.FASTOPENAPI_SPEC_TARGETS[0].filename
|
||||
path.write_text("{}", encoding="utf-8")
|
||||
return [path]
|
||||
|
||||
def convert_spec_to_markdown(spec_path: Path, markdown_path: Path) -> None:
|
||||
markdown_path.write_text(f"# {spec_path.stem}\n\n## Routes\n", encoding="utf-8")
|
||||
|
||||
monkeypatch.setattr(module, "generate_specs", write_specs)
|
||||
monkeypatch.setattr(module, "generate_fastopenapi_specs", write_fastopenapi_specs)
|
||||
monkeypatch.setattr(module, "_convert_spec_to_markdown", convert_spec_to_markdown)
|
||||
|
||||
written_paths = module.generate_markdown_docs(openapi_dir, markdown_dir)
|
||||
|
||||
assert [path.name for path in written_paths] == [
|
||||
"console-openapi.md",
|
||||
"web-openapi.md",
|
||||
"service-openapi.md",
|
||||
"openapi-openapi.md",
|
||||
]
|
||||
assert not stale_combined_doc.exists()
|
||||
assert not list(openapi_dir.glob("*.json"))
|
||||
|
||||
console_markdown = (markdown_dir / "console-openapi.md").read_text(encoding="utf-8")
|
||||
assert "## FastOpenAPI Preview (OpenAPI 3.1)" in console_markdown
|
||||
assert "### fastopenapi-console-openapi" in console_markdown
|
||||
assert "#### Routes" in console_markdown
|
||||
assert "FastOpenAPI Preview" not in (markdown_dir / "web-openapi.md").read_text(encoding="utf-8")
|
||||
assert "FastOpenAPI Preview" not in (markdown_dir / "service-openapi.md").read_text(encoding="utf-8")
|
||||
|
||||
|
||||
def test_generate_markdown_docs_only_removes_generated_specs_from_separate_swagger_dir(
|
||||
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
|
||||
) -> None:
|
||||
module = _load_generate_swagger_markdown_docs_module()
|
||||
swagger_dir = tmp_path / "swagger"
|
||||
markdown_dir = tmp_path / "markdown"
|
||||
swagger_dir.mkdir()
|
||||
existing_file = swagger_dir / "existing.txt"
|
||||
existing_file.write_text("keep me", encoding="utf-8")
|
||||
|
||||
def write_specs(output_dir: Path) -> list[Path]:
|
||||
output_dir.mkdir(parents=True, exist_ok=True)
|
||||
paths = []
|
||||
for target in module.SPEC_TARGETS:
|
||||
path = output_dir / target.filename
|
||||
path.write_text("{}", encoding="utf-8")
|
||||
paths.append(path)
|
||||
return paths
|
||||
|
||||
def write_fastopenapi_specs(output_dir: Path) -> list[Path]:
|
||||
output_dir.mkdir(parents=True, exist_ok=True)
|
||||
path = output_dir / module.FASTOPENAPI_SPEC_TARGETS[0].filename
|
||||
path.write_text("{}", encoding="utf-8")
|
||||
return [path]
|
||||
|
||||
def convert_spec_to_markdown(spec_path: Path, markdown_path: Path) -> None:
|
||||
markdown_path.write_text(f"# {spec_path.stem}\n", encoding="utf-8")
|
||||
|
||||
monkeypatch.setattr(module, "generate_specs", write_specs)
|
||||
monkeypatch.setattr(module, "generate_fastopenapi_specs", write_fastopenapi_specs)
|
||||
monkeypatch.setattr(module, "_convert_spec_to_markdown", convert_spec_to_markdown)
|
||||
|
||||
module.generate_markdown_docs(swagger_dir, markdown_dir)
|
||||
|
||||
assert existing_file.read_text(encoding="utf-8") == "keep me"
|
||||
assert not list(swagger_dir.glob("*.json"))
|
||||
|
||||
|
||||
def test_patch_union_schema_markdown_fills_converter_blank_schema_types(tmp_path: Path) -> None:
|
||||
module = _load_generate_swagger_markdown_docs_module()
|
||||
spec_path = tmp_path / "console-openapi.json"
|
||||
spec_path.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"components": {
|
||||
"schemas": {
|
||||
"FormInputConfig": {
|
||||
"oneOf": [
|
||||
{"$ref": "#/components/schemas/ParagraphInputConfig"},
|
||||
{"$ref": "#/components/schemas/SelectInputConfig"},
|
||||
{"$ref": "#/components/schemas/FileInputConfig"},
|
||||
],
|
||||
},
|
||||
"ParagraphInputConfig": {
|
||||
"properties": {
|
||||
"default": {
|
||||
"anyOf": [
|
||||
{"$ref": "#/components/schemas/StringSource"},
|
||||
{"type": "null"},
|
||||
],
|
||||
"default": None,
|
||||
},
|
||||
"output_variable_name": {"type": "string"},
|
||||
},
|
||||
},
|
||||
"SelectInputConfig": {
|
||||
"properties": {
|
||||
"option_source": {"$ref": "#/components/schemas/StringListSource"},
|
||||
},
|
||||
},
|
||||
"FileInputConfig": {
|
||||
"properties": {
|
||||
"allowed_file_types": {
|
||||
"type": "array",
|
||||
"items": {"$ref": "#/components/schemas/FileType"},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
markdown = """#### FormInputConfig
|
||||
|
||||
| Name | Type | Description | Required |
|
||||
| ---- | ---- | ----------- | -------- |
|
||||
| FormInputConfig | | | |
|
||||
|
||||
#### ParagraphInputConfig
|
||||
|
||||
| Name | Type | Description | Required |
|
||||
| ---- | ---- | ----------- | -------- |
|
||||
| default | | | No |
|
||||
| output_variable_name | string | | Yes |
|
||||
|
||||
#### SelectInputConfig
|
||||
|
||||
| Name | Type | Description | Required |
|
||||
| ---- | ---- | ----------- | -------- |
|
||||
| option_source | | | Yes |
|
||||
|
||||
#### FileInputConfig
|
||||
|
||||
| Name | Type | Description | Required |
|
||||
| ---- | ---- | ----------- | -------- |
|
||||
| allowed_file_types | | | No |
|
||||
"""
|
||||
|
||||
patched = module._patch_union_schema_markdown(markdown, spec_path)
|
||||
|
||||
assert (
|
||||
"| FormInputConfig | "
|
||||
"[ParagraphInputConfig](#paragraphinputconfig)<br>"
|
||||
"[SelectInputConfig](#selectinputconfig)<br>"
|
||||
"[FileInputConfig](#fileinputconfig) | | |"
|
||||
) in patched
|
||||
assert "| default | [StringSource](#stringsource) | | No |" in patched
|
||||
assert "| output_variable_name | string | | Yes |" in patched
|
||||
assert "| option_source | [StringListSource](#stringlistsource) | | Yes |" in patched
|
||||
assert "| allowed_file_types | [ [FileType](#filetype) ] | | No |" in patched
|
||||
|
||||
|
||||
def test_patch_union_schema_markdown_fills_regular_schema_union_property(tmp_path: Path) -> None:
|
||||
module = _load_generate_swagger_markdown_docs_module()
|
||||
spec_path = tmp_path / "service-openapi.json"
|
||||
spec_path.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"components": {
|
||||
"schemas": {
|
||||
"DocumentMetadataResponse": {
|
||||
"properties": {
|
||||
"id": {"type": "string"},
|
||||
"value": {
|
||||
"anyOf": [
|
||||
{"type": "string"},
|
||||
{"type": "integer"},
|
||||
{"type": "number"},
|
||||
{"type": "boolean"},
|
||||
{"type": "null"},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
markdown = """#### DocumentMetadataResponse
|
||||
|
||||
| Name | Type | Description | Required |
|
||||
| ---- | ---- | ----------- | -------- |
|
||||
| id | string | | Yes |
|
||||
| value | string | | No |
|
||||
"""
|
||||
|
||||
patched = module._patch_union_schema_markdown(markdown, spec_path)
|
||||
|
||||
assert "| value | string<br>integer<br>number<br>boolean | | No |" in patched
|
||||
|
||||
|
||||
def test_patch_union_schema_markdown_preserves_nullable_enum_values(tmp_path: Path) -> None:
|
||||
module = _load_generate_swagger_markdown_docs_module()
|
||||
spec_path = tmp_path / "console-openapi.json"
|
||||
spec_path.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"components": {
|
||||
"schemas": {
|
||||
"StepByStepTourStatePatchPayload": {
|
||||
"properties": {
|
||||
"task_id": {
|
||||
"anyOf": [
|
||||
{"enum": ["home", "studio"], "type": "string"},
|
||||
{"type": "null"},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
markdown = """#### StepByStepTourStatePatchPayload
|
||||
|
||||
| Name | Type | Description | Required |
|
||||
| ---- | ---- | ----------- | -------- |
|
||||
| task_id | string | Task ID | No |
|
||||
"""
|
||||
|
||||
patched = module._patch_union_schema_markdown(markdown, spec_path)
|
||||
|
||||
assert '| task_id | string, <br>**Available values:** "home", "studio" | Task ID | No |' in patched
|
||||
|
||||
|
||||
def test_patch_union_schema_markdown_fills_array_item_union_property(tmp_path: Path) -> None:
|
||||
module = _load_generate_swagger_markdown_docs_module()
|
||||
spec_path = tmp_path / "console-openapi.json"
|
||||
spec_path.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"components": {
|
||||
"schemas": {
|
||||
"MemberInviteResponse": {
|
||||
"properties": {
|
||||
"invitation_results": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"oneOf": [
|
||||
{"$ref": "#/components/schemas/MemberInviteSuccessResponse"},
|
||||
{"$ref": "#/components/schemas/MemberInviteAlreadyMemberResponse"},
|
||||
{"$ref": "#/components/schemas/MemberInviteFailedResponse"},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
markdown = """#### MemberInviteResponse
|
||||
|
||||
| Name | Type | Description | Required |
|
||||
| ---- | ---- | ----------- | -------- |
|
||||
| invitation_results | [ ] | | Yes |
|
||||
"""
|
||||
|
||||
patched = module._patch_union_schema_markdown(markdown, spec_path)
|
||||
|
||||
assert (
|
||||
"| invitation_results | [ "
|
||||
"[MemberInviteSuccessResponse](#memberinvitesuccessresponse)<br>"
|
||||
"[MemberInviteAlreadyMemberResponse](#memberinvitealreadymemberresponse)<br>"
|
||||
"[MemberInviteFailedResponse](#memberinvitefailedresponse) ] | | Yes |"
|
||||
) in patched
|
||||
|
||||
|
||||
def test_patch_union_schema_markdown_ignores_specs_without_schemas(tmp_path: Path) -> None:
|
||||
module = _load_generate_swagger_markdown_docs_module()
|
||||
spec_path = tmp_path / "console-openapi.json"
|
||||
spec_path.write_text("{}", encoding="utf-8")
|
||||
|
||||
assert module._patch_union_schema_markdown("unchanged", spec_path) == "unchanged"
|
||||
|
||||
|
||||
def test_patch_union_response_markdown_fills_converter_blank_error_bodies(tmp_path: Path) -> None:
|
||||
module = _load_generate_swagger_markdown_docs_module()
|
||||
spec_path = tmp_path / "console-openapi.json"
|
||||
spec_path.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"paths": {
|
||||
"/plugins/{category}/list": {
|
||||
"get": {
|
||||
"responses": {
|
||||
"200": {"content": {"application/json": {"schema": {"type": "object"}}}},
|
||||
"400": {
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"anyOf": [
|
||||
{"$ref": "#/components/schemas/PluginError"},
|
||||
{"$ref": "#/components/schemas/ErrorResponse"},
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"default": {
|
||||
"content": {
|
||||
"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}
|
||||
}
|
||||
},
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
markdown = """### ~~[GET] /plugins/{category}/list~~
|
||||
#### Responses
|
||||
|
||||
| Code | Description | Schema |
|
||||
| ---- | ----------- | ------ |
|
||||
| 200 | Success | **application/json**: object<br> |
|
||||
| 400 | Bad \\| Request | **application/json**: <br> |
|
||||
| 404 | Undocumented | **application/json**: <br> |
|
||||
| default | Error | **application/json**: [ErrorResponse](#errorresponse)<br> |
|
||||
|
||||
### [GET] /unknown
|
||||
#### Responses
|
||||
|
||||
| Code | Description | Schema |
|
||||
| ---- | ----------- | ------ |
|
||||
| 400 | Bad Request | **application/json**: <br> |
|
||||
"""
|
||||
|
||||
patched = module._patch_union_response_markdown(markdown, spec_path)
|
||||
|
||||
assert (
|
||||
"| 400 | Bad \\| Request | **application/json**: "
|
||||
"[PluginError](#pluginerror)<br>[ErrorResponse](#errorresponse)<br> |"
|
||||
) in patched
|
||||
assert "| 200 | Success | **application/json**: object<br> |" in patched
|
||||
assert "| 404 | Undocumented | **application/json**: <br> |" in patched
|
||||
assert "| default | Error | **application/json**: [ErrorResponse](#errorresponse)<br> |" in patched
|
||||
assert patched.endswith("| 400 | Bad Request | **application/json**: <br> |\n")
|
||||
|
||||
|
||||
def test_patch_wildcard_media_type_markdown_preserves_literal_wildcard() -> None:
|
||||
module = _load_generate_swagger_markdown_docs_module()
|
||||
|
||||
patched = module._patch_wildcard_media_type_markdown("| 200 | Raw file. | ***/***: binary<br> |\n")
|
||||
|
||||
assert patched == "| 200 | Raw file. | `*/*`: binary<br> |\n"
|
||||
|
||||
|
||||
def test_drop_null_values_for_markdown_does_not_mutate_openapi_source() -> None:
|
||||
module = _load_generate_swagger_markdown_docs_module()
|
||||
payload = {
|
||||
"schema": {
|
||||
"default": None,
|
||||
"enum": ["value", None],
|
||||
"properties": {"nullable": {"default": None}}, # pyrefly: ignore[implicit-any-empty-container]
|
||||
}
|
||||
}
|
||||
|
||||
converted = module._drop_null_values_for_markdown(payload)
|
||||
|
||||
assert converted == {
|
||||
"schema": {
|
||||
"enum": ["value", None],
|
||||
"properties": {"nullable": {}},
|
||||
}
|
||||
}
|
||||
assert payload["schema"]["default"] is None
|
||||
assert payload["schema"]["properties"]["nullable"]["default"] is None
|
||||
|
||||
|
||||
def test_patch_union_schema_markdown_ignores_unrenderable_shapes(tmp_path: Path) -> None:
|
||||
module = _load_generate_swagger_markdown_docs_module()
|
||||
spec_path = tmp_path / "console-openapi.json"
|
||||
spec_path.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"components": {
|
||||
"schemas": {
|
||||
"NotAMapping": [],
|
||||
"BrokenUnion": {
|
||||
"oneOf": [
|
||||
{},
|
||||
{"$ref": "#/components/schemas/Missing"},
|
||||
{"$ref": "#/components/schemas/NoPropertyMapping"},
|
||||
],
|
||||
},
|
||||
"NoPropertyMapping": {"properties": []},
|
||||
},
|
||||
}
|
||||
}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
assert module._schema_ref_name(None) is None
|
||||
assert module._schema_markdown_type(None) == ""
|
||||
assert module._schema_markdown_type({"anyOf": [{"type": "null"}]}) == ""
|
||||
assert module._strip_trailing_line_whitespace("line \ncell\t \n") == "line\ncell\n"
|
||||
assert module._replace_schema_table_type("unchanged", "Definition", "field", "") == "unchanged"
|
||||
assert (
|
||||
module._replace_schema_table_type(
|
||||
"#### Definition\n#### Next\n| field | | | No |",
|
||||
"Definition",
|
||||
"field",
|
||||
"string",
|
||||
)
|
||||
== "#### Definition\n#### Next\n| field | | | No |"
|
||||
)
|
||||
assert (
|
||||
module._replace_schema_table_type("#### Definition\n| field |", "Definition", "field", "string")
|
||||
== "#### Definition\n| field |"
|
||||
)
|
||||
|
||||
assert module._patch_union_schema_markdown("#### BrokenUnion\n", spec_path) == "#### BrokenUnion\n"
|
||||
|
||||
|
||||
def test_convert_spec_to_markdown_logs_converter_failure_without_overwriting_docs(
|
||||
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
|
||||
) -> None:
|
||||
module = _load_generate_swagger_markdown_docs_module()
|
||||
spec_path = tmp_path / "console-openapi.json"
|
||||
output_path = tmp_path / "console-openapi.md"
|
||||
spec_path.write_text("{}", encoding="utf-8")
|
||||
output_path.write_text("Existing documentation\n", encoding="utf-8")
|
||||
|
||||
def run_converter(args: list[str], **_kwargs: object) -> subprocess.CompletedProcess[str]:
|
||||
return module.subprocess.CompletedProcess(
|
||||
args=args, returncode=1, stdout="Loading converter", stderr="Unable to resolve npm runtime"
|
||||
)
|
||||
|
||||
monkeypatch.setattr(module.subprocess, "run", run_converter)
|
||||
|
||||
with pytest.raises(module.subprocess.CalledProcessError) as exc_info:
|
||||
module._convert_spec_to_markdown(spec_path, output_path)
|
||||
|
||||
assert exc_info.value.returncode == 1
|
||||
assert exc_info.value.stdout == "Loading converter"
|
||||
assert exc_info.value.stderr == "Unable to resolve npm runtime"
|
||||
assert str(spec_path) in caplog.text
|
||||
assert "Loading converter" in caplog.text
|
||||
assert "Unable to resolve npm runtime" in caplog.text
|
||||
assert output_path.read_text(encoding="utf-8") == "Existing documentation\n"
|
||||
|
||||
|
||||
@pytest.mark.parametrize("required", ["Yes", "No"])
|
||||
@pytest.mark.parametrize("content_count", [1, 2, 3])
|
||||
def test_convert_spec_to_markdown_patches_generated_union_tables(
|
||||
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, required: str, content_count: int
|
||||
) -> None:
|
||||
module = _load_generate_swagger_markdown_docs_module()
|
||||
spec_path = tmp_path / "console-openapi.json"
|
||||
output_path = tmp_path / "console-openapi.md"
|
||||
spec_path.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"components": {
|
||||
"schemas": {
|
||||
"FormInputConfig": {
|
||||
"oneOf": [
|
||||
{"$ref": "#/components/schemas/ParagraphInputConfig"},
|
||||
],
|
||||
},
|
||||
"ParagraphInputConfig": {
|
||||
"properties": {
|
||||
"default": {
|
||||
"anyOf": [
|
||||
{"$ref": "#/components/schemas/StringSource"},
|
||||
{"type": "null"},
|
||||
],
|
||||
"default": None,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
media_types = ["application/json", "multipart/form-data", "application/x-www-form-urlencoded"][:content_count]
|
||||
body_schema = "".join(f"**{media_type}**: string, enum: a\\|b<br>" for media_type in media_types)
|
||||
|
||||
def run_converter(args: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
|
||||
assert kwargs["check"] is False
|
||||
converter_spec_path = Path(args[args.index("-i") + 1])
|
||||
assert converter_spec_path != spec_path
|
||||
converter_spec = json.loads(converter_spec_path.read_text(encoding="utf-8"))
|
||||
converter_default_property = converter_spec["components"]["schemas"]["ParagraphInputConfig"]["properties"][
|
||||
"default"
|
||||
]
|
||||
assert "default" not in converter_default_property
|
||||
source_spec = json.loads(spec_path.read_text(encoding="utf-8"))
|
||||
assert source_spec["components"]["schemas"]["ParagraphInputConfig"]["properties"]["default"]["default"] is None
|
||||
markdown_path = Path(args[args.index("-o") + 1])
|
||||
markdown_path.write_text(
|
||||
"Intro line"
|
||||
+ " \n"
|
||||
+ """
|
||||
#### FormInputConfig
|
||||
|
||||
| Name | Type | Description | Required |
|
||||
| ---- | ---- | ----------- | -------- |
|
||||
| FormInputConfig | | | |
|
||||
|
||||
#### ParagraphInputConfig
|
||||
|
||||
| Name | Type | Description | Required |
|
||||
| ---- | ---- | ----------- | -------- |
|
||||
| default | | | No |
|
||||
"""
|
||||
+ "\n#### Request Body\n\n| Required | Schema |\n| -------- | ------ |\n"
|
||||
+ f"| {required} | "
|
||||
+ " | ".join([body_schema] * content_count)
|
||||
+ " |\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
return module.subprocess.CompletedProcess(args=args, returncode=0, stdout="", stderr="")
|
||||
|
||||
monkeypatch.setattr(module.subprocess, "run", run_converter)
|
||||
|
||||
module._convert_spec_to_markdown(spec_path, output_path)
|
||||
|
||||
converted = output_path.read_text(encoding="utf-8")
|
||||
assert "Intro line \n" not in converted
|
||||
assert "Intro line\n" in converted
|
||||
assert "| FormInputConfig | [ParagraphInputConfig](#paragraphinputconfig) | | |" in converted
|
||||
assert "| default | [StringSource](#stringsource) | | No |" in converted
|
||||
body_row = converted.split("| -------- | ------ |\n", 1)[1].strip()
|
||||
assert [cell.strip() for cell in body_row.strip("|").split(" | ")] == [required, body_schema]
|
||||
|
||||
|
||||
def test_request_body_patch_preserves_distinct_cells_and_other_tables() -> None:
|
||||
module = _load_generate_swagger_markdown_docs_module()
|
||||
markdown = """| Required | Schema |
|
||||
| -------- | ------ |
|
||||
| Yes | first | second |
|
||||
|
||||
| Name | Schema | Description |
|
||||
| ---- | ------ | ----------- |
|
||||
| Yes | same | same |
|
||||
"""
|
||||
assert module._patch_request_body_markdown(markdown) == markdown
|
||||
@@ -0,0 +1,763 @@
|
||||
"""Unit tests for the standalone OpenAPI export helper."""
|
||||
|
||||
import importlib.util
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
from jsonschema import Draft202012Validator
|
||||
from jsonschema.exceptions import SchemaError
|
||||
|
||||
from tests.helpers.unit.config_override import apply_config_overrides
|
||||
|
||||
|
||||
def _walk_values(value):
|
||||
yield value
|
||||
match value:
|
||||
case dict():
|
||||
for child in value.values():
|
||||
yield from _walk_values(child)
|
||||
case list():
|
||||
for child in value:
|
||||
yield from _walk_values(child)
|
||||
|
||||
|
||||
def _load_generate_swagger_specs_module():
|
||||
api_dir = Path(__file__).resolve().parents[3]
|
||||
script_path = api_dir / "dev" / "generate_swagger_specs.py"
|
||||
|
||||
spec = importlib.util.spec_from_file_location("generate_swagger_specs", script_path)
|
||||
assert spec
|
||||
assert spec.loader
|
||||
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
sys.modules[spec.name] = module
|
||||
spec.loader.exec_module(module) # type: ignore[attr-defined]
|
||||
return module
|
||||
|
||||
|
||||
def _operation_ids(payload):
|
||||
methods = {"delete", "get", "head", "options", "patch", "post", "put", "trace"}
|
||||
for path_item in payload["paths"].values():
|
||||
for method, operation in path_item.items():
|
||||
if method in methods and isinstance(operation, dict) and "operationId" in operation:
|
||||
yield operation["operationId"]
|
||||
|
||||
|
||||
def _get_operations(payload):
|
||||
for path_item in payload["paths"].values():
|
||||
operation = path_item.get("get")
|
||||
if isinstance(operation, dict):
|
||||
yield operation
|
||||
|
||||
|
||||
def _response_schema(operation, status="200"):
|
||||
return operation["responses"][status]["content"]["application/json"]["schema"]
|
||||
|
||||
|
||||
def _request_schema(operation, content_type="application/json"):
|
||||
return operation["requestBody"]["content"][content_type]["schema"]
|
||||
|
||||
|
||||
def _reset_schema_cache(api):
|
||||
api._schema = None
|
||||
api.__dict__.pop("__schema__", None)
|
||||
|
||||
|
||||
_OPENAPI_METHODS = {"delete", "get", "head", "options", "patch", "post", "put", "trace"}
|
||||
|
||||
_SCHEMA_MAP_KEYWORDS = ("$defs", "definitions", "dependentSchemas", "patternProperties", "properties")
|
||||
_SCHEMA_OBJECT_KEYWORDS = (
|
||||
"additionalProperties",
|
||||
"contains",
|
||||
"else",
|
||||
"if",
|
||||
"items",
|
||||
"not",
|
||||
"propertyNames",
|
||||
"then",
|
||||
"unevaluatedItems",
|
||||
"unevaluatedProperties",
|
||||
)
|
||||
_SCHEMA_LIST_KEYWORDS = ("allOf", "anyOf", "oneOf", "prefixItems")
|
||||
|
||||
|
||||
def _iter_subschemas(schema):
|
||||
if not isinstance(schema, dict):
|
||||
return
|
||||
yield schema
|
||||
for keyword in _SCHEMA_MAP_KEYWORDS:
|
||||
for child in (schema.get(keyword) or {}).values():
|
||||
yield from _iter_subschemas(child)
|
||||
for keyword in _SCHEMA_OBJECT_KEYWORDS:
|
||||
if keyword in schema:
|
||||
child = schema[keyword]
|
||||
if isinstance(child, list):
|
||||
for item in child:
|
||||
yield from _iter_subschemas(item)
|
||||
else:
|
||||
yield from _iter_subschemas(child)
|
||||
for keyword in _SCHEMA_LIST_KEYWORDS:
|
||||
for child in schema.get(keyword) or []:
|
||||
yield from _iter_subschemas(child)
|
||||
|
||||
|
||||
def _iter_content_schemas(content):
|
||||
"""Yield unmodified schema roots from an optional OpenAPI content mapping."""
|
||||
for media_type in (content or {}).values():
|
||||
if isinstance(media_type, dict) and "schema" in media_type:
|
||||
yield media_type["schema"]
|
||||
|
||||
|
||||
def _iter_parameter_schemas(parameter):
|
||||
"""Yield unmodified schema roots when the input is an OpenAPI parameter mapping."""
|
||||
if not isinstance(parameter, dict):
|
||||
return
|
||||
if "schema" in parameter:
|
||||
yield parameter["schema"]
|
||||
yield from _iter_content_schemas(parameter.get("content"))
|
||||
|
||||
|
||||
def _iter_operation_schemas(operation):
|
||||
for parameter in operation.get("parameters") or []:
|
||||
yield from _iter_parameter_schemas(parameter)
|
||||
request_body = operation.get("requestBody")
|
||||
if isinstance(request_body, dict):
|
||||
yield from _iter_content_schemas(request_body.get("content"))
|
||||
for response in (operation.get("responses") or {}).values():
|
||||
if not isinstance(response, dict):
|
||||
continue
|
||||
yield from _iter_content_schemas(response.get("content"))
|
||||
for header in (response.get("headers") or {}).values():
|
||||
yield from _iter_parameter_schemas(header)
|
||||
|
||||
|
||||
def _iter_document_schemas(payload):
|
||||
"""Yield schema roots from a document without recursively duplicating their children."""
|
||||
yield from payload["components"]["schemas"].values()
|
||||
for path_item in payload["paths"].values():
|
||||
for parameter in path_item.get("parameters") or []:
|
||||
yield from _iter_parameter_schemas(parameter)
|
||||
for method, operation in path_item.items():
|
||||
if method in _OPENAPI_METHODS and isinstance(operation, dict):
|
||||
yield from _iter_operation_schemas(operation)
|
||||
|
||||
|
||||
def _schema_contract_errors(payload):
|
||||
"""Report invalid schemas and broken local contracts without changing the document.
|
||||
|
||||
The input has OpenAPI paths and component schemas. Validate each schema tree
|
||||
once, then inspect its subschemas for required fields and local references.
|
||||
"""
|
||||
errors = []
|
||||
known_refs = {f"#/components/schemas/{name}" for name in payload["components"]["schemas"]}
|
||||
roots = list(_iter_document_schemas(payload))
|
||||
# check_schema recursively validates children. Batching roots also avoids
|
||||
# constructing the meta-schema validator again for every property and ref.
|
||||
try:
|
||||
Draft202012Validator.check_schema({"$defs": {str(index): schema for index, schema in enumerate(roots)}})
|
||||
except SchemaError as exc:
|
||||
return [f"malformed schema: {exc}"]
|
||||
for schema in (child for root in roots for child in _iter_subschemas(root)):
|
||||
required = schema.get("required")
|
||||
properties = schema.get("properties")
|
||||
if required and isinstance(properties, dict) and not ({"allOf", "anyOf", "oneOf", "$ref"} & schema.keys()):
|
||||
missing = sorted(set(required) - set(properties))
|
||||
if missing:
|
||||
errors.append(f"required properties missing from properties: {missing}")
|
||||
ref = schema.get("$ref")
|
||||
if isinstance(ref, str) and ref.startswith("#/components/schemas/") and ref not in known_refs:
|
||||
errors.append(f"dangling $ref: {ref}")
|
||||
discriminator = schema.get("discriminator")
|
||||
if isinstance(discriminator, dict):
|
||||
for mapped in (discriminator.get("mapping") or {}).values():
|
||||
if isinstance(mapped, str) and mapped.startswith("#/components/schemas/") and mapped not in known_refs:
|
||||
errors.append(f"dangling discriminator mapping: {mapped}")
|
||||
return errors
|
||||
|
||||
|
||||
def _operation_contract_errors(payload):
|
||||
errors = []
|
||||
for path, path_item in payload["paths"].items():
|
||||
template_parameters = set(re.findall(r"\{([^{}]+)\}", path))
|
||||
path_level_parameters = [p for p in path_item.get("parameters") or [] if isinstance(p, dict)]
|
||||
for method, operation in path_item.items():
|
||||
if method not in _OPENAPI_METHODS or not isinstance(operation, dict):
|
||||
continue
|
||||
label = f"{method.upper()} {path}"
|
||||
if not operation.get("operationId"):
|
||||
errors.append(f"{label}: missing operationId")
|
||||
responses = operation.get("responses")
|
||||
if not responses:
|
||||
errors.append(f"{label}: missing responses")
|
||||
else:
|
||||
for status, response in responses.items():
|
||||
if not isinstance(response, dict) or not response.get("description"):
|
||||
errors.append(f"{label} {status}: response is missing a description")
|
||||
parameters = path_level_parameters + [p for p in operation.get("parameters") or [] if isinstance(p, dict)]
|
||||
declared = {p.get("name") for p in parameters if p.get("in") == "path"}
|
||||
undeclared = sorted(template_parameters - declared)
|
||||
if undeclared:
|
||||
errors.append(f"{label}: path parameters not declared: {undeclared}")
|
||||
for parameter in parameters:
|
||||
if parameter.get("in") == "path" and parameter.get("required") is not True:
|
||||
errors.append(f"{label}: path parameter {parameter.get('name')!r} is not required")
|
||||
return errors
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def generated_specs(tmp_path_factory: pytest.TempPathFactory) -> list[Path]:
|
||||
"""Spec files written once by ``generate_specs`` for the tests that only read them.
|
||||
|
||||
Each export imports every API surface and takes seconds, so read-only checks share one;
|
||||
tests that exercise generation itself still call ``generate_specs`` on their own.
|
||||
"""
|
||||
return _load_generate_swagger_specs_module().generate_specs(tmp_path_factory.mktemp("specs"))
|
||||
|
||||
|
||||
@pytest.mark.timeout(150) # Two cold, coverage-instrumented CLI exports each have a 60-second limit.
|
||||
def test_console_stdout_export_contains_both_surfaces_without_spec_files(tmp_path: Path):
|
||||
script = Path(__file__).resolve().parents[3] / "dev" / "export_console_openapi.py"
|
||||
result = subprocess.run(
|
||||
[sys.executable, str(script)], cwd=tmp_path, capture_output=True, text=True, check=True, timeout=60
|
||||
)
|
||||
documents = json.loads(result.stdout)
|
||||
assert set(documents) == {"console", "fast"}
|
||||
for document in documents.values():
|
||||
assert document["openapi"].startswith("3.")
|
||||
assert document["paths"]
|
||||
for item in document["paths"].values():
|
||||
for operation in item.values():
|
||||
if not isinstance(operation, dict) or "responses" not in operation:
|
||||
continue
|
||||
origin = operation["x-source-location"]
|
||||
source_line = Path(origin["file"]).read_text().splitlines()[origin["line"] - 1].lstrip()
|
||||
assert source_line.startswith(("def ", "async def "))
|
||||
datasets = documents["console"]["paths"]["/datasets"]["get"]["x-source-location"]
|
||||
assert datasets["file"].endswith("/controllers/console/datasets/datasets.py")
|
||||
cached_script = script.with_name("cached_console_openapi.py")
|
||||
try:
|
||||
cached = subprocess.run(
|
||||
[sys.executable, str(cached_script)], cwd=tmp_path, capture_output=True, text=True, check=True, timeout=60
|
||||
)
|
||||
assert json.loads(cached.stdout) == documents
|
||||
finally:
|
||||
subprocess.run(
|
||||
[sys.executable, str(cached_script), "--stop"], cwd=tmp_path, capture_output=True, check=True, timeout=10
|
||||
)
|
||||
assert not list(tmp_path.rglob("*.json"))
|
||||
|
||||
|
||||
def test_generate_specs_writes_all_openapi_files(generated_specs: list[Path]):
|
||||
assert [path.name for path in generated_specs] == [
|
||||
"console-openapi.json",
|
||||
"web-openapi.json",
|
||||
"service-openapi.json",
|
||||
"openapi-openapi.json",
|
||||
"inner-openapi.json",
|
||||
]
|
||||
|
||||
for path in generated_specs:
|
||||
payload = json.loads(path.read_text(encoding="utf-8"))
|
||||
assert payload["openapi"] == "3.1.0"
|
||||
assert "paths" in payload
|
||||
|
||||
inner_path = next(path for path in generated_specs if path.name == "inner-openapi.json")
|
||||
inner_payload = json.loads(inner_path.read_text(encoding="utf-8"))
|
||||
assert inner_payload["security"] == [{"InnerApiKey": []}]
|
||||
assert inner_payload["components"]["securitySchemes"] == {
|
||||
"InnerApiKey": {
|
||||
"type": "apiKey",
|
||||
"in": "header",
|
||||
"name": "X-Inner-Api-Key",
|
||||
"description": "INNER_API_KEY for enterprise callers; INNER_API_KEY_FOR_PLUGIN for plugin/agent callers.",
|
||||
}
|
||||
}
|
||||
assert "Bearer" not in inner_payload["components"]["securitySchemes"]
|
||||
assert "/enterprise/apps/{app_id}/dsl" in inner_payload["paths"]
|
||||
|
||||
|
||||
def test_console_only_export_matches_the_full_export():
|
||||
module = _load_generate_swagger_specs_module()
|
||||
assert module.export_console_spec() == module.export_specs()["console-openapi.json"]
|
||||
|
||||
|
||||
def test_generate_specs_match_live_openapi_payloads(tmp_path: Path):
|
||||
module = _load_generate_swagger_specs_module()
|
||||
app = module.create_spec_app()
|
||||
client = app.test_client()
|
||||
target_apis = module._target_apis()
|
||||
for api in target_apis.values():
|
||||
_reset_schema_cache(api)
|
||||
live_payloads = {target.filename: client.get(target.route).get_json() for target in module.SPEC_TARGETS}
|
||||
|
||||
# Poison the endpoint cache after reading the live contract. The exporter
|
||||
# must independently serialize each API instead of succeeding by reading
|
||||
# the same cached payload through the HTTP spec route.
|
||||
poison_payload = {"poison": "stale schema cache"}
|
||||
for api in target_apis.values():
|
||||
api._schema = poison_payload
|
||||
api.__dict__["__schema__"] = poison_payload
|
||||
try:
|
||||
for target in module.SPEC_TARGETS:
|
||||
response = client.get(target.route)
|
||||
assert response.status_code == 200
|
||||
assert response.get_json() == poison_payload
|
||||
written_paths = module.generate_specs(tmp_path)
|
||||
finally:
|
||||
for api in target_apis.values():
|
||||
_reset_schema_cache(api)
|
||||
|
||||
assert {path.name for path in written_paths} == set(live_payloads)
|
||||
for path in written_paths:
|
||||
assert json.loads(path.read_text(encoding="utf-8")) == live_payloads[path.name]
|
||||
|
||||
|
||||
@pytest.mark.timeout(75) # Allow one cold, coverage-instrumented export with its own 60-second limit.
|
||||
def test_generate_specs_after_controllers_were_imported_with_swagger_disabled(tmp_path: Path):
|
||||
api_dir = Path(__file__).resolve().parents[3]
|
||||
script = """
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
from controllers.console import api as console_api
|
||||
from controllers.inner_api import api as inner_api
|
||||
from controllers.openapi import api as openapi_api
|
||||
from controllers.service_api import api as service_api
|
||||
from controllers.web import api as web_api
|
||||
|
||||
apis = (console_api, web_api, service_api, openapi_api, inner_api)
|
||||
assert all(api._add_specs is False for api in apis)
|
||||
|
||||
from dev.generate_swagger_specs import generate_specs
|
||||
|
||||
written_paths = generate_specs(Path(sys.argv[1]))
|
||||
assert [path.name for path in written_paths] == [
|
||||
"console-openapi.json",
|
||||
"web-openapi.json",
|
||||
"service-openapi.json",
|
||||
"openapi-openapi.json",
|
||||
"inner-openapi.json",
|
||||
]
|
||||
"""
|
||||
env = os.environ.copy()
|
||||
env["PYTHONPATH"] = str(api_dir)
|
||||
env["SWAGGER_UI_ENABLED"] = "false"
|
||||
|
||||
result = subprocess.run(
|
||||
[sys.executable, "-c", script, str(tmp_path)],
|
||||
cwd=api_dir,
|
||||
env=env,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=60,
|
||||
)
|
||||
|
||||
assert result.returncode == 0, result.stderr
|
||||
|
||||
|
||||
def test_apply_runtime_defaults_forces_swagger_routes_on(monkeypatch):
|
||||
module = _load_generate_swagger_specs_module()
|
||||
from configs import dify_config
|
||||
|
||||
monkeypatch.setenv("SWAGGER_UI_ENABLED", "false")
|
||||
apply_config_overrides(monkeypatch, SWAGGER_UI_ENABLED=False)
|
||||
|
||||
module.apply_runtime_defaults()
|
||||
|
||||
assert dify_config.SWAGGER_UI_ENABLED is True
|
||||
|
||||
|
||||
def test_generate_specs_writes_openapi_with_resolvable_references_and_null_defaults(generated_specs: list[Path]):
|
||||
for path in generated_specs:
|
||||
payload = json.loads(path.read_text(encoding="utf-8"))
|
||||
schemas = payload["components"]["schemas"]
|
||||
refs = {
|
||||
item["$ref"].removeprefix("#/components/schemas/")
|
||||
for item in _walk_values(payload)
|
||||
if isinstance(item, dict)
|
||||
and isinstance(item.get("$ref"), str)
|
||||
and item["$ref"].startswith("#/components/schemas/")
|
||||
}
|
||||
|
||||
assert refs <= set(schemas)
|
||||
assert all("nullable" not in value for value in _walk_values(payload) if isinstance(value, dict))
|
||||
|
||||
service_payload = json.loads((generated_specs[0].parent / "service-openapi.json").read_text(encoding="utf-8"))
|
||||
conversation_id = service_payload["components"]["schemas"]["ChatRequestPayload"]["properties"]["conversation_id"]
|
||||
assert "default" in conversation_id
|
||||
assert conversation_id["default"] is None
|
||||
|
||||
schemas = service_payload["components"]["schemas"]
|
||||
document_detail = schemas["DocumentDetailResponse"]
|
||||
validator = Draft202012Validator(service_payload)
|
||||
for schema in (document_detail, *schemas["DocumentTextUpdate"]["anyOf"]):
|
||||
for property_schema in schema["properties"].values():
|
||||
if "default" in property_schema:
|
||||
validator.evolve(schema=property_schema).validate(property_schema["default"])
|
||||
|
||||
assert document_detail["required"] == ["id"]
|
||||
assert document_detail["properties"]["enabled"]["type"] == "boolean"
|
||||
assert "default" not in document_detail["properties"]["enabled"]
|
||||
assert document_detail["properties"]["tokens"]["default"] is None
|
||||
|
||||
|
||||
def test_generate_specs_writes_unique_operation_ids(generated_specs: list[Path]):
|
||||
for path in generated_specs:
|
||||
payload = json.loads(path.read_text(encoding="utf-8"))
|
||||
operation_ids = list(_operation_ids(payload))
|
||||
|
||||
assert len(operation_ids) == len(set(operation_ids))
|
||||
|
||||
|
||||
def test_finalize_openapi_payload_preserves_canonical_operation_id():
|
||||
module = _load_generate_swagger_specs_module()
|
||||
payload = {
|
||||
"paths": {
|
||||
"/items/create-by-file": {
|
||||
"post": {"operationId": "create_item", "responses": {"200": {}}},
|
||||
},
|
||||
"/items/create_by_file": {
|
||||
"post": {"deprecated": True, "operationId": "create_item", "responses": {"200": {}}},
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
result = module.finalize_openapi_payload(payload)
|
||||
|
||||
assert result["paths"]["/items/create-by-file"]["post"]["operationId"] == "create_item"
|
||||
legacy_operation_id = result["paths"]["/items/create_by_file"]["post"]["operationId"]
|
||||
assert legacy_operation_id.startswith("create_item_")
|
||||
|
||||
|
||||
def test_finalize_openapi_payload_only_marks_explicit_binary_responses():
|
||||
module = _load_generate_swagger_specs_module()
|
||||
payload = {
|
||||
"paths": {
|
||||
"/transport": {
|
||||
"get": {
|
||||
"operationId": "get_transport",
|
||||
"responses": {
|
||||
"200": {
|
||||
"content": {
|
||||
"application/octet-stream": {},
|
||||
"application/json; charset=utf-8": {},
|
||||
"application/problem+json": {},
|
||||
"text/event-stream; charset=utf-8": {
|
||||
"schema": {"$ref": "#/components/schemas/BlockingResponse"}
|
||||
},
|
||||
"text/plain": {},
|
||||
}
|
||||
}
|
||||
},
|
||||
"x-dify-binary-response-media-types": ["application/octet-stream"],
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
result = module.finalize_openapi_payload(payload)
|
||||
operation = result["paths"]["/transport"]["get"]
|
||||
content = operation["responses"]["200"]["content"]
|
||||
|
||||
assert content["application/octet-stream"]["schema"] == {"format": "binary", "type": "string"}
|
||||
assert content["text/event-stream; charset=utf-8"]["schema"] == {"type": "string"}
|
||||
assert content["application/json; charset=utf-8"] == {}
|
||||
assert content["application/problem+json"] == {}
|
||||
assert content["text/plain"] == {}
|
||||
assert "x-dify-binary-response-media-types" not in operation
|
||||
|
||||
|
||||
def test_console_file_and_audio_responses_declare_binary_success_and_json_errors(generated_specs: list[Path]):
|
||||
payload = json.loads((generated_specs[0].parent / "console-openapi.json").read_text(encoding="utf-8"))
|
||||
audio_media = {"audio/aac", "audio/flac", "audio/mp4", "audio/mpeg", "audio/ogg", "audio/wav", "audio/webm"}
|
||||
operations = [
|
||||
("/workspaces/current/plugin/asset", "get", {"application/octet-stream"}),
|
||||
("/workspaces/current/plugin/icon", "get", {"*/*"}),
|
||||
("/workspaces/current/skills/{skill_id}/files/content", "get", {"*/*"}),
|
||||
("/installed-apps/{installed_app_id}/text-to-audio", "post", audio_media),
|
||||
("/trial-apps/{app_id}/text-to-audio", "post", audio_media),
|
||||
]
|
||||
for path, method, media_types in operations:
|
||||
responses = payload["paths"][path][method]["responses"]
|
||||
assert responses["200"]["content"] == {
|
||||
media_type: {"schema": {"type": "string", "format": "binary"}} for media_type in media_types
|
||||
}, path
|
||||
errors = {status: response for status, response in responses.items() if status.startswith(("4", "5"))}
|
||||
assert errors, path
|
||||
for status, response in errors.items():
|
||||
assert set(response["content"]) == {"application/json"}, (path, status)
|
||||
|
||||
|
||||
def test_system_features_specs_exclude_backend_only_fields(generated_specs: list[Path]):
|
||||
excluded_fields = {
|
||||
"enable_trial_app",
|
||||
"is_allow_create_workspace",
|
||||
"max_plugin_package_size",
|
||||
"plugin_manager",
|
||||
}
|
||||
|
||||
for spec_name in ("console-openapi.json", "web-openapi.json"):
|
||||
spec_path = next(path for path in generated_specs if path.name == spec_name)
|
||||
payload = json.loads(spec_path.read_text(encoding="utf-8"))
|
||||
schemas = payload["components"]["schemas"]
|
||||
system_features_schema = schemas["SystemFeatureModel"]
|
||||
|
||||
assert excluded_fields.isdisjoint(system_features_schema["properties"])
|
||||
assert "PluginManagerModel" not in schemas
|
||||
|
||||
|
||||
def test_generate_specs_writes_get_operations_without_request_bodies(generated_specs: list[Path]):
|
||||
for path in generated_specs:
|
||||
payload = json.loads(path.read_text(encoding="utf-8"))
|
||||
|
||||
assert all("requestBody" not in operation for operation in _get_operations(payload))
|
||||
|
||||
|
||||
def test_generate_specs_include_command_oriented_knowledge_fs_contract(generated_specs: list[Path]):
|
||||
openapi_path = next(path for path in generated_specs if path.name == "openapi-openapi.json")
|
||||
payload = json.loads(openapi_path.read_text(encoding="utf-8"))
|
||||
paths = payload["paths"]
|
||||
prefix = "/workspaces/{workspace_id}/knowledge-fs/knowledge-spaces/{knowledge_space_id}/fs"
|
||||
|
||||
assert {
|
||||
f"{prefix}:cat": "get",
|
||||
f"{prefix}:diff": "post",
|
||||
f"{prefix}:find": "get",
|
||||
f"{prefix}:grep": "get",
|
||||
f"{prefix}:ls": "get",
|
||||
f"{prefix}:stat": "get",
|
||||
f"{prefix}:tree": "get",
|
||||
} == {
|
||||
path: next(method for method in item if method != "parameters")
|
||||
for path, item in paths.items()
|
||||
if path.startswith(prefix)
|
||||
}
|
||||
assert not any("/knowledge-fs/spaces/" in path or "/entries" in path for path in paths)
|
||||
|
||||
list_operation = paths[f"{prefix}:ls"]["get"]
|
||||
query_names = {parameter["name"] for parameter in list_operation["parameters"] if parameter["in"] == "query"}
|
||||
assert query_names == {"consistency_class", "page_size", "page_token", "path"}
|
||||
path_names = {parameter["name"] for parameter in list_operation["parameters"] if parameter["in"] == "path"}
|
||||
assert path_names == {"knowledge_space_id", "workspace_id"}
|
||||
assert "requestBody" not in list_operation
|
||||
assert list_operation["operationId"] == "ls_knowledge_fs"
|
||||
assert list_operation["summary"] == "List an Agent Knowledge Base directory (ls)"
|
||||
assert "stable Agent Knowledge Base traversal order" in list_operation["description"]
|
||||
assert "total is intentionally omitted" in list_operation["description"]
|
||||
assert "WORKSPACE_READ" in list_operation["description"]
|
||||
assert _response_schema(list_operation)["$ref"] == "#/components/schemas/KnowledgeFSEntryListResponse"
|
||||
for status in ("400", "401", "403", "404", "409", "413", "422", "503"):
|
||||
assert _response_schema(list_operation, status)["$ref"] == "#/components/schemas/ErrorBody"
|
||||
|
||||
list_schema = payload["components"]["schemas"]["KnowledgeFSEntryListResponse"]
|
||||
assert {"data", "has_more", "next_page_token", "path", "truncated"} <= set(list_schema["properties"])
|
||||
entry_schema = payload["components"]["schemas"]["KnowledgeFSEntryResponse"]
|
||||
assert {item.get("type") for item in entry_schema["properties"]["resource_type"]["anyOf"]} == {
|
||||
"null",
|
||||
"string",
|
||||
}
|
||||
metadata_schema = payload["components"]["schemas"]["KnowledgeFSEntryMetadataResponse"]
|
||||
assert metadata_schema["properties"]["resource_type"]["type"] == "string"
|
||||
assert "enum" not in metadata_schema["properties"]["resource_type"]
|
||||
|
||||
diff_operation = paths[f"{prefix}:diff"]["post"]
|
||||
assert diff_operation["operationId"] == "diff_knowledge_fs"
|
||||
assert "consume model quota" in diff_operation["description"]
|
||||
assert "Automatic retries are not safe" in diff_operation["description"]
|
||||
assert _request_schema(diff_operation)["$ref"] == "#/components/schemas/KnowledgeFSEntryComparePayload"
|
||||
assert _response_schema(diff_operation)["$ref"] == ("#/components/schemas/KnowledgeFSEntryComparisonResponse")
|
||||
|
||||
tree_operation = paths[f"{prefix}:tree"]["get"]
|
||||
assert tree_operation["operationId"] == "tree_knowledge_fs"
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("nested_schema", "expected_error"),
|
||||
[
|
||||
({"type": "invalid-type"}, "malformed schema"),
|
||||
({"properties": {}, "required": ["missing"]}, "required properties missing"),
|
||||
({"$ref": "#/components/schemas/Missing"}, "dangling $ref"),
|
||||
(
|
||||
{"discriminator": {"propertyName": "kind", "mapping": {"cat": "#/components/schemas/Missing"}}},
|
||||
"dangling discriminator mapping",
|
||||
),
|
||||
],
|
||||
)
|
||||
def test_schema_contract_rejects_invalid_nested_schemas(nested_schema, expected_error):
|
||||
"""Nested schema defects must remain detectable when validating roots together."""
|
||||
payload = {
|
||||
"components": {"schemas": {"Envelope": {"properties": {"nested": nested_schema}}}},
|
||||
"paths": {},
|
||||
}
|
||||
|
||||
assert any(expected_error in error for error in _schema_contract_errors(payload))
|
||||
|
||||
|
||||
@pytest.mark.timeout(60) # Validate all five exports under coverage, including the large console schema.
|
||||
def test_generate_specs_produce_valid_openapi_contracts(tmp_path: Path):
|
||||
module = _load_generate_swagger_specs_module()
|
||||
|
||||
written_paths = module.generate_specs(tmp_path)
|
||||
|
||||
assert len(written_paths) == 5
|
||||
for path in written_paths:
|
||||
payload = json.loads(path.read_text(encoding="utf-8"))
|
||||
assert payload["openapi"].startswith("3."), path.name
|
||||
assert payload["paths"], path.name
|
||||
assert _schema_contract_errors(payload) == [], path.name
|
||||
assert _operation_contract_errors(payload) == [], path.name
|
||||
|
||||
|
||||
def test_generated_request_contracts_accept_and_reject_payloads(tmp_path: Path):
|
||||
module = _load_generate_swagger_specs_module()
|
||||
|
||||
written_paths = module.generate_specs(tmp_path)
|
||||
service_path = next(path for path in written_paths if path.name == "service-openapi.json")
|
||||
payload = json.loads(service_path.read_text(encoding="utf-8"))
|
||||
schemas = payload["components"]["schemas"]
|
||||
|
||||
file_item_schema = schemas["CompletionRequestPayloadWithUser"]["properties"]["files"]["anyOf"][0]["items"]
|
||||
file_validator = Draft202012Validator(file_item_schema)
|
||||
valid_file_values = [
|
||||
{"type": "image", "transfer_method": "remote_url", "url": "https://example.com/image.png"},
|
||||
{"type": "image", "transfer_method": "remote_url", "remote_url": "https://example.com/image.png"},
|
||||
{
|
||||
"type": "image",
|
||||
"transfer_method": "remote_url",
|
||||
"upload_file_id": "00000000-0000-0000-0000-000000000001",
|
||||
},
|
||||
{
|
||||
"type": "image",
|
||||
"transfer_method": "local_file",
|
||||
"upload_file_id": "00000000-0000-0000-0000-000000000001",
|
||||
"url": "https://example.com/signed-preview",
|
||||
},
|
||||
]
|
||||
for value in valid_file_values:
|
||||
assert not list(file_validator.iter_errors(value)), value
|
||||
|
||||
invalid_file_values = [
|
||||
{"type": "image", "transfer_method": "remote_url"},
|
||||
{"type": "image", "transfer_method": "local_file", "url": "https://example.com/image.png"},
|
||||
]
|
||||
for value in invalid_file_values:
|
||||
assert list(file_validator.iter_errors(value)), value
|
||||
|
||||
user_input_form_schema = schemas["Parameters"]["properties"]["user_input_form"]
|
||||
validator = Draft202012Validator(user_input_form_schema)
|
||||
form_values = {
|
||||
"text-input": "hello",
|
||||
"select": "alpha",
|
||||
"paragraph": "long text",
|
||||
"number": 3.5,
|
||||
"external_data_tool": None,
|
||||
"file": {"upload_file_id": "file-id"},
|
||||
"file-list": [{"upload_file_id": "file-id"}],
|
||||
"checkbox": True,
|
||||
"json_object": {"key": "value"},
|
||||
}
|
||||
for form_type, default in form_values.items():
|
||||
value = [{form_type: {"label": "Input", "variable": "input", "required": False, "default": default}}]
|
||||
assert not list(validator.iter_errors(value)), form_type
|
||||
|
||||
invalid_values = [
|
||||
[{"unknown": {"label": "Input", "variable": "input"}}],
|
||||
[
|
||||
{
|
||||
"text-input": {"label": "Text", "variable": "text"},
|
||||
"number": {"label": "Number", "variable": "number"},
|
||||
}
|
||||
],
|
||||
]
|
||||
for value in invalid_values:
|
||||
assert list(validator.iter_errors(value)), value
|
||||
|
||||
|
||||
def test_generate_specs_writes_web_file_upload_error_codes(generated_specs: list[Path]):
|
||||
web_path = next(path for path in generated_specs if path.name == "web-openapi.json")
|
||||
payload = json.loads(web_path.read_text(encoding="utf-8"))
|
||||
|
||||
upload_bad_request = payload["paths"]["/files/upload"]["post"]["responses"]["400"]["description"]
|
||||
assert "`file_extension_blocked`" in upload_bad_request
|
||||
|
||||
|
||||
def test_standalone_inline_model_name_includes_list_constraints():
|
||||
module = _load_generate_swagger_specs_module()
|
||||
|
||||
from flask_restx import fields
|
||||
|
||||
cases = (
|
||||
({"min_items": 1}, {"min_items": 2}),
|
||||
({"max_items": 1}, {"max_items": 2}),
|
||||
({"unique": True}, {"unique": False}),
|
||||
)
|
||||
for first_kwargs, second_kwargs in cases:
|
||||
first_inline_model = {"items": fields.List(fields.String, **first_kwargs)}
|
||||
second_inline_model = {"items": fields.List(fields.String, **second_kwargs)}
|
||||
|
||||
assert module._inline_model_name(first_inline_model) != module._inline_model_name(second_inline_model)
|
||||
|
||||
|
||||
def test_generate_specs_is_idempotent(tmp_path: Path):
|
||||
module = _load_generate_swagger_specs_module()
|
||||
|
||||
first_paths = module.generate_specs(tmp_path / "first")
|
||||
second_paths = module.generate_specs(tmp_path / "second")
|
||||
|
||||
assert [path.name for path in first_paths] == [path.name for path in second_paths]
|
||||
for first_path, second_path in zip(first_paths, second_paths, strict=False):
|
||||
assert first_path.read_text(encoding="utf-8") == second_path.read_text(encoding="utf-8")
|
||||
|
||||
|
||||
def test_generate_specs_include_agent_v2_knowledge_set_schema_and_query_enums(generated_specs: list[Path]):
|
||||
console_path = next(path for path in generated_specs if path.name == "console-openapi.json")
|
||||
payload = json.loads(console_path.read_text(encoding="utf-8"))
|
||||
schemas = payload["components"]["schemas"]
|
||||
|
||||
assert "AgentKnowledgeSetConfig" in schemas
|
||||
assert schemas["AgentSoulKnowledgeConfig"]["properties"]["sets"]["items"]["$ref"] == (
|
||||
"#/components/schemas/AgentKnowledgeSetConfig"
|
||||
)
|
||||
assert schemas["AgentKnowledgeQueryMode"]["enum"] == ["generated_query", "user_query"]
|
||||
|
||||
|
||||
def test_checked_in_agent_v2_knowledge_openapi_and_generated_contracts_are_in_sync():
|
||||
api_dir = Path(__file__).resolve().parents[3]
|
||||
repo_root = api_dir.parent
|
||||
|
||||
markdown = (api_dir / "openapi" / "markdown" / "console-openapi.md").read_text(encoding="utf-8")
|
||||
agent_types = (
|
||||
repo_root / "packages" / "contracts" / "generated" / "api" / "console" / "agent" / "types.gen.ts"
|
||||
).read_text(encoding="utf-8")
|
||||
apps_types = (
|
||||
repo_root / "packages" / "contracts" / "generated" / "api" / "console" / "apps" / "types.gen.ts"
|
||||
).read_text(encoding="utf-8")
|
||||
agent_zod = (
|
||||
repo_root / "packages" / "contracts" / "generated" / "api" / "console" / "agent" / "zod.gen.ts"
|
||||
).read_text(encoding="utf-8")
|
||||
apps_zod = (
|
||||
repo_root / "packages" / "contracts" / "generated" / "api" / "console" / "apps" / "zod.gen.ts"
|
||||
).read_text(encoding="utf-8")
|
||||
|
||||
assert "#### AgentKnowledgeSetConfig" in markdown
|
||||
assert "#### AgentSoulKnowledgeConfig" in markdown
|
||||
assert "#### AgentKnowledgeQueryMode" in markdown
|
||||
|
||||
for content in (agent_types, apps_types):
|
||||
assert "export type AgentKnowledgeSetConfig = {" in content
|
||||
assert "export type AgentSoulKnowledgeConfig = {" in content
|
||||
assert "AgentKnowledgeQueryMode" in content
|
||||
assert "generated_query" in content
|
||||
assert "user_query" in content
|
||||
|
||||
for content in (agent_zod, apps_zod):
|
||||
assert "export const zAgentKnowledgeSetConfig = z.object({" in content
|
||||
assert "export const zAgentSoulKnowledgeConfig = z.object({" in content
|
||||
assert "zAgentKnowledgeQueryMode = z.enum([" in content
|
||||
assert "generated_query" in content
|
||||
assert "user_query" in content
|
||||
@@ -0,0 +1,283 @@
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
from dev import lint_response_contracts
|
||||
|
||||
|
||||
def _checks_for_source(tmp_path: Path, source: str) -> list[lint_response_contracts.ContractCheck]:
|
||||
controller_path = tmp_path / "controllers" / "sample.py"
|
||||
controller_path.parent.mkdir()
|
||||
controller_path.write_text(source, encoding="utf-8")
|
||||
return lint_response_contracts.checks_for_file(controller_path, tmp_path)
|
||||
|
||||
|
||||
def test_no_body_status_with_body_is_mismatch_while_empty_body_is_valid(tmp_path: Path) -> None:
|
||||
checks = _checks_for_source(
|
||||
tmp_path,
|
||||
"""
|
||||
@ns.route("/bad")
|
||||
class BadDeleteApi(Resource):
|
||||
@ns.response(204, "Deleted")
|
||||
def delete(self):
|
||||
return {"result": "success"}, 204
|
||||
|
||||
|
||||
@ns.route("/ok")
|
||||
class EmptyDeleteApi(Resource):
|
||||
@ns.response(204, "Deleted")
|
||||
def delete(self):
|
||||
return "", 204
|
||||
""",
|
||||
)
|
||||
|
||||
assert [(check.class_name, check.classification) for check in checks] == [
|
||||
("BadDeleteApi", "mismatch"),
|
||||
("EmptyDeleteApi", "valid"),
|
||||
]
|
||||
assert "no-body response but returns raw_dict" in checks[0].reason
|
||||
|
||||
|
||||
def test_variable_model_dump_is_refactorable_not_valid(tmp_path: Path) -> None:
|
||||
checks = _checks_for_source(
|
||||
tmp_path,
|
||||
"""
|
||||
from http import HTTPStatus
|
||||
|
||||
|
||||
@ns.route("/annotations")
|
||||
class AnnotationApi(Resource):
|
||||
@ns.response(HTTPStatus.CREATED, "Created", ns.models[AnnotationResponse.__name__])
|
||||
def post(self):
|
||||
if use_existing:
|
||||
response = AnnotationResponse.model_validate(existing, from_attributes=True)
|
||||
else:
|
||||
response = AnnotationResponse(id="new")
|
||||
return response.model_dump(mode="json"), HTTPStatus.CREATED
|
||||
""",
|
||||
)
|
||||
|
||||
assert len(checks) == 1
|
||||
assert checks[0].classification == "refactorable"
|
||||
assert checks[0].actual[0].status == 201
|
||||
assert checks[0].actual[0].kind == "model_dump_variable"
|
||||
assert "prefer dump_response" in checks[0].reason
|
||||
|
||||
|
||||
def test_constructor_variable_model_dump_is_valid(tmp_path: Path) -> None:
|
||||
checks = _checks_for_source(
|
||||
tmp_path,
|
||||
"""
|
||||
@ns.route("/annotations")
|
||||
class AnnotationApi(Resource):
|
||||
@ns.response(201, "Created", ns.models[AnnotationResponse.__name__])
|
||||
def post(self):
|
||||
response = AnnotationResponse(id="new", name=name)
|
||||
return response.model_dump(mode="json"), 201
|
||||
""",
|
||||
)
|
||||
|
||||
assert len(checks) == 1
|
||||
assert checks[0].classification == "valid"
|
||||
assert checks[0].actual[0].kind == "model"
|
||||
assert checks[0].actual[0].model == "AnnotationResponse"
|
||||
|
||||
|
||||
def test_variable_model_dump_with_wrong_documented_schema_is_mismatch(tmp_path: Path) -> None:
|
||||
checks = _checks_for_source(
|
||||
tmp_path,
|
||||
"""
|
||||
@ns.route("/annotations")
|
||||
class AnnotationApi(Resource):
|
||||
@ns.response(200, "OK", ns.models[DocumentedResponse.__name__])
|
||||
def get(self):
|
||||
response = ActualResponse.model_validate(data)
|
||||
return response.model_dump(mode="json"), 200
|
||||
""",
|
||||
)
|
||||
|
||||
assert len(checks) == 1
|
||||
assert checks[0].classification == "mismatch"
|
||||
assert "documents DocumentedResponse but returns ActualResponse" in checks[0].reason
|
||||
|
||||
|
||||
def test_nested_returns_are_ignored_for_outer_control_flow(tmp_path: Path) -> None:
|
||||
checks = _checks_for_source(
|
||||
tmp_path,
|
||||
"""
|
||||
@ns.route("/stream")
|
||||
class StreamApi(Resource):
|
||||
@ns.response(200, "OK", ns.models[StreamResponse.__name__])
|
||||
def get(self):
|
||||
def generate_events():
|
||||
return dump_response(WrongResponse, {"event": "nested"}), 200
|
||||
|
||||
if finished:
|
||||
return dump_response(StreamResponse, {"event": "done"}), 200
|
||||
return dump_response(StreamResponse, {"event": "running"}), 200
|
||||
""",
|
||||
)
|
||||
|
||||
assert len(checks) == 1
|
||||
assert checks[0].classification == "valid"
|
||||
assert {actual.model for actual in checks[0].actual} == {"StreamResponse"}
|
||||
|
||||
|
||||
def test_response_contract_ignore_comment_skips_route_method(tmp_path: Path) -> None:
|
||||
checks = _checks_for_source(
|
||||
tmp_path,
|
||||
"""
|
||||
@ns.route("/binary")
|
||||
class BinaryApi(Resource):
|
||||
# response-contract:ignore binary response
|
||||
@ns.response(200, "Binary file")
|
||||
def get(self):
|
||||
return send_file(path)
|
||||
|
||||
|
||||
# response-contract:ignore compact Flask response
|
||||
@ns.route("/compact")
|
||||
class CompactApi(Resource):
|
||||
def get(self):
|
||||
return make_response({"url": "https://example.com"})
|
||||
|
||||
|
||||
@ns.route("/regular")
|
||||
class RegularApi(Resource):
|
||||
@ns.response(200, "OK", ns.models[RegularResponse.__name__])
|
||||
def get(self):
|
||||
return dump_response(RegularResponse, {})
|
||||
""",
|
||||
)
|
||||
|
||||
assert len(checks) == 1
|
||||
assert checks[0].class_name == "RegularApi"
|
||||
assert checks[0].classification == "valid"
|
||||
|
||||
|
||||
def test_method_ignore_comment_does_not_skip_sibling_methods(tmp_path: Path) -> None:
|
||||
checks = _checks_for_source(
|
||||
tmp_path,
|
||||
"""
|
||||
@ns.route("/mixed")
|
||||
class MixedApi(Resource):
|
||||
# response-contract:ignore binary response
|
||||
@ns.response(200, "Binary file")
|
||||
def get(self):
|
||||
return send_file(path)
|
||||
|
||||
@ns.response(200, "OK", ns.models[RegularResponse.__name__])
|
||||
def post(self):
|
||||
return dump_response(RegularResponse, {})
|
||||
""",
|
||||
)
|
||||
|
||||
assert len(checks) == 1
|
||||
assert checks[0].class_name == "MixedApi"
|
||||
assert checks[0].method == "post"
|
||||
assert checks[0].classification == "valid"
|
||||
|
||||
|
||||
def test_main_is_report_only_by_default_for_mismatches(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
controller_path = tmp_path / "controllers" / "sample.py"
|
||||
controller_path.parent.mkdir()
|
||||
controller_path.write_text(
|
||||
"""
|
||||
@ns.route("/bad")
|
||||
class BadDeleteApi(Resource):
|
||||
@ns.response(204, "Deleted")
|
||||
def delete(self):
|
||||
return {"result": "success"}, 204
|
||||
""",
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
monkeypatch.setattr(sys, "argv", ["lint_response_contracts.py", str(controller_path)])
|
||||
assert lint_response_contracts.main() == 0
|
||||
|
||||
monkeypatch.setattr(sys, "argv", ["lint_response_contracts.py", "--fail-on-mismatch", str(controller_path)])
|
||||
assert lint_response_contracts.main() == 1
|
||||
|
||||
|
||||
def test_main_hides_unknown_details_by_default(
|
||||
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
|
||||
) -> None:
|
||||
controller_path = tmp_path / "controllers" / "sample.py"
|
||||
controller_path.parent.mkdir()
|
||||
controller_path.write_text(
|
||||
"""
|
||||
@ns.route("/items")
|
||||
class ItemApi(Resource):
|
||||
@ns.response(200, "OK", ns.models[ItemResponse.__name__])
|
||||
def get(self):
|
||||
return dump_response(ItemResponse, item), status_code
|
||||
""",
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
monkeypatch.setattr(sys, "argv", ["lint_response_contracts.py", str(controller_path)])
|
||||
assert lint_response_contracts.main() == 0
|
||||
default_output = capsys.readouterr().out
|
||||
assert "1 unknown" in default_output
|
||||
assert "UNKNOWN:" not in default_output
|
||||
|
||||
monkeypatch.setattr(sys, "argv", ["lint_response_contracts.py", "--include-unknown", str(controller_path)])
|
||||
assert lint_response_contracts.main() == 0
|
||||
include_unknown_output = capsys.readouterr().out
|
||||
assert "UNKNOWN:" in include_unknown_output
|
||||
assert "non-literal or unsupported status" in include_unknown_output
|
||||
|
||||
|
||||
def test_class_level_route_and_response_docs_apply_to_methods(tmp_path: Path) -> None:
|
||||
checks = _checks_for_source(
|
||||
tmp_path,
|
||||
"""
|
||||
@ns.route(path="/items")
|
||||
@ns.response(code=200, description="OK", model=ns.models[ItemListResponse.__name__])
|
||||
class ItemListApi(Resource):
|
||||
def get(self):
|
||||
return dump_response(ItemListResponse, {"data": []}), 200
|
||||
""",
|
||||
)
|
||||
|
||||
assert len(checks) == 1
|
||||
assert checks[0].classification == "valid"
|
||||
assert checks[0].route == "/items"
|
||||
|
||||
|
||||
def test_unknown_reassignment_prevents_variable_model_dump_inference(tmp_path: Path) -> None:
|
||||
checks = _checks_for_source(
|
||||
tmp_path,
|
||||
"""
|
||||
@ns.route("/items")
|
||||
class ItemApi(Resource):
|
||||
@ns.response(200, "OK", ns.models[ItemResponse.__name__])
|
||||
def get(self):
|
||||
response = ItemResponse.model_validate(item)
|
||||
if refresh:
|
||||
response = load_response()
|
||||
return response.model_dump(mode="json"), 200
|
||||
""",
|
||||
)
|
||||
|
||||
assert len(checks) == 1
|
||||
assert checks[0].classification == "unknown"
|
||||
assert "returns unknown" in checks[0].reason
|
||||
|
||||
|
||||
def test_non_literal_status_is_unknown_not_defaulted_to_200(tmp_path: Path) -> None:
|
||||
checks = _checks_for_source(
|
||||
tmp_path,
|
||||
"""
|
||||
@ns.route("/items")
|
||||
class ItemApi(Resource):
|
||||
@ns.response(200, "OK", ns.models[ItemResponse.__name__])
|
||||
def get(self):
|
||||
return dump_response(ItemResponse, item), status_code
|
||||
""",
|
||||
)
|
||||
|
||||
assert len(checks) == 1
|
||||
assert checks[0].classification == "unknown"
|
||||
assert "non-literal or unsupported status" in checks[0].reason
|
||||
@@ -0,0 +1,75 @@
|
||||
"""Editor metadata must follow registered Python identities without changing live schemas."""
|
||||
|
||||
import inspect
|
||||
from collections.abc import Callable
|
||||
from copy import deepcopy
|
||||
from functools import wraps
|
||||
from pathlib import Path
|
||||
|
||||
from flask_restx import Api, Namespace, Resource
|
||||
from pydantic import BaseModel
|
||||
|
||||
from controllers.common.schema import register_schema_model, registered_schema_sources
|
||||
from dev.export_console_openapi import attach_api_sources, resolve_source_type, source_location
|
||||
|
||||
|
||||
class NavigationPayload(BaseModel):
|
||||
name: str
|
||||
|
||||
|
||||
class Container:
|
||||
class Nested(BaseModel):
|
||||
value: str
|
||||
|
||||
|
||||
def decorated[**P, R](handler: Callable[P, R]) -> Callable[P, R]:
|
||||
@wraps(handler)
|
||||
def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
|
||||
return handler(*args, **kwargs)
|
||||
|
||||
return wrapper
|
||||
|
||||
|
||||
class NavigationResource(Resource):
|
||||
@decorated
|
||||
def post(self) -> dict[str, str]:
|
||||
return {}
|
||||
|
||||
|
||||
def test_registered_models_and_decorated_operations_have_exact_origins() -> None:
|
||||
namespace = Namespace("navigation", path="/navigation")
|
||||
register_schema_model(namespace, NavigationPayload)
|
||||
namespace.add_resource(NavigationResource, "")
|
||||
api = Api()
|
||||
api.add_namespace(namespace)
|
||||
live_schema = deepcopy(namespace.models["NavigationPayload"].__schema__)
|
||||
document = {
|
||||
"components": {"schemas": {"NavigationPayload": deepcopy(live_schema), "Synthetic": {"type": "object"}}},
|
||||
"paths": {"/navigation": {"post": {"description": "Create"}}},
|
||||
}
|
||||
|
||||
attach_api_sources(document, api)
|
||||
|
||||
model_source = document["components"]["schemas"]["NavigationPayload"]["x-source-location"]
|
||||
assert model_source == {"file": str(Path(__file__).resolve()), "line": inspect.getsourcelines(NavigationPayload)[1]}
|
||||
operation_source = document["paths"]["/navigation"]["post"]["x-source-location"]
|
||||
expected_line = next(
|
||||
line
|
||||
for line, text in enumerate(Path(__file__).read_text().splitlines(), 1)
|
||||
if text.strip() == "def post(self) -> dict[str, str]:"
|
||||
)
|
||||
assert operation_source == {"file": str(Path(__file__).resolve()), "line": expected_line}
|
||||
assert "x-source-location" not in document["components"]["schemas"]["Synthetic"]
|
||||
assert namespace.models["NavigationPayload"].__schema__ == live_schema
|
||||
sources = registered_schema_sources(namespace)
|
||||
sources.clear()
|
||||
assert registered_schema_sources(namespace)["NavigationPayload"].endswith(".NavigationPayload")
|
||||
|
||||
|
||||
def test_exact_nested_and_generic_identities_resolve_without_name_guessing() -> None:
|
||||
assert resolve_source_type(f"{__name__}.Container.Nested") is Container.Nested
|
||||
assert resolve_source_type(f"{__name__}.Container.Nested[builtins.str]") is Container.Nested
|
||||
assert resolve_source_type("unknown.module.NavigationPayload") is None
|
||||
assert resolve_source_type(f"{__name__}.Missing.NavigationPayload") is None
|
||||
assert source_location(None) is None
|
||||
assert source_location(str) is None
|
||||
@@ -0,0 +1,160 @@
|
||||
"""Keep early CI sharding complete, disjoint, and independent of input order."""
|
||||
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
from dev.pytest_sharding import main, select_test_files
|
||||
|
||||
|
||||
def test_file_shards_cover_each_test_file_once(tmp_path: Path) -> None:
|
||||
unit = tmp_path / "unit"
|
||||
provider = tmp_path / "provider"
|
||||
controllers = unit / "controllers"
|
||||
expected = {
|
||||
unit / "test_a.py",
|
||||
unit / "nested" / "test_b.py",
|
||||
unit / "nested" / "feature_test.py",
|
||||
provider / "test_a.py",
|
||||
provider / "test_c.py",
|
||||
}
|
||||
for path in expected | {controllers / "test_controller.py", unit / "conftest.py", unit / "helper.py"}:
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.touch()
|
||||
|
||||
shards = [
|
||||
select_test_files([unit, provider, unit], shard_index=i, shard_total=3, ignored=[controllers])
|
||||
for i in range(1, 4)
|
||||
]
|
||||
selected = [path for shard in shards for path in shard]
|
||||
assert len(selected) == len(set(selected))
|
||||
assert set(selected) == expected
|
||||
assert max(map(len, shards)) - min(map(len, shards)) <= 1
|
||||
assert shards[1] == select_test_files([provider, unit], shard_index=2, shard_total=3, ignored=[controllers])
|
||||
|
||||
|
||||
@pytest.mark.parametrize(("index", "total"), [(0, 3), (4, 3), (1, 0), (1, -1)])
|
||||
def test_rejects_invalid_shard(tmp_path: Path, index: int, total: int) -> None:
|
||||
with pytest.raises(ValueError, match="shard-index"):
|
||||
select_test_files([tmp_path], shard_index=index, shard_total=total)
|
||||
|
||||
|
||||
def test_empty_shard_fails_instead_of_running_default_discovery(
|
||||
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
|
||||
) -> None:
|
||||
monkeypatch.setattr("sys.argv", ["pytest_sharding.py", "--shard-index", "1", "--shard-total", "3", str(tmp_path)])
|
||||
with pytest.raises(SystemExit) as exc:
|
||||
main()
|
||||
assert exc.value.code == 2
|
||||
captured = capsys.readouterr()
|
||||
assert captured.out == ""
|
||||
assert "No test files selected" in captured.err
|
||||
|
||||
|
||||
def test_duration_plan_balances_work_and_ignores_stale_history() -> None:
|
||||
from dev.pytest_sharding import build_plan
|
||||
|
||||
files = [Path(f"test_{name}.py") for name in "abcd"]
|
||||
durations = dict(zip((str(path) for path in files), [90.0, 80.0, 50.0, 40.0], strict=True))
|
||||
durations["deleted.py"] = 999.0
|
||||
plan = build_plan(files, durations, total=2, threshold=120)
|
||||
assert set(plan) == {str(path) for path in files}
|
||||
loads = [sum(durations[name] for name, targets in plan.items() if targets == [i]) for i in (1, 2)]
|
||||
assert loads == [130, 130]
|
||||
assert plan == build_plan(list(reversed(files)), durations, total=2, threshold=120)
|
||||
|
||||
|
||||
def test_logical_shards_cover_existing_and_new_cases_exactly_once() -> None:
|
||||
from dev.pytest_sharding import build_plan, case_shard
|
||||
|
||||
plan = build_plan([Path("test_large.py")], {"test_large.py": 250.0}, total=3, threshold=100)
|
||||
targets = plan["test_large.py"]
|
||||
assert sorted(targets) == [1, 2, 3]
|
||||
cases = [f"TestLarge::test_case[param-{i}]" for i in range(100)] + ["test_new"]
|
||||
partitions = [{case for case in cases if case_shard(case, targets) == shard} for shard in (1, 2, 3)]
|
||||
assert set.union(*partitions) == set(cases)
|
||||
assert sum(map(len, partitions)) == len(cases)
|
||||
assert all(partitions)
|
||||
|
||||
|
||||
def test_missing_or_corrupt_history_keeps_all_files(tmp_path: Path) -> None:
|
||||
from dev.pytest_sharding import build_plan, load_durations
|
||||
|
||||
path = tmp_path / "durations.json"
|
||||
assert load_durations(path) == {}
|
||||
for invalid in ["broken", "[]", "null"]:
|
||||
path.write_text(invalid)
|
||||
assert load_durations(path) == {}
|
||||
path.write_text('{"good": 2, "negative": -1, "nan": NaN, "bool": true, "string": "2"}')
|
||||
assert load_durations(path) == {"good": 2.0}
|
||||
files = [Path(f"test_{i}.py") for i in range(5)]
|
||||
assert list(build_plan(files, {}, total=2, threshold=60).values()) == [[1], [2], [1], [2], [1]]
|
||||
|
||||
|
||||
def test_plan_cli_selects_only_files_assigned_to_shard(
|
||||
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
|
||||
) -> None:
|
||||
import json
|
||||
|
||||
plan = tmp_path / "plan.json"
|
||||
plan.write_text(json.dumps({"api/test_a.py": [1], "api/test_b.py": [2], "api/test_big.py": [1, 2]}))
|
||||
monkeypatch.setattr(
|
||||
"sys.argv", ["pytest_sharding.py", "--shard-index", "2", "--shard-total", "2", "--plan", str(plan), "api"]
|
||||
)
|
||||
main()
|
||||
assert capsys.readouterr().out.splitlines() == ["api/test_b.py", "api/test_big.py"]
|
||||
|
||||
|
||||
@pytest.mark.parametrize("with_history", [False, True])
|
||||
def test_cli_freezes_current_files_and_every_shard_consumes_the_same_plan(
|
||||
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], with_history: bool
|
||||
) -> None:
|
||||
import json
|
||||
|
||||
root = tmp_path / "tests"
|
||||
root.mkdir()
|
||||
slow = root / "test_slow.py"
|
||||
new = root / "test_new.py"
|
||||
for path in (slow, new, root / "helper.py"):
|
||||
path.touch()
|
||||
history = tmp_path / "history.json"
|
||||
history.write_text(json.dumps({str(slow): 100, str(root / "test_deleted.py"): 1000}))
|
||||
plan_path = tmp_path / "plan.json"
|
||||
arguments = ["pytest_sharding.py", "--shard-index", "1", "--shard-total", "2", "--write-plan", str(plan_path)]
|
||||
if with_history:
|
||||
arguments.extend(["--durations", str(history)])
|
||||
monkeypatch.setattr("sys.argv", [*arguments, str(root)])
|
||||
main()
|
||||
assert capsys.readouterr().out == ""
|
||||
plan = json.loads(plan_path.read_text())
|
||||
assert set(plan) == {str(slow), str(new)}
|
||||
if with_history:
|
||||
assert sorted(plan[str(slow)]) == [1, 2]
|
||||
selected: set[str] = set()
|
||||
for shard in (1, 2):
|
||||
monkeypatch.setattr(
|
||||
"sys.argv",
|
||||
[
|
||||
"pytest_sharding.py",
|
||||
"--shard-index",
|
||||
str(shard),
|
||||
"--shard-total",
|
||||
"2",
|
||||
"--plan",
|
||||
str(plan_path),
|
||||
str(root),
|
||||
],
|
||||
)
|
||||
main()
|
||||
files = capsys.readouterr().out.splitlines()
|
||||
assert set(files) == {name for name, targets in plan.items() if shard in targets}
|
||||
selected.update(files)
|
||||
assert selected == {str(slow), str(new)}
|
||||
|
||||
|
||||
@pytest.mark.parametrize("threshold", [0, -1, float("nan")])
|
||||
def test_invalid_logical_split_threshold_is_rejected(threshold: float) -> None:
|
||||
from dev.pytest_sharding import build_plan
|
||||
|
||||
with pytest.raises(ValueError, match="positive"):
|
||||
build_plan([Path("test_a.py")], {"test_a.py": 10.0}, total=2, threshold=threshold)
|
||||
Reference in new issue
Block a user