46 more unit tests, and `vm-mcp` rewritten around the new split (21 subtests, up from 14). `test_mcp_resources.py` is the new file and its subject is what the resource layer actually decides: which entry a URI resolves to, which query parameters it will accept, and the argv each read builds. The cases that matter are the ones a reshuffle would quietly break -- a literal route beating a template (`hhstream://sessions` is the listing, not a session with a blank id), a switch parameter becoming a bare flag or nothing at all (`--all=false` is not something the CLI takes), an undeclared parameter being refused rather than dropped, a frame's media type being sniffed rather than assumed, and a refusal being *raised* instead of returned as the body. One test exists only to stop a future kindness: there must be no resource for the reconciling container read, because that one writes. `test_mcp_server.py` grows the protocol-level half -- both listings, a read that returns JSON, a read that returns a blob, a refused read arriving as `McpError`, and a toolset selection that narrows the tools while leaving the resources alone. The tool and toolset tests move with the surface: the read-only verbs are asserted *absent* by name rather than merely missing, so re-adding one is a failure instead of a silent widening of what mcp-v2 narrowed. In the guest, the subtest the whole surface turns on is now measured rather than described: two reads of `hhstream://sessions/<id>` must NOT move the idle deadline, and `session_touch` must. It also asks for the same container two ways and checks the answers agree, reads one output's frame as a blob and confirms the `shot` tool reports the same geometry, and proves `--toolsets` makes an omitted tool unreachable and not merely unlisted. `checks/lib/mcp_client.py` gains `--resources`, `--read` and `--server-arg`, and exits 3 rather than 2 on a protocol error -- so "the server refused this read" stays distinguishable from "the server did not answer at all", which is the distinction that keeps the refusal subtests from passing for the wrong reason. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
390 lines
14 KiB
Python
390 lines
14 KiB
Python
"""The runner: how the CLI is called in process, decoded, and mapped to a code.
|
|
|
|
Most of this drives a recording stand-in (:class:`mcp_fake.FakeCli`), because
|
|
the subject is what this layer decides -- the argv list and the mapping. Three
|
|
tests drive the **real** entry point, against a control socket that does not
|
|
exist: that is the honest way to prove the dispatch, the capture and the
|
|
exit-code mapping against the CLI's actual parser without standing a daemon up.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import contextlib
|
|
import os
|
|
import signal
|
|
|
|
import mcp_fake
|
|
import pytest
|
|
from hhstreamd.protocol import ExitCode
|
|
from hhstream_mcp import invoke, media
|
|
|
|
|
|
@pytest.fixture(autouse=True)
|
|
def _isolated(monkeypatch, tmp_path):
|
|
mcp_fake.isolate(monkeypatch, tmp_path)
|
|
|
|
|
|
# ── the call ───────────────────────────────────────────────────────────────
|
|
|
|
|
|
def test_the_argv_reaches_the_entry_point_unchanged():
|
|
fake = mcp_fake.FakeCli(stdout="hello\n")
|
|
outcome = invoke.Runner(fake).run(["session", "list", "--json"])
|
|
|
|
assert outcome.ok
|
|
assert outcome.stdout == "hello\n"
|
|
assert fake.argv == ["session", "list", "--json"]
|
|
assert outcome.argv == ["session", "list", "--json"]
|
|
|
|
|
|
def test_a_metacharacter_is_one_argument_and_never_a_statement():
|
|
"""There is no shell between a tool and the CLI, and no string either."""
|
|
|
|
fake = mcp_fake.FakeCli()
|
|
nasty = "; rm -rf / #"
|
|
invoke.Runner(fake).run(["session", "keyboard", "type", "--", "s1", nasty])
|
|
|
|
assert fake.argv == ["session", "keyboard", "type", "--", "s1", nasty]
|
|
|
|
|
|
def test_what_the_cli_prints_is_captured_and_not_leaked_to_the_transport(capsys):
|
|
"""A print on stdout here would be a parse error at the client."""
|
|
|
|
fake = mcp_fake.FakeCli(stdout="on stdout\n", stderr="on stderr\n")
|
|
outcome = invoke.Runner(fake).run(["status"])
|
|
|
|
assert outcome.stdout == "on stdout\n"
|
|
assert outcome.stderr == "on stderr\n"
|
|
escaped = capsys.readouterr()
|
|
assert escaped.out == ""
|
|
assert escaped.err == ""
|
|
|
|
|
|
def test_sys_exit_is_the_exit_code_a_process_would_have_had():
|
|
"""argparse refuses with `sys.exit(2)`; handlers exit on a missing tool."""
|
|
|
|
fake = mcp_fake.FakeCli(raises=SystemExit(2))
|
|
assert invoke.Runner(fake).run(["session"]).returncode == int(ExitCode.USAGE)
|
|
|
|
# `sys.exit("message")` is status 1 in a real process, and the message is
|
|
# the exit code object rather than something printed.
|
|
fake = mcp_fake.FakeCli(raises=SystemExit("hhstream: grim is not on PATH"))
|
|
assert invoke.Runner(fake).run(["shot"]).returncode == invoke.GENERIC_FAILURE
|
|
|
|
fake = mcp_fake.FakeCli(raises=SystemExit(None))
|
|
assert invoke.Runner(fake).run(["status"]).returncode == 0
|
|
|
|
|
|
def test_an_uncaught_exception_becomes_exit_one_with_its_traceback():
|
|
"""What a CLI process would have done, rather than a transport error."""
|
|
|
|
fake = mcp_fake.FakeCli(raises=RuntimeError("boom"))
|
|
outcome = invoke.Runner(fake).run(["session", "list", "--json"])
|
|
|
|
assert outcome.returncode == invoke.GENERIC_FAILURE
|
|
assert "RuntimeError: boom" in outcome.stderr
|
|
assert "Traceback" in outcome.stderr
|
|
|
|
|
|
def test_a_keyboard_interrupt_is_not_swallowed_as_a_tool_result():
|
|
"""BaseException is caught on purpose; the code still says "failed"."""
|
|
|
|
fake = mcp_fake.FakeCli(raises=KeyboardInterrupt())
|
|
outcome = invoke.Runner(fake).run(["session", "list"])
|
|
assert outcome.returncode == invoke.GENERIC_FAILURE
|
|
|
|
|
|
def test_a_call_runs_with_the_serialising_lock_held():
|
|
"""The CLI prints to a process-global stdout, so one call at a time.
|
|
|
|
Asserted from inside the call rather than by racing two threads and hoping
|
|
their output interleaves: a race that passes by luck is not a test. The
|
|
private name is the point -- what is being asserted is that this specific
|
|
lock is held while a handler runs.
|
|
"""
|
|
|
|
def probing(argv):
|
|
free = invoke._ONE_AT_A_TIME.acquire(blocking=False)
|
|
if free:
|
|
invoke._ONE_AT_A_TIME.release()
|
|
print("free" if free else "held", end="")
|
|
return 0
|
|
|
|
assert invoke.Runner(probing).run(["status"]).stdout == "held"
|
|
|
|
|
|
# ── decoding ───────────────────────────────────────────────────────────────
|
|
|
|
|
|
def test_the_protocol_object_is_read_from_stdout_on_success():
|
|
fields = {"ok": True, "id": "s-1", "session": {"state": "running"}}
|
|
fake = mcp_fake.FakeCli(stdout=mcp_fake.reply(**fields))
|
|
assert invoke.Runner(fake).run(["session", "status", "--json"]).payload() == fields
|
|
|
|
|
|
def test_the_protocol_object_is_read_from_stderr_on_failure():
|
|
"""The CLI's own split: an error goes to stderr whatever the output mode."""
|
|
|
|
fields = {"ok": False, "error": "no_lease", "reason": "no pointer lease for s-1"}
|
|
fake = mcp_fake.FakeCli(
|
|
stderr=mcp_fake.reply(**fields), exit_code=int(ExitCode.NO_LEASE)
|
|
)
|
|
outcome = invoke.Runner(fake).run(["session", "pointer", "click", "--json"])
|
|
|
|
assert not outcome.ok
|
|
assert outcome.payload() == fields
|
|
|
|
|
|
def test_an_object_printed_under_a_bare_line_is_still_found():
|
|
"""`session start` prints the id beside its object; parsing must survive it."""
|
|
|
|
fake = mcp_fake.FakeCli(stdout='s-1\n{\n "ok": true,\n "id": "s-1"\n}\n')
|
|
assert invoke.Runner(fake).run(["session", "start"]).payload() == {
|
|
"ok": True,
|
|
"id": "s-1",
|
|
}
|
|
|
|
|
|
def test_no_json_at_all_is_none_rather_than_an_invention():
|
|
fake = mcp_fake.FakeCli(stdout="services:\n hyprland-headless.service active\n")
|
|
assert invoke.Runner(fake).run(["status"]).payload() is None
|
|
|
|
|
|
def test_a_json_array_is_not_mistaken_for_the_protocol_object():
|
|
assert invoke.first_json_object("[1, 2, 3]") is None
|
|
assert invoke.first_json_object('[{"a": 1}]') == {"a": 1}
|
|
|
|
|
|
# ── the real entry point, with nothing listening ───────────────────────────
|
|
|
|
|
|
def test_the_real_cli_refuses_a_bad_flag_with_the_frozen_usage_code():
|
|
"""argparse's own refusal, through the CLI's own parser, mapped to exit 2."""
|
|
|
|
outcome = invoke.Runner().run(
|
|
["session", "pointer", "click", "--json", "--button=nonsense", "--", "s-1"]
|
|
)
|
|
|
|
assert outcome.returncode == int(ExitCode.USAGE)
|
|
assert "invalid choice" in outcome.stderr
|
|
# And nothing escaped onto the real stdout: argparse prints usage there for
|
|
# --help and to stderr for an error, and both are captured.
|
|
assert outcome.stdout == ""
|
|
|
|
|
|
def test_the_real_cli_reports_an_unreachable_broker_as_the_frozen_code():
|
|
"""No socket, no daemon, no fake: the mapping end to end."""
|
|
|
|
outcome = invoke.Runner().run(["session", "list", "--json"])
|
|
|
|
assert outcome.returncode == int(ExitCode.DAEMON_UNREACHABLE)
|
|
payload = outcome.payload()
|
|
assert payload is not None
|
|
assert payload["error"] == "daemon_unreachable"
|
|
|
|
|
|
def test_the_real_cli_refuses_a_gesture_with_no_lease_without_a_broker():
|
|
"""Exit 9 is produced by the CLI before the socket is touched at all."""
|
|
|
|
outcome = invoke.Runner().run(
|
|
["session", "pointer", "click", "--json", "--", "s-1"]
|
|
)
|
|
|
|
assert outcome.returncode == int(ExitCode.NO_LEASE)
|
|
assert (outcome.payload() or {}).get("error") == "no_lease"
|
|
|
|
|
|
def test_an_unreachable_frame_socket_earns_the_hint_the_sg_re_exec_replaces():
|
|
"""The one capability lost by calling the CLI in process, said out loud."""
|
|
|
|
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=1)).run(["shot"])
|
|
|
|
assert "cannot read" in outcome.stderr
|
|
assert "sg hhstream" in outcome.stderr
|
|
|
|
|
|
def test_the_hint_is_absent_when_the_socket_is_readable(tmp_path, monkeypatch):
|
|
readable = tmp_path / "stream.sock"
|
|
readable.write_bytes(b"")
|
|
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(readable))
|
|
|
|
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=1)).run(["shot"])
|
|
assert "sg hhstream" not in outcome.stderr
|
|
|
|
|
|
def test_a_session_verb_never_earns_the_frame_socket_hint():
|
|
"""It has nothing to do with the control socket, so it must not be offered."""
|
|
|
|
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=int(ExitCode.BUSY))).run(
|
|
["session", "pointer", "acquire", "--json", "--", "s-1"]
|
|
)
|
|
assert "sg hhstream" not in outcome.stderr
|
|
|
|
|
|
# ── the exit-code table ────────────────────────────────────────────────────
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
"code",
|
|
[
|
|
ExitCode.USAGE,
|
|
ExitCode.NO_SUCH_SESSION,
|
|
ExitCode.BAD_STATE,
|
|
ExitCode.DAEMON_UNREACHABLE,
|
|
ExitCode.POLICY,
|
|
ExitCode.TIMEOUT,
|
|
ExitCode.BUSY,
|
|
ExitCode.NO_LEASE,
|
|
ExitCode.COMPOSITOR,
|
|
],
|
|
)
|
|
def test_every_frozen_exit_code_has_a_remedy_naming_itself(code):
|
|
"""A new code in the frozen table must not fall through to a generic line."""
|
|
|
|
text = invoke.remedy_for(int(code))
|
|
assert text.startswith(f"exit {int(code)} ({code.name})")
|
|
assert int(code) in invoke.REMEDY
|
|
|
|
|
|
def test_the_lease_codes_say_the_two_different_things_an_agent_must_do():
|
|
"""8 and 9 are the pair that must never read alike (CONTRACT-sessions.md §4)."""
|
|
|
|
busy = invoke.remedy_for(int(ExitCode.BUSY))
|
|
none_held = invoke.remedy_for(int(ExitCode.NO_LEASE))
|
|
|
|
assert "hhstream://pointer" in busy and "wait" in busy
|
|
assert "pointer_acquire" in none_held
|
|
# "acquire one" must not be the advice for BUSY: that is the one confusion
|
|
# the two codes exist to prevent.
|
|
assert "pointer_acquire" not in busy
|
|
|
|
|
|
def test_an_unclassified_code_is_still_a_failure_and_says_so():
|
|
text = invoke.remedy_for(42)
|
|
assert "exit 42 (UNCLASSIFIED)" in text
|
|
assert "do not assume anything happened" in text
|
|
|
|
|
|
def test_generic_failure_is_its_own_case():
|
|
"""Exit 1 is the frame verbs', and is not in the broker's frozen table."""
|
|
|
|
assert invoke.GENERIC_FAILURE not in [int(code) for code in ExitCode]
|
|
assert "grim" in invoke.remedy_for(invoke.GENERIC_FAILURE)
|
|
|
|
|
|
# ── launch, for `run` ──────────────────────────────────────────────────────
|
|
|
|
|
|
def test_launch_leaves_the_application_running_in_its_own_session(wayland):
|
|
"""`run` launches and forgets, and a killed server must not take it along."""
|
|
|
|
spawned = invoke.Runner().launch(["sleep", "30"], settle=0.3)
|
|
try:
|
|
assert not spawned.exited
|
|
assert spawned.pid > 0
|
|
os.kill(spawned.pid, 0)
|
|
# Its own session, so a client that kills this server's process group
|
|
# does not kill the desktop with it.
|
|
assert os.getsid(spawned.pid) == spawned.pid
|
|
assert os.getsid(spawned.pid) != os.getsid(0)
|
|
finally:
|
|
with contextlib.suppress(ProcessLookupError):
|
|
os.kill(spawned.pid, signal.SIGTERM)
|
|
|
|
|
|
def test_launch_reports_an_application_that_died_inside_the_window(wayland):
|
|
spawned = invoke.Runner().launch(["false"], settle=5.0)
|
|
|
|
assert spawned.exited
|
|
assert spawned.pid > 0
|
|
|
|
|
|
def test_launch_hands_back_what_a_failing_application_said(wayland):
|
|
spawned = invoke.Runner().launch(
|
|
["sh", "-c", "echo 'cannot open display' >&2; exit 3"], settle=5.0
|
|
)
|
|
|
|
assert spawned.exited
|
|
assert "cannot open display" in spawned.stderr
|
|
|
|
|
|
def test_launch_refuses_a_command_that_is_not_on_path_rather_than_forking(wayland):
|
|
spawned = invoke.Runner().launch(["definitely-not-a-program-here"], settle=5.0)
|
|
|
|
assert spawned.exited
|
|
assert spawned.pid == 0
|
|
assert "no executable" in spawned.stderr
|
|
|
|
|
|
def test_launch_passes_on_the_cli_s_own_refusal_when_there_is_no_compositor(tmp_path, monkeypatch):
|
|
"""`env_for_session` exits with the message; it is handed on verbatim."""
|
|
|
|
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(tmp_path / "empty" / "stream.sock"))
|
|
(tmp_path / "empty").mkdir()
|
|
spawned = invoke.Runner().launch(["true"], settle=1.0)
|
|
|
|
assert spawned.exited
|
|
assert spawned.pid == 0
|
|
assert "no wayland socket" in spawned.stderr
|
|
assert "is the compositor up?" in spawned.stderr
|
|
|
|
|
|
@pytest.fixture
|
|
def wayland(workdir, monkeypatch):
|
|
"""A runtime directory with something `env_for_session` accepts in it.
|
|
|
|
A real AF_UNIX socket, because that function checks `is_socket()` -- an
|
|
empty file would make it refuse for a reason these tests are not about.
|
|
The suite's `workdir` fixture and not `tmp_path`, because an AF_UNIX
|
|
address is capped near 108 bytes and pytest's own paths are longer than
|
|
that.
|
|
"""
|
|
|
|
import socket
|
|
|
|
listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
|
listener.bind(str(workdir / "wayland-0"))
|
|
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(workdir / "stream.sock"))
|
|
yield workdir
|
|
listener.close()
|
|
|
|
|
|
# ── artefact readers ───────────────────────────────────────────────────────
|
|
|
|
|
|
def test_a_png_is_sniffed_by_its_header_not_its_extension():
|
|
image = media.sniff(mcp_fake.png(width=13, height=7))
|
|
assert image is not None
|
|
assert (image.media_type, image.width, image.height) == ("image/png", 13, 7)
|
|
|
|
|
|
def test_a_jpeg_under_a_png_filename_is_still_a_jpeg():
|
|
"""The publisher serves `image/jpeg` on the deployment machine."""
|
|
|
|
image = media.sniff(mcp_fake.jpeg(width=6, height=3))
|
|
assert image is not None
|
|
assert (image.media_type, image.width, image.height) == ("image/jpeg", 6, 3)
|
|
|
|
|
|
def test_an_unrecognised_format_is_none_rather_than_a_guess():
|
|
assert media.sniff(b"GIF89a\x00\x00") is None
|
|
assert media.sniff(b"") is None
|
|
|
|
|
|
def test_the_measured_record_rate_is_read_off_the_cli_s_own_line():
|
|
found = media.recording("/tmp/out.mp4 (57 frames in 6.02s -> 9 fps)\n")
|
|
assert found is not None
|
|
assert (found.path, found.frames, found.seconds, found.fps) == ("/tmp/out.mp4", 57, 6.02, 9)
|
|
|
|
|
|
def test_a_record_line_in_an_unexpected_shape_is_not_half_parsed():
|
|
assert media.recording("/tmp/out.mp4\n") is None
|
|
assert media.recording("") is None
|
|
|
|
|
|
def test_temp_name_is_unique_per_process_and_under_a_named_directory():
|
|
first = invoke.temp_name("recording", ".mp4")
|
|
assert "hhstream-mcp" in first
|
|
assert first.endswith(".mp4")
|
|
assert str(os.getpid()) in first
|