test(mcp): the argv each tool builds, the mapping, and the server in a guest

101 unit tests under `tests/unit/` and one new VM check.

The unit suite's subject is the only thing this layer decides: the argv list.
`mcp_fake.FakeCli` is a recording stand-in put where the CLI goes, so every
test can assert on the exact argv a tool handed over -- the `=` form of each
flag, the `--` before each positional, the omission of a flag the caller did
not give. Three tests drive the **real** entry point against a control socket
that does not exist, which proves the dispatch, the capture and the exit-code
mapping against the CLI's actual parser with no daemon standing up: argparse's
exit 2 for a bad `--button`, exit 5 for the unreachable broker, exit 9 for a
gesture with no lease.

`test_mcp_server.py` imports the MCP SDK unconditionally and runs the server
in process over the SDK's memory transport. It is not allowed to skip: the tool
table is stdlib and tested without the SDK, but whether every schema validates
and every name is one the specification allows is a question only the SDK can
answer, and a file that skipped when it was absent would be green in exactly
the build where that mattered. `checks/unit.nix` therefore puts `mcp` in the
test environment and `hhstream-mcp` on PYTHONPATH beside `hhstream`.

`checks/vm-mcp.nix` boots the session machine with `mcp.enable = true` and
drives the real binary over a real pipe with `checks/lib/mcp_client.py` -- raw
JSON-RPC, deliberately not the SDK's client, for the reason
`tests/assert_stream.py` is a second implementation of the frame contract. It
asserts the handshake, the 26-tool listing with its annotations and its two
rules, a call that reaches the live broker, `shot` as image content, the lease
granted/used/returned against the real driver, and exits 9 and 3 arriving as
tool errors.

The geometry assertion in that check is one it got wrong first time and now
records: the published frame is 2560x720 on a guest configured for 1280x720,
because the publisher's default capture takes the whole compositor layout and a
session's container is a second output beside the main one. `shot` with the
container's own `output` is the one that is exactly 1280x720.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-11 06:32:55 +00:00
1 parent 549c73e8ae
commit fea55eecde
8 files changed
+1984 -3

No files matched your search

+389
View File
@@ -0,0 +1,389 @@
"""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 "pointer_state" 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