Files
hyprland-headless-stream-pl…/tests/unit/test_mcp_tools.py
T
HermenixandClaude Opus 5 56493721f0 test(mcp): the resource routing, the toolsets, and the guest check for both
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
2026-10-11 11:50:12 +00:00

604 lines
22 KiB
Python

"""The tool table: the argv each tool builds, and what it makes of the answer.
The subject is the shim and nothing else. Every test here drives a tool
through :class:`hhstream_mcp.invoke.Runner` with a recording stand-in
(:class:`mcp_fake.FakeCli`) where the CLI goes, and asserts on the argv it was
handed -- which is the only thing this layer actually decides.
Nothing in this file imports the MCP SDK: the table is standard library by
design, so an argv bug is findable without a protocol stack. The SDK wiring is
``test_mcp_server.py``, and the real CLI entry point is exercised in
``test_mcp_invoke.py``.
"""
from __future__ import annotations
import json
import os
import signal
import mcp_fake
import pytest
from hhstreamd.protocol import ExitCode
from hhstream_mcp import invoke, tools
@pytest.fixture(autouse=True)
def _isolated(monkeypatch, tmp_path):
mcp_fake.isolate(monkeypatch, tmp_path)
@pytest.fixture
def call():
"""`call("session_touch", {"id": "s-1"})` -> (Result, [argv, ...])."""
def _call(name, arguments, **script):
fake = mcp_fake.FakeCli(**script)
result = tools.BY_NAME[name].invoke(invoke.Runner(fake), arguments)
return result, fake.calls
return _call
# ── the surface is all there ───────────────────────────────────────────────
#: Every tool `docs/CONTRACT-mcp.md` §3 freezes. Written out rather than derived
#: from the table, because a list derived from the thing it checks cannot
#: notice a missing entry.
EXPECTED = {
# frames -- capturing is an act at a moment, so these stay tools
"shot", "record", "run",
# lifecycle. The read-only verbs are resources; see MOVED_TO_RESOURCES.
"session_start", "session_touch", "session_kill", "session_gc",
"session_adopt", "session_container", "session_reconcile",
# pointer
"pointer_acquire", "pointer_move", "pointer_click", "pointer_scroll",
"pointer_down", "pointer_up", "pointer_release",
# keyboard
"keyboard_type", "keyboard_key", "keyboard_down", "keyboard_up",
}
#: Verbs that are resources now and must NOT come back as tools. Named, not
#: merely absent, so re-adding one is a failure rather than a silent widening
#: of the surface mcp-v2 narrowed.
MOVED_TO_RESOURCES = {
"status",
"session_list",
"session_status",
"session_logs",
"pointer_state",
}
def test_the_acting_verbs_are_tools_and_nothing_else_is():
assert set(tools.BY_NAME) == EXPECTED
assert len(tools.TOOLS) == 21
def test_the_read_only_verbs_are_not_tools():
"""They are `hhstream://…` resources: the host's context, not the model's acts."""
assert MOVED_TO_RESOURCES.isdisjoint(set(tools.BY_NAME))
# ...and the table that says where each one went covers exactly those five,
# so a caller holding a v1 name can be told rather than just refused.
assert set(tools.MOVED_TO_RESOURCES) == MOVED_TO_RESOURCES
for uri in tools.MOVED_TO_RESOURCES.values():
assert uri.startswith("hhstream://")
def test_session_container_stayed_a_tool_because_it_writes():
"""With an id the CLI runs `container.reconcile`, so it is not a read."""
assert "session_container" in tools.BY_NAME
assert not tools.BY_NAME["session_container"].read_only
assert "write" in tools.BY_NAME["session_container"].description
def test_the_table_is_ordered_and_has_no_duplicate_names():
names = [tool.name for tool in tools.TOOLS]
assert len(names) == len(set(names))
assert isinstance(tools.TOOLS, tuple)
def test_only_the_verbs_that_read_are_marked_read_only():
"""One left, now that the rest of the reads are resources."""
read_only = {tool.name for tool in tools.TOOLS if tool.read_only}
assert read_only == {"shot"}
# `record` writes a file, so it is not read-only either.
assert not tools.BY_NAME["record"].read_only
assert tools.BY_NAME["session_kill"].destructive
assert [t.name for t in tools.TOOLS if t.destructive] == ["session_kill"]
# ── the two rules an agent gets wrong ──────────────────────────────────────
#: The tools the CLI's own note names as NOT counting as activity. The others
#: it names are resources now, and `test_mcp_resources.py` holds those.
NON_ACTIVITY = {
"session_gc",
"session_container",
"session_reconcile",
}
GESTURES = {
"pointer_move",
"pointer_click",
"pointer_scroll",
"pointer_down",
"pointer_up",
"pointer_release",
"keyboard_type",
"keyboard_key",
"keyboard_down",
"keyboard_up",
}
#: The four families `--toolsets` selects from.
FAMILIES = ("frames", "sessions", "pointer", "keyboard")
def test_the_idle_clock_rule_is_on_every_tool_that_does_not_reset_it():
for name in NON_ACTIVITY | GESTURES | {"session_start", "session_touch", "pointer_acquire"}:
description = tools.BY_NAME[name].description
assert tools.ACTIVITY_NOTE in description, f"{name} does not carry the activity rule"
def test_the_idle_clock_rule_names_touch_as_the_only_mark_of_activity():
assert "`session_touch` is the ONLY thing" in tools.ACTIVITY_NOTE
# It has to name the *resources* now, because that is where reading moved:
# an agent told "listing does not count" cannot act on it if the thing it
# is listing with is no longer called `session_list`.
for named in ("hhstream://sessions", "session_gc", "pointer or keyboard tool"):
assert named in tools.ACTIVITY_NOTE
assert "does NOT count" in tools.ACTIVITY_NOTE
def test_the_cli_still_owns_the_rule_this_wording_restates():
"""A tripwire, not a duplication.
`tools.ACTIVITY_NOTE` and `tools.LEASE_NOTE` are the CLI's two epilogues
said in terms of tools. If the CLI's constants are renamed or stop saying
what they say, these notes have silently become this server's own opinion --
so the originals are asserted to still exist and still carry the rule.
"""
import hhstream_session
assert "ONLY" in hhstream_session.ACTIVITY_NOTE
assert "touch" in hhstream_session.ACTIVITY_NOTE
assert "no 'keyboard acquire'" in hhstream_session.KEYBOARD_LEASE_NOTE
def test_every_keyboard_tool_says_it_needs_the_pointer_lease():
for name in ("keyboard_type", "keyboard_key", "keyboard_down", "keyboard_up"):
description = tools.BY_NAME[name].description
assert tools.LEASE_NOTE in description, f"{name} does not carry the lease rule"
assert "POINTER lease" in tools.LEASE_NOTE
assert "exit 9" in tools.LEASE_NOTE
assert "`pointer_acquire`" in tools.LEASE_NOTE
assert "There is no keyboard lease" in tools.LEASE_NOTE
assert "only while it holds" in tools.LEASE_NOTE
def test_holding_a_non_modifier_is_warned_about_where_it_can_happen():
assert tools.HOLD_NOTE in tools.BY_NAME["keyboard_down"].description
assert "FLOODS THE WINDOW" in tools.HOLD_NOTE
assert "the APPLICATION does the repeating" in tools.HOLD_NOTE
def test_the_lease_is_a_required_argument_on_every_gesture_and_is_never_cached():
for name in GESTURES:
schema = tools.BY_NAME[name].schema
assert "lease" in schema["required"], f"{name} does not require a lease"
# ...and acquire is the one that hands it out, so it must not require one.
assert "lease" not in tools.BY_NAME["pointer_acquire"].schema.get("required", [])
# ── toolsets ───────────────────────────────────────────────────────────────
def test_every_tool_is_in_exactly_one_toolset():
"""Or `--toolsets` would be able to hide a tool nobody could ask for."""
assert tuple(tools.TOOLSETS) == FAMILIES
seen: list[str] = []
for family in FAMILIES:
seen.extend(tools.TOOLSETS[family])
assert len(seen) == len(set(seen)), "a tool is in two toolsets"
assert set(seen) == set(tools.BY_NAME), "a tool is in no toolset"
def test_no_toolset_named_is_every_tool():
"""The default, and what an unconfigured client gets."""
assert tools.selected(None) == tools.TOOLS
def test_a_selection_keeps_the_table_s_own_order():
"""So a listing does not reshuffle because of how the flag was written."""
chosen = [tool.name for tool in tools.selected(["keyboard", "frames"])]
assert chosen == ["shot", "record", "run", "keyboard_type", "keyboard_key",
"keyboard_down", "keyboard_up"]
def test_a_repeated_family_is_not_a_repeated_tool():
assert tools.selected(["frames", "frames"]) == tools.selected(["frames"])
def test_an_unknown_family_is_refused_and_names_the_known_ones():
"""Not skipped: a typo that served nothing would look like an empty server."""
with pytest.raises(tools.UnknownToolset) as caught:
tools.selected(["frames", "mouse"])
assert "'mouse'" in str(caught.value)
for family in FAMILIES:
assert family in str(caught.value)
def test_every_schema_refuses_an_argument_this_server_would_drop():
for tool in tools.TOOLS:
assert tool.schema["additionalProperties"] is False, tool.name
assert tool.schema["type"] == "object"
# ── the argv each tool builds ──────────────────────────────────────────────
def test_a_session_verb_is_run_with_json_and_its_id_after_a_separator(call):
_, calls = call("session_touch", {"id": "s-1"})
assert calls == [["session", "touch", "--json", "--", "s-1"]]
def test_omitted_arguments_become_no_flag_at_all(call):
"""A flag left off is the broker's own default; this layer must not supply one."""
_, calls = call("session_gc", {})
assert calls == [["session", "gc", "--json"]]
_, calls = call("session_gc", {"request_id": "r-1"})
assert calls == [["session", "gc", "--json", "--request-id=r-1"]]
_, calls = call("session_reconcile", {})
assert calls == [["session", "reconcile", "--json"]]
def test_start_passes_the_application_argv_after_one_separator(call):
_, calls = call(
"session_start",
{
"app": "chromium",
"argv": ["--new-window", "https://example.invalid"],
"idle_timeout": "5m",
"wait_ready": "30s",
"request_id": "req-7",
},
)
assert calls == [
[
"session", "start", "--json",
"--idle-timeout=5m",
"--wait-ready=30s",
"--request-id=req-7",
"--",
"chromium",
"--new-window",
"https://example.invalid",
]
]
def test_an_application_argument_that_looks_like_a_flag_is_not_eaten(call):
"""The `--` is what makes `--new-window` the application's and not the CLI's."""
_, calls = call("session_start", {"app": "foot", "argv": ["--help"]})
assert calls[0] == ["session", "start", "--json", "--", "foot", "--help"]
def test_an_ephemeral_home_is_a_switch_and_a_home_is_a_value(call):
_, calls = call("session_start", {"app": "foot", "ephemeral_home": True})
assert "--ephemeral-home" in calls[0]
_, calls = call("session_start", {"app": "foot", "home": "/tmp/h"})
assert "--home=/tmp/h" in calls[0]
def test_a_coordinate_pair_is_sent_in_the_cli_s_own_x_comma_y_form(call):
_, calls = call("pointer_move", {"id": "s-1", "lease": "L", "to": [0.25, 0.75]})
assert calls == [["session", "pointer", "move", "--json", "--lease=L", "--to=0.25,0.75", "--", "s-1"]]
def test_a_negative_delta_stays_one_token_so_argparse_cannot_read_it_as_a_flag(call):
_, calls = call("pointer_move", {"id": "s-1", "lease": "L", "by": [-0.1, 0.5]})
assert calls[0][5] == "--by=-0.1,0.5"
def test_a_coordinate_is_not_rounded_on_the_way_through(call):
"""A caller that computed a number deserves the broker's verdict on it."""
_, calls = call("pointer_move", {"id": "s-1", "lease": "L", "to": [1 / 3, 0.0]})
assert calls[0][5] == f"--to={1 / 3!r},0.0"
def test_a_negative_scroll_amount_stays_one_token(call):
_, calls = call("pointer_scroll", {"id": "s-1", "lease": "L", "amount": -3, "axis": "horizontal"})
assert calls[0] == [
"session", "pointer", "scroll", "--json",
"--lease=L", "--axis=horizontal", "--amount=-3.0", "--", "s-1",
]
def test_a_typed_string_is_one_positional_after_the_separator(call):
text = "--not-a-flag\nsecond line\twith a tab"
_, calls = call("keyboard_type", {"id": "s-1", "lease": "L", "text": text})
assert calls == [["session", "keyboard", "type", "--json", "--lease=L", "--", "s-1", text]]
def test_a_keysym_name_is_passed_through_untouched(call):
_, calls = call("keyboard_key", {"id": "s-1", "lease": "L", "name": "BackSpace"})
assert calls[0][-1] == "BackSpace"
def test_adopt_sends_the_pid_as_a_flag_because_the_cli_requires_it(call):
_, calls = call("session_adopt", {"pid": 4242, "app": "chromium"})
assert calls == [["session", "adopt", "--json", "--pid=4242", "--app=chromium"]]
def test_container_with_no_id_lists_and_with_an_id_reconciles(call):
_, calls = call("session_container", {})
assert calls == [["session", "container", "--json"]]
_, calls = call("session_container", {"id": "s-1"})
assert calls == [["session", "container", "--json", "--", "s-1"]]
# ── what each tool makes of the answer ─────────────────────────────────────
def test_a_successful_session_verb_passes_the_protocol_object_through(call):
reply = {"ok": True, "pruned": 2, "sessions": [{"id": "s-1"}]}
result, _ = call("session_gc", {}, stdout=json.dumps(reply, indent=2))
assert not result.is_error
assert result.data == reply
# The text is the CLI's own stdout: a shim that re-rendered it would be
# inventing a second format for the same facts.
assert json.loads(result.text) == reply
def test_acquire_puts_the_lease_id_where_the_next_call_will_look(call):
reply = {"ok": True, "id": "s-1", "lease_id": "lease-abc", "bookmark": {"output": "hh-s-1"}}
result, _ = call("pointer_acquire", {"id": "s-1"}, stdout=json.dumps(reply, indent=2))
assert result.data == reply
assert result.text.startswith("lease_id: lease-abc")
assert "pointer_release" in result.text
def test_start_puts_the_new_session_id_first_and_names_the_idle_clock(call):
reply = {"ok": True, "id": "s-9", "state": "running"}
result, _ = call("session_start", {"app": "foot"}, stdout=json.dumps(reply, indent=2))
assert result.text.startswith("session id: s-9")
assert "session_touch" in result.text
def test_a_refusal_is_an_error_and_never_a_success(call):
reply = {
"ok": False,
"error": "no_lease",
"reason": "no pointer lease for s-1 on this socket",
"hint": "run 'pointer acquire s-1' first",
}
result, _ = call(
"pointer_click",
{"id": "s-1", "lease": "stale"},
stderr=json.dumps(reply, indent=2),
exit_code=int(ExitCode.NO_LEASE),
)
assert result.is_error
assert result.data["ok"] is False
assert result.data["exit_code"] == int(ExitCode.NO_LEASE)
# The remedy first, then the broker's own words: an agent needs to know what
# to do before it needs to know what was said.
assert result.text.startswith("exit 9 (NO_LEASE)")
assert "pointer_acquire" in result.text
assert "error: no_lease" in result.text
assert "no pointer lease for s-1" in result.text
def test_the_contended_lease_case_names_the_holder_and_does_not_say_acquire(call):
reply = {"ok": False, "error": "pointer_busy", "reason": "held by s-other"}
result, _ = call(
"pointer_acquire",
{"id": "s-1"},
stderr=json.dumps(reply, indent=2),
exit_code=int(ExitCode.BUSY),
)
assert result.is_error
assert result.text.startswith("exit 8 (BUSY)")
assert "hhstream://pointer" in result.text
assert "s-other" in result.text
def test_a_usage_refusal_from_argparse_itself_is_still_an_error(call):
"""Exit 2 with no JSON anywhere -- argparse wrote prose to stderr."""
result, _ = call(
"pointer_click",
{"id": "s-1", "lease": "L", "button": "left"},
stderr="usage: hhstream session pointer click ...\nerror: argument --button: invalid choice\n",
exit_code=int(ExitCode.USAGE),
)
assert result.is_error
assert result.data["exit_code"] == int(ExitCode.USAGE)
assert "invalid choice" in result.text
def test_a_broker_that_is_down_is_reported_as_the_operator_s_problem(call):
result, _ = call(
"session_gc",
{},
stderr="error: cannot reach the hhstream session daemon at /run/hhstream/control.sock\n",
exit_code=int(ExitCode.DAEMON_UNREACHABLE),
)
assert result.is_error
assert "HHSTREAM_SOCKET" in result.text
assert "frame tools" in result.text
# ── shot and record ────────────────────────────────────────────────────────
def test_shot_captures_to_a_file_and_returns_the_bytes_with_the_geometry(call):
frame = mcp_fake.png(width=320, height=180)
result, calls = call("shot", {}, write_png=frame, stdout="/tmp/ignored.png\n")
assert len(calls) == 1
verb, out = calls[0][0], calls[0][1]
assert verb == "shot"
assert out.startswith("--out=")
# The temporary directory is gone, so the file cannot be read twice: the
# bytes are in the reply or they are nowhere.
assert result.image == frame
assert result.media_type == "image/png"
assert "320x180 image/png" in result.text
assert result.data["width"] == 320
def test_shot_of_one_output_names_it_in_the_argv_and_in_the_reply(call):
result, calls = call("shot", {"output": "hh-s-1"}, write_png=mcp_fake.png())
assert "--output=hh-s-1" in calls[0]
assert "output 'hh-s-1'" in result.text
assert result.data["output"] == "hh-s-1"
def test_shot_tells_the_truth_about_a_format_it_cannot_read(call):
result, _ = call("shot", {}, write_png=b"GIF89a-not-an-image")
assert not result.is_error
assert result.image is None
assert "does not recognise" in result.text
def test_shot_does_not_claim_an_image_when_the_cli_wrote_no_file(call):
"""Exit 0 and no artefact is still a failure; the alternative is a lie."""
result, _ = call("shot", {}, stdout="/tmp/somewhere.png\n")
assert result.is_error
assert result.data["error"] == "no_artifact"
def test_shot_passes_a_refusal_through_without_reading_a_file(call):
result, _ = call(
"shot",
{"output": "hh-gone"},
stderr="hhstream: could not capture output 'hh-gone': unknown output\n",
exit_code=1,
)
assert result.is_error
assert result.image is None
assert "unknown output" in result.text
def test_record_returns_the_path_and_the_measured_rate_not_the_video(call):
destination = "/tmp/hhstream-mcp/clip.mp4"
result, calls = call(
"record",
{"seconds": 3, "out": destination},
stdout=f"{destination} (28 frames in 3.01s -> 9 fps)\n",
)
assert calls[0] == ["record", f"--out={destination}", "--seconds=3"]
assert result.image is None
assert result.data == {
"ok": True,
"path": destination,
"frames": 28,
"seconds": 3.01,
"fps": 9,
}
assert "measured 9 fps" in result.text
def test_record_without_a_destination_generates_one_and_names_it(call):
result, calls = call("record", {}, stdout="/x (1 frames in 1.00s -> 1 fps)\n")
flag = next(a for a in calls[0] if a.startswith("--out="))
assert "hhstream-mcp" in flag
assert flag.endswith(".mp4")
assert result.data["ok"] is True
def test_record_of_one_output_passes_the_rate_target_through(call):
_, calls = call(
"record",
{"seconds": 2, "output": "hh-s-1", "fps": 4, "keep": True, "work_dir": "/tmp/w"},
stdout="/x (8 frames in 2.00s -> 4 fps)\n",
)
# The generated --out is asserted by the test above; what matters here is
# the order and form of everything after it.
assert calls[0][0] == "record"
assert calls[0][2:] == [
"--seconds=2",
"--output=hh-s-1",
"--fps=4",
"--work-dir=/tmp/w",
"--keep",
]
# ── run ────────────────────────────────────────────────────────────────────
def test_run_reports_the_application_s_pid_and_that_it_is_unmanaged(wayland):
result = tools.BY_NAME["run"].invoke(
invoke.Runner(), {"argv": ["sleep", "30"], "settle_s": 0.3}
)
try:
assert not result.is_error
assert result.data["managed"] is False
assert result.data["pid"] > 0
assert result.data["argv"] == ["sleep", "30"]
# The tool's own words have to point at the managed alternative, or an
# agent reaches for `run` because it is the shorter name.
assert "session_start" in result.text
assert "UNMANAGED" in result.text
finally:
import contextlib
with contextlib.suppress(ProcessLookupError):
os.kill(result.data["pid"], signal.SIGTERM)
def test_run_reports_a_launch_that_failed_immediately_as_an_error(wayland):
result = tools.BY_NAME["run"].invoke(
invoke.Runner(),
{"argv": ["sh", "-c", "echo 'cannot open display' >&2; exit 1"], "settle_s": 5.0},
)
assert result.is_error
assert result.data["error"] == "run_exited"
assert "cannot open display" in result.text
assert "nothing is on" in result.text
@pytest.fixture
def wayland(workdir, monkeypatch):
"""A runtime directory the CLI's `env_for_session` accepts.
A real AF_UNIX socket, because that function checks `is_socket()`, and the
suite's short-pathed `workdir` because an AF_UNIX address is capped near
108 bytes.
"""
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()