Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

test(plugins): pin entry-point loader contract across load, isolation, duplicate and gating paths (#1740)

evan188199-techa325ddfbbd88
diff --git a/evidence/test-plugins-loader-20261004/README.md b/evidence/test-plugins-loader-20261004/README.md
new file mode 100644
index 000000000..4a92614af
--- /dev/null
+++ b/evidence/test-plugins-loader-20261004/README.md
@@ -0,0 +1,54 @@
+# test: plugins entry-point loader contract tests
+
+Branch: `test/plugins-entrypoint-loader-20261004` (based on `origin/main` @ `ef2d9e5c3`)
+
+## Scope
+
+New file `tests/plugins/test_entrypoint_loader.py` — 13 contract tests pinning the
+current behaviour of the entry-point loader stack, as groundwork for upstream
+#961 (learning resource providers with lifecycle controls) and #1307 (managed
+third-party plugin platform). No product code was modified.
+
+Layers exercised:
+
+- `deeptutor/core/entry_points.py` — shared `load_entry_point_group` plumbing
+- `deeptutor/plugins/loader.py` — `discover_plugins` / `load_plugin_capability`
+- `deeptutor/runtime/registry/capability_registry.py` — `CapabilityRegistry.load_plugins`
+
+## Path families covered (asserting current real behaviour)
+
+1. **Normal loading** — clean entry points are coerced in order (`load_entry_point_group`);
+ class- and instance-yielding plugins produce manifests (`discover_plugins`); the
+ canonical `deeptutor.extensions` group registers into the registry.
+2. **Missing dependencies** — an entry point raising `ModuleNotFoundError` at load is
+ skipped while others load; instantiation via `load_plugin_capability` propagates a
+ missing module (discovery isolates, instantiation does not); a legacy manifest whose
+ entry cannot import aborts the remaining legacy manifests (logged only at debug).
+3. **Load-error isolation** — a raising entry point is skipped with a warning naming the
+ group and entry point; a failing group read returns `[]` with a warning; a coercer
+ returning `None` rejects without error.
+4. **Duplicate registration** — two canonical entry points shipping the same capability
+ name keep the first and warn "already registered"; a legacy plugin with a taken name
+ is skipped after canonical wins, and legacy-group presence emits a `DeprecationWarning`.
+5. **Disable-gating status quo** — `PluginManifest` has no `enabled`/`disabled` field
+ (structural fields only), and the only gates are structural (empty entry,
+ `tool.py` entry, non-capability `type`) and short-circuit before resolving the entry,
+ so a gated manifest never imports its target.
+
+## Commands and results
+
+```
+python -m pytest -q -p no:cacheprovider tests/plugins/test_entrypoint_loader.py
+→ 13 passed, 1 warning in 0.27s
+
+python -m pytest -q -p no:cacheprovider tests/plugins/
+→ 19 passed, 2 warnings in 0.25s (13 new + 6 pre-existing in test_loader.py)
+
+python -m ruff check tests/plugins/test_entrypoint_loader.py
+→ All checks passed!
+```
+
+Full verbose run: `pytest-output.txt`.
+
+Environment: Python 3.13.13, pytest 9.1.1, shared repo venv; worktree of
+`/Users/Shared/DeepTutor` at `origin/main` (`ef2d9e5c3`, release v1.6.12).
diff --git a/evidence/test-plugins-loader-20261004/pytest-output.txt b/evidence/test-plugins-loader-20261004/pytest-output.txt
new file mode 100644
index 000000000..5a9743efd
--- /dev/null
+++ b/evidence/test-plugins-loader-20261004/pytest-output.txt
@@ -0,0 +1,12 @@
+============================= test session starts ==============================
+platform darwin -- Python 3.13.13, pytest-9.1.1, pluggy-1.6.0
+rootdir: /Users/xzh/services/ai-development/multica-pilot/workspaces/agents-plan-5fede2af789a/agen-480-1c472ac18bc5/workdir/dt-plugins-loader-wt
+configfile: pyproject.toml
+plugins: cov-7.1.0, devtools-0.12.2, asyncio-1.4.0, anyio-4.14.2
+asyncio: mode=Mode.STRICT, debug=False, asyncio_default_fixture_loop_scope=function, asyncio_default_test_loop_scope=function
+collected 19 items
+
+tests/plugins/test_entrypoint_loader.py ............. [ 68%]
+tests/plugins/test_loader.py ...... [100%]
+
+======================== 19 passed, 2 warnings in 0.29s ========================
diff --git a/tests/plugins/test_entrypoint_loader.py b/tests/plugins/test_entrypoint_loader.py
new file mode 100644
index 000000000..39b268e32
--- /dev/null
+++ b/tests/plugins/test_entrypoint_loader.py
@@ -0,0 +1,370 @@
+"""Contract tests for the plugins entry-point loader.
+
+These pin the *current* behaviour of the three layers that turn entry-point
+registrations into registered capabilities — the shared plumbing in
+``deeptutor.core.entry_points``, the neutral discovery in
+``deeptutor.plugins.loader``, and ``CapabilityRegistry.load_plugins`` — so the
+managed-plugin slices (upstream #961 / #1307) extend a documented contract
+instead of an accident.
+
+Five path families are covered:
+
+* normal loading
+* missing dependencies
+* load-error isolation
+* duplicate registration
+* disable-gating status quo (structural gates only, no user toggle)
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import logging
+from types import SimpleNamespace
+
+import pytest
+
+from deeptutor.core.capability_protocol import CapabilityManifest, TurnCapability
+from deeptutor.core.context import UnifiedContext
+import deeptutor.core.entry_points as ep_module
+from deeptutor.plugins.loader import (
+ PluginManifest,
+ discover_plugins,
+ load_plugin_capability,
+)
+from deeptutor.runtime.registry.capability_registry import CapabilityRegistry
+from deeptutor.runtime.stream_bus import StreamBus
+
+PLUGINS_GROUP = "deeptutor.plugins"
+EXTENSIONS_GROUP = "deeptutor.extensions"
+PLUGINS_LOGGER = "deeptutor.plugins.loader"
+PLUMBING_LOGGER = "deeptutor.core.entry_points"
+REGISTRY_LOGGER = "deeptutor.runtime.registry.capability_registry"
+
+
+class _PluginCap(TurnCapability):
+ manifest = CapabilityManifest(
+ name="plugin_cap",
+ description="Capability provided by a plugin entry point.",
+ stages=["responding"],
+ )
+
+ async def run(self, context: UnifiedContext, stream: StreamBus) -> None:
+ return None
+
+
+class _PluginCapBis(TurnCapability):
+ """Different plugin class, same declared capability name as _PluginCap."""
+
+ manifest = CapabilityManifest(
+ name="plugin_cap",
+ description="Second plugin shipping the same capability name.",
+ stages=["responding"],
+ )
+
+ async def run(self, context: UnifiedContext, stream: StreamBus) -> None:
+ return None
+
+
+class _OtherCap(TurnCapability):
+ manifest = CapabilityManifest(
+ name="other_cap",
+ description="Second plugin capability with its own name.",
+ stages=["responding"],
+ )
+
+ async def run(self, context: UnifiedContext, stream: StreamBus) -> None:
+ return None
+
+
+def _make_missing_module_capability() -> type[TurnCapability]:
+ """Capability class whose qualified entry points at a module that is not installed."""
+
+ async def _run(self, context: UnifiedContext, stream: StreamBus) -> None:
+ return None
+
+ cls = type(
+ "_MissingModuleCap",
+ (TurnCapability,),
+ {
+ "manifest": CapabilityManifest(
+ name="missing_cap",
+ description="Capability whose module cannot be imported.",
+ stages=["responding"],
+ ),
+ "run": _run,
+ },
+ )
+ cls.__module__ = "tests.plugins._no_such_module"
+ return cls
+
+
+def _ep(name: str, load):
+ return SimpleNamespace(name=name, load=load)
+
+
+def _fake_groups(groups: dict[str, list]):
+ def fake_entry_points(*, group: str):
+ return list(groups.get(group, []))
+
+ return fake_entry_points
+
+
+# ---------------------------------------------------------------------------
+# Normal loading
+# ---------------------------------------------------------------------------
+
+
+def test_load_entry_point_group_returns_coerced_values_in_order(monkeypatch):
+ monkeypatch.setattr(
+ ep_module,
+ "entry_points",
+ _fake_groups({"g": [_ep("a", lambda: "A"), _ep("b", lambda: "B")]}),
+ )
+ loaded = ep_module.load_entry_point_group("g", lambda _name, obj: obj)
+ assert loaded == ["A", "B"]
+
+
+def test_discover_plugins_normal_load_from_class_and_instance(monkeypatch):
+ monkeypatch.setattr(
+ ep_module,
+ "entry_points",
+ _fake_groups(
+ {
+ PLUGINS_GROUP: [
+ _ep("plugin_cap", lambda: _PluginCap),
+ _ep("other_cap", lambda: _OtherCap()),
+ ]
+ }
+ ),
+ )
+ manifests = discover_plugins()
+ assert [m.name for m in manifests] == ["plugin_cap", "other_cap"]
+ by_name = {m.name: m for m in manifests}
+ for manifest in by_name.values():
+ assert manifest.type == "capability"
+ assert manifest.stages == ["responding"]
+ assert ":" in manifest.entry
+ assert by_name["plugin_cap"].entry.endswith("_PluginCap")
+ assert by_name["other_cap"].entry.endswith("_OtherCap")
+
+
+def test_registry_load_plugins_loads_canonical_extensions_group(monkeypatch):
+ monkeypatch.setattr(
+ ep_module,
+ "entry_points",
+ _fake_groups({EXTENSIONS_GROUP: [_ep("plugin_cap", lambda: _PluginCap)]}),
+ )
+ reg = CapabilityRegistry()
+ reg.load_plugins()
+ assert isinstance(reg.get("plugin_cap"), _PluginCap)
+
+
+# ---------------------------------------------------------------------------
+# Missing dependencies
+# ---------------------------------------------------------------------------
+
+
+def test_missing_dependency_entry_point_is_skipped_others_still_load(monkeypatch, caplog):
+ def _missing_dep():
+ raise ModuleNotFoundError("No module named 'plugin_dep'")
+
+ monkeypatch.setattr(
+ ep_module,
+ "entry_points",
+ _fake_groups(
+ {
+ PLUGINS_GROUP: [
+ _ep("needs_dep", _missing_dep),
+ _ep("plugin_cap", lambda: _PluginCap),
+ ]
+ }
+ ),
+ )
+ with caplog.at_level(logging.WARNING, logger=PLUGINS_LOGGER):
+ manifests = discover_plugins()
+ assert [m.name for m in manifests] == ["plugin_cap"]
+ assert any("needs_dep" in record.getMessage() for record in caplog.records)
+
+
+def test_load_plugin_capability_propagates_missing_module():
+ """Discovery isolates import failures; instantiation does not (current contract)."""
+
+ manifest = PluginManifest(
+ name="gone_cap",
+ type="capability",
+ entry="tests.plugins._no_such_module:Cap",
+ )
+ with pytest.raises(ModuleNotFoundError):
+ load_plugin_capability(manifest)
+
+
+def test_legacy_instantiation_error_aborts_remaining_legacy_manifests(monkeypatch, caplog):
+ """A legacy manifest that fails to instantiate drops every manifest after it."""
+
+ missing_cls = _make_missing_module_capability()
+ monkeypatch.setattr(
+ ep_module,
+ "entry_points",
+ _fake_groups(
+ {
+ EXTENSIONS_GROUP: [],
+ PLUGINS_GROUP: [
+ _ep("good_first", lambda: _PluginCap),
+ _ep("needs_dep", lambda: missing_cls),
+ _ep("good_after", lambda: _OtherCap),
+ ],
+ }
+ ),
+ )
+ reg = CapabilityRegistry()
+ with caplog.at_level(logging.DEBUG, logger=REGISTRY_LOGGER):
+ reg.load_plugins()
+ assert isinstance(reg.get("plugin_cap"), _PluginCap)
+ assert reg.get("other_cap") is None
+ assert any(
+ "Legacy plugin loader unavailable" in record.getMessage() for record in caplog.records
+ )
+
+
+# ---------------------------------------------------------------------------
+# Load-error isolation
+# ---------------------------------------------------------------------------
+
+
+def test_entry_point_load_error_is_isolated_and_named_in_warning(monkeypatch, caplog):
+ def _boom():
+ raise RuntimeError("boom at import time")
+
+ monkeypatch.setattr(
+ ep_module,
+ "entry_points",
+ _fake_groups(
+ {
+ PLUGINS_GROUP: [
+ _ep("bad", _boom),
+ _ep("plugin_cap", lambda: _PluginCap),
+ _ep("worse", _boom),
+ ]
+ }
+ ),
+ )
+ with caplog.at_level(logging.WARNING, logger=PLUGINS_LOGGER):
+ manifests = discover_plugins()
+ assert [m.name for m in manifests] == ["plugin_cap"]
+ assert any(
+ PLUGINS_GROUP in message and "skipping" in message
+ for message in (record.getMessage() for record in caplog.records)
+ )
+
+
+def test_group_read_failure_returns_empty_with_warning(monkeypatch, caplog):
+ def _broken_reader(*, group: str):
+ raise RuntimeError("metadata reader exploded")
+
+ monkeypatch.setattr(ep_module, "entry_points", _broken_reader)
+ with caplog.at_level(logging.WARNING, logger=PLUMBING_LOGGER):
+ loaded = ep_module.load_entry_point_group(PLUGINS_GROUP, lambda _name, obj: obj)
+ assert loaded == []
+ assert any(PLUGINS_GROUP in record.getMessage() for record in caplog.records)
+
+
+def test_coercer_none_rejects_entry_point_without_error(monkeypatch):
+ monkeypatch.setattr(
+ ep_module,
+ "entry_points",
+ _fake_groups({"g": [_ep("junk", lambda: object()), _ep("keep", lambda: "kept")]}),
+ )
+ loaded = ep_module.load_entry_point_group(
+ "g", lambda name, obj: obj if name == "keep" else None
+ )
+ assert loaded == ["kept"]
+
+
+# ---------------------------------------------------------------------------
+# Duplicate registration
+# ---------------------------------------------------------------------------
+
+
+def test_duplicate_extension_registration_first_wins_with_warning(monkeypatch, caplog):
+ monkeypatch.setattr(
+ ep_module,
+ "entry_points",
+ _fake_groups(
+ {
+ EXTENSIONS_GROUP: [
+ _ep("first_ship", lambda: _PluginCap),
+ _ep("second_ship", lambda: _PluginCapBis),
+ ]
+ }
+ ),
+ )
+ reg = CapabilityRegistry()
+ with caplog.at_level(logging.WARNING, logger=REGISTRY_LOGGER):
+ reg.load_plugins()
+ assert reg.list_capabilities().count("plugin_cap") == 1
+ cap = reg.get("plugin_cap")
+ assert isinstance(cap, _PluginCap)
+ assert any(
+ "second_ship" in record.getMessage() and "already registered" in record.getMessage()
+ for record in caplog.records
+ )
+
+
+def test_legacy_plugin_with_taken_name_is_ignored(monkeypatch):
+ """Canonical registrations win; a same-named legacy plugin is skipped, and the
+ legacy group's presence is announced with a DeprecationWarning."""
+
+ monkeypatch.setattr(
+ ep_module,
+ "entry_points",
+ _fake_groups(
+ {
+ EXTENSIONS_GROUP: [_ep("plugin_cap", lambda: _PluginCap)],
+ PLUGINS_GROUP: [_ep("legacy_dup", lambda: _PluginCapBis)],
+ }
+ ),
+ )
+ reg = CapabilityRegistry()
+ with pytest.warns(DeprecationWarning, match="deprecated"):
+ reg.load_plugins()
+ assert reg.list_capabilities().count("plugin_cap") == 1
+ assert isinstance(reg.get("plugin_cap"), _PluginCap)
+
+
+# ---------------------------------------------------------------------------
+# Disable-gating status quo
+# ---------------------------------------------------------------------------
+
+
+def test_plugin_manifest_has_no_enable_disable_gate():
+ """Today a plugin cannot be disabled declaratively: PluginManifest carries no
+ enabled/disabled flag, and the loader consults none."""
+
+ field_names = {f.name for f in dataclasses.fields(PluginManifest)}
+ assert field_names == {
+ "name",
+ "type",
+ "description",
+ "stages",
+ "version",
+ "author",
+ "entry",
+ }
+ assert not field_names & {"enabled", "disabled"}
+
+
+def test_structural_gates_short_circuit_before_resolving_entry():
+ """The only gates are structural (entry / type) and run before any import, so a
+ gated manifest never triggers its (here broken) entry point."""
+
+ empty_entry = PluginManifest(name="t1", type="capability", entry="")
+ tool_script = PluginManifest(name="t2", type="capability", entry="tests/plugins/tool.py")
+ wrong_type = PluginManifest(
+ name="t3",
+ type="tool",
+ entry="tests.plugins._no_such_module:Cap",
+ )
+ assert load_plugin_capability(empty_entry) is None
+ assert load_plugin_capability(tool_script) is None
+ assert load_plugin_capability(wrong_type) is None