chore: 纳入本地 Dify 1.19.0 源码及品牌与免登改动

演示目录只保留可重建的源码。运行密钥、数据卷、依赖和带口令的本地配置不进入仓库。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
wuzilongandCursor committed 2026-11-18 13:59:25 +08:00
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)