From fea55eecdeaaab4c30817c2a2e0ef23c68b1aa24 Mon Sep 17 00:00:00 2001 From: Hermenix Date: Sun, 11 Oct 2026 06:32:55 +0000 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE --- checks/default.nix | 9 +- checks/lib/mcp_client.py | 175 +++++++++++ checks/unit.nix | 22 +- checks/vm-mcp.nix | 375 +++++++++++++++++++++++ tests/unit/mcp_fake.py | 152 ++++++++++ tests/unit/test_mcp_invoke.py | 389 ++++++++++++++++++++++++ tests/unit/test_mcp_server.py | 312 +++++++++++++++++++ tests/unit/test_mcp_tools.py | 553 ++++++++++++++++++++++++++++++++++ 8 files changed, 1984 insertions(+), 3 deletions(-) create mode 100755 checks/lib/mcp_client.py create mode 100644 checks/vm-mcp.nix create mode 100644 tests/unit/mcp_fake.py create mode 100644 tests/unit/test_mcp_invoke.py create mode 100644 tests/unit/test_mcp_server.py create mode 100644 tests/unit/test_mcp_tools.py diff --git a/checks/default.nix b/checks/default.nix index a87259c..ae71224 100644 --- a/checks/default.nix +++ b/checks/default.nix @@ -1,6 +1,7 @@ # The flake's `checks` output. One file per check; this is only the wiring. # # unit -- pytest over tests/, against the nix/package.nix build +# vm-mcp -- the MCP server over stdio, against a live broker # vm-basic -- nixosTest with a fake capture backend: module + wire contract # vm-hyprland -- nixosTest with the real compositor and grim # vm-sessions -- nixosTest with the real compositor and the session broker @@ -32,6 +33,7 @@ }: let hhstream = self.packages.${system}.hhstream; + hhstream-mcp = self.packages.${system}.hhstream-mcp; hhsModule = self.nixosModules.default; testTools = pkgs.callPackage ./lib/test-tools.nix { }; # The session checks take the same arguments; naming them once keeps a new @@ -42,7 +44,7 @@ let }; in { - unit = pkgs.callPackage ./unit.nix { inherit hhstream; }; + unit = pkgs.callPackage ./unit.nix { inherit hhstream hhstream-mcp; }; vm-basic = pkgs.callPackage ./vm-basic.nix { inherit hhstream hhsModule testTools; @@ -73,4 +75,9 @@ in vm-stream-firewall = pkgs.callPackage ./vm-stream-firewall.nix { inherit hhstream hhsModule testTools; }; + + # The session machine again, plus `mcp.enable`, driven over stdio by a + # JSON-RPC client the check writes itself. `sessionArgs` plus the one package + # the others have no reason to carry. + vm-mcp = pkgs.callPackage ./vm-mcp.nix (sessionArgs // { inherit hhstream-mcp; }); } diff --git a/checks/lib/mcp_client.py b/checks/lib/mcp_client.py new file mode 100755 index 0000000..1fcf56f --- /dev/null +++ b/checks/lib/mcp_client.py @@ -0,0 +1,175 @@ +#!/usr/bin/env python3 +"""``hhs-mcp-call`` -- drive an MCP server over stdio from a shell. + +What `checks/vm-mcp.nix` uses to talk to `hhstream-mcp` in the guest, and +deliberately **not** the MCP SDK's own client: the SDK on both ends would agree +with itself about a framing neither side had to get right. This is raw +JSON-RPC, newline-delimited, written against the specification -- the same +choice, and for the same reason, as `tests/assert_stream.py` being a second +implementation of the frame contract. + +One server process per invocation, which means every call re-does the +`initialize` handshake. That is a feature here: the handshake is one of the +things under test, and a client that did it once would prove it once. + + hhs-mcp-call --initialize the handshake's own result + hhs-mcp-call --list every tool, as JSON + hhs-mcp-call session_list one call, no arguments + hhs-mcp-call session_touch '{"id": "s-1"}' one call, arguments as JSON + +Always exits 0 when the server answered, whatever the answer was: a refusal is +a result the test asserts on, not this program's failure. Exit 2 is "the +server did not answer" -- it died, it timed out, or it sent something that is +not JSON-RPC -- which is the one outcome no assertion should be able to mistake +for a reply. +""" + +from __future__ import annotations + +import argparse +import json +import signal +import subprocess +import sys +from typing import Any + +#: The protocol version this client speaks. Named rather than negotiated: a +#: server that answers a different one is a thing the test should see. +PROTOCOL_VERSION = "2025-06-18" + + +def fail(message: str) -> None: + print(f"hhs-mcp-call: {message}", file=sys.stderr) + raise SystemExit(2) + + +class Server: + """One ``hhstream-mcp`` process, spoken to over its stdin and stdout.""" + + def __init__(self, command: list[str], timeout: int) -> None: + self.timeout = timeout + # stderr is left alone on purpose: the server logs there, and in a + # nixosTest that ends up in the build log beside the assertion that + # failed, which is where it is wanted. + self.process = subprocess.Popen( + command, + stdin=subprocess.PIPE, + stdout=subprocess.PIPE, + text=True, + bufsize=1, + ) + self.next_id = 0 + + def send(self, message: dict[str, Any]) -> None: + assert self.process.stdin is not None + self.process.stdin.write(json.dumps(message) + "\n") + self.process.stdin.flush() + + def read(self) -> dict[str, Any]: + assert self.process.stdout is not None + # An alarm rather than a poll loop: a server that never answers must + # fail the check, not hang the test driver until its global timeout. + signal.alarm(self.timeout) + try: + line = self.process.stdout.readline() + except KeyboardInterrupt: # pragma: no cover -- the alarm handler + fail(f"no answer within {self.timeout}s") + raise + finally: + signal.alarm(0) + if not line: + fail(f"the server closed its stream (exit {self.process.poll()})") + try: + return json.loads(line) + except json.JSONDecodeError: + # The failure a stray `print` on stdout produces, named as such: + # the tools run the CLI in process, and this is what it looks like + # when something it printed reached the transport. + fail(f"not JSON-RPC on the server's stdout: {line!r}") + raise AssertionError("unreachable") + + def request(self, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]: + self.next_id += 1 + wanted = self.next_id + self.send( + {"jsonrpc": "2.0", "id": wanted, "method": method, "params": params or {}} + ) + answer = self.read() + if answer.get("id") != wanted: + fail(f"answer for id {answer.get('id')!r}, expected {wanted}") + if "error" in answer: + fail(f"{method} was refused at the protocol level: {answer['error']}") + return answer["result"] + + def initialize(self) -> dict[str, Any]: + result = self.request( + "initialize", + { + "protocolVersion": PROTOCOL_VERSION, + "capabilities": {}, + "clientInfo": {"name": "hhs-mcp-call", "version": "0"}, + }, + ) + self.send({"jsonrpc": "2.0", "method": "notifications/initialized"}) + return result + + def close(self) -> int: + assert self.process.stdin is not None + self.process.stdin.close() + try: + return self.process.wait(timeout=self.timeout) + except subprocess.TimeoutExpired: # pragma: no cover + self.process.kill() + return -1 + + +def _alarm(signum, frame): # pragma: no cover -- raises into read() + raise KeyboardInterrupt + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(prog="hhs-mcp-call", description=__doc__) + parser.add_argument( + "--server", + default="hhstream-mcp", + help="the MCP server to spawn (default: %(default)s, from PATH)", + ) + parser.add_argument("--timeout", type=int, default=120, metavar="SECONDS") + parser.add_argument("--initialize", action="store_true", help="print the handshake result") + parser.add_argument("--list", action="store_true", help="print the tool listing") + parser.add_argument("tool", nargs="?", help="the tool to call") + parser.add_argument("arguments", nargs="?", default="{}", help="its arguments, as JSON") + args = parser.parse_args(argv) + + signal.signal(signal.SIGALRM, _alarm) + + try: + arguments = json.loads(args.arguments) + except json.JSONDecodeError as exc: + fail(f"arguments are not JSON: {exc}") + return 2 + if not isinstance(arguments, dict): + fail("arguments must be a JSON object") + + server = Server([args.server], args.timeout) + try: + handshake = server.initialize() + if args.initialize: + print(json.dumps(handshake, indent=2, sort_keys=True)) + return 0 + if args.list: + print(json.dumps(server.request("tools/list"), indent=2, sort_keys=True)) + return 0 + if not args.tool: + fail("name a tool, or pass --list or --initialize") + result = server.request( + "tools/call", {"name": args.tool, "arguments": arguments} + ) + print(json.dumps(result, indent=2, sort_keys=True)) + return 0 + finally: + server.close() + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/checks/unit.nix b/checks/unit.nix index 4a29301..0d96c9d 100644 --- a/checks/unit.nix +++ b/checks/unit.nix @@ -16,6 +16,7 @@ runCommand, python3, hhstream, + hhstream-mcp, }: let # `xkbcommon` beside `pywayland`, and it is not optional: `tests/pointer/ @@ -24,7 +25,19 @@ let # needs a level-three mask rather than Shift. A suite that could skip those # would let the unmappable-character path rot, which is the path that decides # whether a bad string types a prefix. - pytestEnv = python3.withPackages (ps: [ ps.pytest ps.pywayland ps.xkbcommon ]); + # + # `mcp` beside them, for `tests/unit/test_mcp_server.py`. That file imports + # the SDK on purpose and is not allowed to skip: the tool table itself is + # stdlib-only and tested without it, but the step that turns the table into + # `mcp.types.Tool` objects is where a malformed schema or a name the spec + # refuses would show up, and a file that skipped when the SDK was absent + # would be green in exactly the build where that mattered. + pytestEnv = python3.withPackages (ps: [ + ps.pytest + ps.pywayland + ps.xkbcommon + ps.mcp + ]); # Only the suite itself, so an editor's droppings or a local .pytest_cache # cannot change the derivation's hash. @@ -61,11 +74,16 @@ runCommand "hhstream-unit" # point PYTHONPATH at what nix/package.nix installed. Importing it here rather # than letting pytest do it makes a packaging problem distinguishable from a # test failure. - export PYTHONPATH=${hhstream}/${python3.sitePackages} + export PYTHONPATH=${hhstream}/${python3.sitePackages}:${hhstream-mcp}/${python3.sitePackages} export PYTHONDONTWRITEBYTECODE=1 export HOME=$PWD python3 -c 'import hhstream; print("testing hhstream", hhstream.__version__, "from", hhstream.__file__)' python3 -c 'import hhstreamd.ipc, hhstream_pointer; print("broker ipc client + pointer driver import")' + # The second distribution, on the path beside the first. `tests/unit`'s + # conftest adds `../src` to sys.path, which does not exist in this sandbox -- + # so here, as for `hhstream`, the import comes from what Nix installed, and a + # packaging mistake is distinguishable from a test failure. + python3 -c 'import hhstream_mcp.tools as t; print("mcp tool table:", len(t.TOOLS), "tools")' set +e pytest suite \ diff --git a/checks/vm-mcp.nix b/checks/vm-mcp.nix new file mode 100644 index 0000000..818ee4d --- /dev/null +++ b/checks/vm-mcp.nix @@ -0,0 +1,375 @@ +# checks..vm-mcp -- the MCP server over stdio, in a guest, against a +# live broker and a real compositor. +# +# The same machine the other session checks use (`lib/session-machine.nix`), +# plus `services.hyprland-headless-stream.mcp.enable = true` -- which is also +# the first thing asserted, because "installing it" is the whole of that +# option. Then `hhs-mcp-call` (`lib/mcp_client.py`) spawns `hhstream-mcp` as the +# operator account and talks raw JSON-RPC to it: initialize, tools/list, +# tools/call. +# +# WHAT THIS PROVES, AND WHAT IT DOES NOT. +# +# It proves the *surface*: the handshake completes over a real pipe, all +# twenty-six tools are listed, a tool call reaches the broker and comes back +# with the broker's own protocol object, an image arrives as image content with +# the geometry the module configured, and a refusal arrives as a tool error +# carrying the frozen exit code rather than as a success. +# +# It does not prove the compositor behaviour the other checks own, and it must +# not be read as doing so. `vm-pointer` is where a click is shown to land in the +# window it was aimed at; `vm-keyboard` is where a typed symbol is shown to be +# decoded by a client from the keymap the driver uploaded. Here the victim is +# `foot`, which ignores `$HHSTREAM_APP_ID` and so matches no container rule +# (README.dev.md, known gap 4) -- so what the pointer and keyboard subtests +# below assert is that the lease was granted and the driver accepted the +# injection, which is the part the MCP layer is responsible for. +# +# The client is not the MCP SDK's, deliberately: the SDK on both ends would +# agree with itself about a framing neither side had to get right. Same choice +# as `tests/assert_stream.py` being a second implementation of the frame +# contract, and for the same reason. +# +# Habits copied from the other session checks: every wait is bounded, each +# subtest asserts once, and a failure dumps the compositor's diagnostics and +# the broker's journal before it propagates. +{ + testers, + hhstream, + hhstream-mcp, + hhsModule, + testTools, + hyprland, + foot, + jq, + grim, + procps, + coreutils, + dejavu_fonts, + width ? 1280, + height ? 720, + sessionUser ? "hermes", +}: +testers.runNixOSTest ( + { pkgs, ... }: + let + tools = pkgs.callPackage ./lib/session-tools.nix { inherit hhstream; }; + guest = import ./lib/session-machine.nix { + inherit + hhsModule + hhstream + hyprland + testTools + foot + jq + procps + grim + coreutils + dejavu_fonts + ; + sessionTools = tools; + }; + prelude = import ./lib/session-prelude.nix { + inherit hhstream coreutils sessionUser; + }; + + # The client, with a plain python3: it speaks JSON-RPC over a pipe and + # imports nothing but the standard library, which is what makes it a second + # implementation rather than the SDK talking to itself. + client = pkgs.runCommandLocal "hhs-mcp-call" { } '' + install -Dm755 ${./lib/mcp_client.py} $out/bin/hhs-mcp-call + sed -i '1s|.*|#!${pkgs.python3}/bin/python3|' $out/bin/hhs-mcp-call + $out/bin/hhs-mcp-call --help > /dev/null + # It must refuse to invent a request rather than printing nothing: a + # client that exits 0 having done nothing would make every subtest below + # vacuous. + if $out/bin/hhs-mcp-call --server ${coreutils}/bin/true; then + echo "hhs-mcp-call succeeded against a server that says nothing" >&2 + exit 1 + fi + ''; + in + { + name = "hhstream-vm-mcp"; + + globalTimeout = 1800; + + nodes.machine = { + imports = [ + (guest { + inherit width height sessionUser; + pointer = true; + apps.foot = { + exec = "${foot}/bin/foot"; + # The broker refuses unlisted arguments and this check passes none: + # `foot` with no argv opens a window, which is all the victim has + # to do. + argsAllow = [ ]; + }; + }) + ]; + + # The option under test. Installing the package IS the option, so the + # first subtest asserts the binary is on PATH and nothing else had to + # happen. + services.hyprland-headless-stream.mcp = { + enable = true; + package = hhstream-mcp; + }; + + environment.systemPackages = [ client ]; + }; + + testScript = + prelude + + '' + import base64 + import shlex + + MCP = "${client}/bin/hhs-mcp-call" + WIDTH = ${toString width} + HEIGHT = ${toString height} + + + def mcp(argv, timeout=180): + """`hhs-mcp-call …` as USER, parsed. Fails loudly if it printed no JSON.""" + + out = machine.succeed(as_user(f"{MCP} {argv}"), timeout=timeout) + try: + return json.loads(out) + except json.JSONDecodeError: + raise AssertionError(f"not JSON from `hhs-mcp-call {argv}`: {out!r}") + + + def call(tool, arguments=None, timeout=180): + """One tools/call. Returns the CallToolResult as a dict.""" + + payload = json.dumps(arguments or {}) + return mcp(f"{tool} {shlex.quote(payload)}", timeout=timeout) + + + def text_of(result): + """The text part of a CallToolResult, which is where the CLI's own + output and (on a refusal) the remedy live.""" + + for block in result.get("content") or []: + if block.get("type") == "text": + return block["text"] + raise AssertionError(f"no text content in {result!r}") + + + def succeeded(tool, arguments=None, timeout=180): + """A call that must not be an error, with the reason printed if it is.""" + + result = call(tool, arguments, timeout=timeout) + if result.get("isError"): + print(f"----- {tool} returned an error -----") + print(text_of(result)) + assert not result.get("isError"), f"{tool} failed: {text_of(result)}" + return result + + + start_all() + bring_up("the compositor and broker") + + with subtest("the as-user wrapper propagates exit status"): + # Every assertion below reads machine.succeed through it, so a + # wrapper that swallowed the status would make them all vacuous. + machine.succeed(as_user(TRUE), timeout=120) + machine.fail(as_user(FALSE), timeout=120) + + with subtest("mcp.enable put the server on the system PATH"): + # The whole of the module option: no unit, no socket, no state dir. + path = machine.succeed(as_user("/run/current-system/sw/bin/sh -c 'command -v hhstream-mcp'")).strip() + print(f"hhstream-mcp resolves to {path}") + assert path.startswith("/run/current-system/sw/bin"), path + machine.fail("systemctl is-active hhstream-mcp.service") + + with subtest("the stdio handshake completes and names this server"): + try: + handshake = mcp("--initialize") + print(json.dumps(handshake, indent=2)[:600]) + assert handshake["serverInfo"]["name"] == "hhstream", handshake + assert handshake["capabilities"].get("tools") is not None, handshake + # The two rules, in the instructions a client is handed once. + instructions = handshake["instructions"] + assert "`session_touch` is the ONLY" in instructions + assert "POINTER lease" in instructions + except Exception: + dump("the mcp handshake") + raise + + with subtest("tools/list carries every verb, with its annotations"): + listed = mcp("--list")["tools"] + names = sorted(tool["name"] for tool in listed) + print(f"{len(names)} tools: {', '.join(names)}") + assert len(names) == 26, names + for expected in ( + "status", "shot", "record", "run", + "session_start", "session_touch", "session_kill", + "pointer_acquire", "pointer_click", "keyboard_type", + ): + assert expected in names, f"{expected} is missing from the listing" + by_name = {tool["name"]: tool for tool in listed} + assert by_name["session_list"]["annotations"]["readOnlyHint"] is True + assert by_name["session_kill"]["annotations"]["destructiveHint"] is True + # The rule has to be on the tool, not only in the instructions. + assert "session_touch" in by_name["session_list"]["description"] + assert "POINTER lease" in by_name["keyboard_type"]["description"] + + with subtest("a read-only tool reaches the broker and returns its object"): + try: + result = succeeded("session_list") + assert result["structuredContent"]["ok"] is True, result + # The text part is the CLI's own `--json` output, unmodified. + assert json.loads(text_of(result)) == result["structuredContent"] + except Exception: + dump("session_list over mcp") + raise + + with subtest("a session started over mcp is the broker's own session"): + try: + started = succeeded("session_start", {"app": "foot"}, timeout=300) + session_id = started["structuredContent"]["id"] + print(f"started {session_id}") + assert text_of(started).startswith(f"session id: {session_id}") + # The broker is the authority on whether that happened, so it + # is asked directly rather than through the server under test. + listing = cli_json("list --json") + assert session_id in [s["id"] for s in listing["sessions"]], listing + except Exception: + dump("session_start over mcp") + raise + + with subtest("touch is the verb that moves the idle deadline"): + try: + before = succeeded("session_status", {"id": session_id}) + before_expiry = before["structuredContent"]["session"]["expires_in_s"] + # `status` must NOT have moved it; `touch` must. + after_status = succeeded("session_status", {"id": session_id}) + assert ( + after_status["structuredContent"]["session"]["expires_in_s"] + <= before_expiry + ), "reading status reset the idle clock" + touched = succeeded("session_touch", {"id": session_id}) + assert ( + touched["structuredContent"]["session"]["expires_in_s"] + >= after_status["structuredContent"]["session"]["expires_in_s"] + ), touched + except Exception: + dump("touch over mcp", session_id) + raise + + with subtest("shot returns image content, sized as the publisher serves it"): + # MEASURED, and not what this check first assumed: the frame is + # 2560x720 on a guest configured for 1280x720. The publisher's + # default capture is `grim -t png -` with no `-o`, which takes the + # whole compositor layout -- and with containers on (the module's + # default) a session's own output sits beside the main one, so one + # session doubles the width. The geometry the module configures is + # the geometry of an *output*, which is what the next subtest + # captures by name. + try: + shot = succeeded("shot", timeout=300) + kinds = [block["type"] for block in shot["content"]] + assert kinds == ["text", "image"], kinds + image = shot["content"][1] + frame = base64.b64decode(image["data"]) + print(f"{image['mimeType']}, {len(frame)} bytes: {text_of(shot)}") + assert image["mimeType"] in ("image/png", "image/jpeg") + # The media type is read off the bytes, never off the extension + # this server asked the CLI for -- so the two must agree. + magic = {"image/png": b"\x89PNG", "image/jpeg": b"\xff\xd8\xff"} + assert frame.startswith(magic[image["mimeType"]]), frame[:8] + reported = shot["structuredContent"] + assert reported["height"] == HEIGHT, reported + assert reported["width"] >= WIDTH, reported + assert reported["bytes"] == len(frame), reported + assert len(frame) > 1024, "a frame that small is not a desktop" + except Exception: + dump("shot over mcp", session_id) + raise + + with subtest("shot of the session's own container is one output, exactly"): + # Which is also the only subtest that reads `session_container`, and + # the one that joins the two tools an agent uses together: the + # output name that verb reports is what `shot` takes as `output`. + try: + container = succeeded("session_container", {"id": session_id}) + output = container["structuredContent"]["container"]["output"] + print(f"container output: {output}") + assert output == f"hh-{session_id}", container + + framed = succeeded("shot", {"output": output}, timeout=300) + reported = framed["structuredContent"] + print(text_of(framed)) + assert reported["output"] == output, reported + assert (reported["width"], reported["height"]) == (WIDTH, HEIGHT), reported + assert framed["content"][1]["type"] == "image" + except Exception: + dump("shot --output over mcp", session_id) + raise + + with subtest("the pointer lease is granted, used and given back"): + try: + acquired = succeeded("pointer_acquire", {"id": session_id}) + lease = acquired["structuredContent"]["lease_id"] + print(f"lease {lease}: {text_of(acquired).splitlines()[0]}") + assert text_of(acquired).startswith(f"lease_id: {lease}") + + # Every gesture takes the lease as an explicit argument: the + # server caches nothing, which is what makes a transcript of + # tool calls readable. + succeeded("pointer_move", {"id": session_id, "lease": lease, "to": [0.5, 0.5]}) + succeeded("pointer_click", {"id": session_id, "lease": lease}) + succeeded("keyboard_type", {"id": session_id, "lease": lease, "text": "hello"}) + typed = succeeded( + "keyboard_key", {"id": session_id, "lease": lease, "name": "Return"} + ) + assert typed["structuredContent"]["ok"] is True, typed + + released = succeeded("pointer_release", {"id": session_id, "lease": lease}) + assert released["structuredContent"]["ok"] is True, released + # And the broker agrees that nobody holds it now. + assert cli_json("pointer state --json")["holder"] is None + except Exception: + dump("the pointer lease over mcp", session_id) + raise + + with subtest("a gesture after the release is exit 9 and says to acquire"): + # The frozen NO_LEASE code, arriving as a tool error an agent can + # act on rather than as a success with a sad message in it. + refused = call("pointer_click", {"id": session_id, "lease": lease}) + assert refused["isError"] is True, refused + assert refused["structuredContent"]["exit_code"] == 9, refused + said = text_of(refused) + print(said.splitlines()[0]) + assert "exit 9 (NO_LEASE)" in said + assert "pointer_acquire" in said + + with subtest("an unknown session is exit 3, not a success"): + refused = call("session_status", {"id": "no-such-session"}) + assert refused["isError"] is True, refused + assert refused["structuredContent"]["exit_code"] == 3, refused + assert "session_list" in text_of(refused) + + with subtest("an argument the schema refuses never reaches the broker"): + # No `lease`, so the server's own schema refuses before an argv list + # exists. The CLI is not run at all, which is the point. + refused = call("keyboard_type", {"id": session_id, "text": "x"}) + assert refused["isError"] is True, refused + assert "lease" in text_of(refused), refused + + with subtest("kill over mcp ends the session the broker was tracking"): + try: + killed = succeeded("session_kill", {"id": session_id}, timeout=300) + print(text_of(killed)) + assert killed["structuredContent"]["ok"] is True, killed + live = [s["id"] for s in cli_json("list --json")["sessions"]] + assert session_id not in live, live + except Exception: + dump("session_kill over mcp", session_id) + raise + ''; + } +) diff --git a/tests/unit/mcp_fake.py b/tests/unit/mcp_fake.py new file mode 100644 index 0000000..9e48efd --- /dev/null +++ b/tests/unit/mcp_fake.py @@ -0,0 +1,152 @@ +"""A recording stand-in for the CLI, and two image fixtures, for the MCP tests. + +The MCP server calls ``hhstream.cli``'s handlers in this process, so what sits +between a tool and the broker is **the argv list** -- and that list is the only +thing this layer decides. :class:`FakeCli` is therefore an entry point that +records the argv it was given, prints whatever the test told it to, and returns +the exit code the test chose: everything the real entry point is, minus the +broker. + +That is also why there is no live socket anywhere in this suite. The broker's +behaviour is `tests/sessions`' subject and the VM checks'; what is left here is +the shim. Two tests in ``test_mcp_invoke.py`` do drive the **real** entry point +against a socket path that does not exist, which is the honest way to prove the +dispatch, the capture and the exit-code mapping without standing a daemon up. +""" + +from __future__ import annotations + +import json +import pathlib +import struct +import sys +import zlib +from typing import Any + + +class FakeCli: + """Where :func:`hhstream_mcp.invoke.dispatch` goes in a test. + + Prints through ``sys.stdout``/``sys.stderr`` rather than returning text, so + the capture under test is exercised rather than bypassed. + """ + + def __init__( + self, + *, + stdout: str = "", + stderr: str = "", + exit_code: int = 0, + write_png: bytes | None = None, + raises: BaseException | None = None, + ) -> None: + self.stdout = stdout + self.stderr = stderr + self.exit_code = exit_code + self.write_png = write_png + self.raises = raises + #: Every argv this was called with, in order. + self.calls: list[list[str]] = [] + + def __call__(self, argv: list[str]) -> int: + self.calls.append(list(argv)) + if self.write_png is not None: + destination = _value_of("--out", argv) + if destination: + pathlib.Path(destination).write_bytes(self.write_png) + if self.stdout: + sys.stdout.write(self.stdout) + if self.stderr: + sys.stderr.write(self.stderr) + if self.raises is not None: + raise self.raises + return self.exit_code + + @property + def argv(self) -> list[str]: + """The single call's argv. Fails loudly if there was not exactly one.""" + + assert len(self.calls) == 1, f"expected one CLI call, got {self.calls}" + return self.calls[0] + + +def _value_of(name: str, argv: list[str]) -> str | None: + prefix = f"{name}=" + for argument in argv: + if argument.startswith(prefix): + return argument[len(prefix) :] + return None + + +def reply(**fields: Any) -> str: + """A protocol object the way the CLI prints one: ``json.dumps(indent=2)``.""" + + return json.dumps(fields, indent=2, sort_keys=True) + "\n" + + +def png(width: int = 8, height: int = 4) -> bytes: + """A minimal valid truecolour PNG of a known size. + + Built here rather than shared with the suite's other helper because what is + under test is "the server reports the geometry the file actually has", so + the size has to be the test's to choose. + """ + + def chunk(kind: bytes, data: bytes) -> bytes: + return ( + struct.pack(">I", len(data)) + + kind + + data + + struct.pack(">I", zlib.crc32(kind + data) & 0xFFFFFFFF) + ) + + raster = (b"\x00" + b"\x10\x20\x30" * width) * height + return ( + b"\x89PNG\r\n\x1a\n" + + chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)) + + chunk(b"IDAT", zlib.compress(raster, 9)) + + chunk(b"IEND", b"") + ) + + +def jpeg(width: int = 6, height: int = 3) -> bytes: + """Enough of a JPEG to carry a SOF0: magic, APP0, SOF0, EOI. + + Not a decodable image, deliberately: what is under test is the header scan + that has to skip a segment it does not care about and find the one it does. + """ + + app0 = ( + b"\xff\xe0" + + struct.pack(">H", 16) + + b"JFIF\x00" + + b"\x01\x01\x00" + + b"\x00\x01" * 2 + + b"\x00\x00" + ) + sof0 = ( + b"\xff\xc0" + + struct.pack(">H", 11) + + b"\x08" + + struct.pack(">HH", height, width) + + b"\x01\x01\x11\x00" + ) + return b"\xff\xd8" + app0 + sof0 + b"\xff\xd9" + + +def isolate(monkeypatch, tmp_path: pathlib.Path) -> None: + """Point every path the CLI reads from the environment at ``tmp_path``. + + A developer's shell has `$HHSTREAM_SOCKET` set, and the real entry point + reads it -- so without this a test could reach a live broker on the machine + it is running on. The lease directory is redirected for the same reason: + `pointer acquire` writes a cache there, and a test must not touch the one a + real session is using. + """ + + monkeypatch.setenv("HHSTREAM_SOCKET", str(tmp_path / "control.sock")) + monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(tmp_path / "stream.sock")) + monkeypatch.setenv("HHSTREAM_LEASE_DIR", str(tmp_path / "leases")) + # `$HHSTREAM_LEASE` outranks the cache in `hhstream_session.lease.recall`, + # so an inherited one would hand a gesture a lease it never acquired. + monkeypatch.delenv("HHSTREAM_LEASE", raising=False) diff --git a/tests/unit/test_mcp_invoke.py b/tests/unit/test_mcp_invoke.py new file mode 100644 index 0000000..e3fefe7 --- /dev/null +++ b/tests/unit/test_mcp_invoke.py @@ -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 diff --git a/tests/unit/test_mcp_server.py b/tests/unit/test_mcp_server.py new file mode 100644 index 0000000..b564a67 --- /dev/null +++ b/tests/unit/test_mcp_server.py @@ -0,0 +1,312 @@ +"""The SDK wiring: the handshake, the listing, and one call of each shape. + +This is the file that imports the MCP SDK, and it does so unconditionally. The +tool table is standard library and tested without it +(``test_mcp_tools.py``); what is left is the part only the SDK can judge -- +whether every schema validates, whether every name is one the specification +allows, and whether a refusal arrives as a tool error rather than a success. A +file that skipped when the SDK was absent would be green in exactly the build +where that mattered, which is why ``checks/unit.nix`` puts ``mcp`` in the test +environment rather than making it optional. + +The server runs in process, over the SDK's in-memory transport. The stdio +transport itself is proved end to end by ``checks/vm-mcp.nix`` and by the +handshake in the pull request description -- a pair of memory streams cannot +tell you that a stray ``print`` has corrupted stdout. +""" + +from __future__ import annotations + +import json +import os + +import anyio +import jsonschema +import mcp.types as types +import mcp_fake +import pytest +from hhstreamd.protocol import ExitCode +from mcp.shared.memory import create_connected_server_and_client_session +from mcp.shared.tool_name_validation import validate_tool_name + +from hhstream_mcp import SERVER_NAME, __version__, invoke, server, tools + + +@pytest.fixture(autouse=True) +def _isolated(monkeypatch, tmp_path): + mcp_fake.isolate(monkeypatch, tmp_path) + + +@pytest.fixture +def session(): + """`session(...)` -> (the recording CLI, a connected client session). + + The stand-in is scripted per test, exactly as in the table's own tests; + what is added here is a real client on the other end of a real server, so + `initialize` and the two request types are exercised rather than asserted + about. + """ + + def _session(**script): + fake = mcp_fake.FakeCli(**script) + built = server.build(invoke.Runner(fake)) + return fake, create_connected_server_and_client_session( + built, raise_exceptions=True + ) + + return _session + + +def run(coroutine): + return anyio.run(coroutine) + + +# ── the handshake ────────────────────────────────────────────────────────── + + +def test_initialize_names_this_server_and_declares_tools(session): + _, connected = session() + + async def go(): + async with connected as client: + result = await client.initialize() + return result + + initialized = run(go) + assert initialized.serverInfo.name == SERVER_NAME + assert initialized.serverInfo.version == __version__ + assert initialized.capabilities.tools is not None + # The instructions are where the two rules are said once for the whole + # surface; a client that shows them must be given them. + assert initialized.instructions + assert "`session_touch` is the ONLY" in initialized.instructions + + +def test_the_instructions_carry_both_rules(): + assert "`session_touch` is the ONLY" in server.INSTRUCTIONS + assert "POINTER lease" in server.INSTRUCTIONS + assert "There is no keyboard lease" in server.INSTRUCTIONS + # And the two lease codes an agent has to tell apart. + assert "Exit 8 means" in server.INSTRUCTIONS + assert "9 means you need to acquire one" in server.INSTRUCTIONS + + +# ── the listing ──────────────────────────────────────────────────────────── + + +def test_tools_list_returns_every_tool_with_a_title_and_a_description(session): + _, connected = session() + + async def go(): + async with connected as client: + await client.initialize() + return await client.list_tools() + + listed = run(go).tools + assert {tool.name for tool in listed} == set(tools.BY_NAME) + for tool in listed: + assert tool.title, tool.name + assert tool.description and len(tool.description) > 40, tool.name + assert tool.annotations is not None + assert tool.annotations.openWorldHint is False + + +def test_every_tool_name_is_one_the_specification_allows(): + for tool in tools.TOOLS: + result = validate_tool_name(tool.name) + assert result.is_valid, (tool.name, result.warnings) + # Warnings are not failures to the SDK, but a name that earns one is a + # name that will be mangled by some client. + assert result.warnings == [], (tool.name, result.warnings) + + +def test_every_input_schema_is_a_schema_the_validator_accepts(): + """The SDK validates every call against these; a bad one fails at call time.""" + + for tool in tools.TOOLS: + jsonschema.Draft202012Validator.check_schema(tool.schema) + + +def test_the_read_only_hint_is_set_from_the_verb_and_not_from_the_name(): + for tool in tools.TOOLS: + described = server.describe(tool) + assert described.annotations.readOnlyHint == tool.read_only + if tool.read_only: + assert described.annotations.destructiveHint is None + else: + assert described.annotations.destructiveHint is tool.destructive + + +# ── the schemas, through the validator the server actually uses ──────────── + + +def test_move_requires_exactly_one_of_to_and_by(): + schema = tools.BY_NAME["pointer_move"].schema + jsonschema.validate({"id": "s", "lease": "L", "to": [0.5, 0.5]}, schema) + jsonschema.validate({"id": "s", "lease": "L", "by": [0.5, 0.5]}, schema) + for bad in ( + {"id": "s", "lease": "L"}, + {"id": "s", "lease": "L", "to": [0.5, 0.5], "by": [0.1, 0.1]}, + {"id": "s", "lease": "L", "to": [0.5]}, + {"id": "s", "lease": "L", "to": [0.5, 0.5, 0.5]}, + ): + with pytest.raises(jsonschema.ValidationError): + jsonschema.validate(bad, schema) + + +def test_home_and_ephemeral_home_are_refused_together_by_the_schema(): + """The CLI's mutually exclusive group, moved forward to where it is cheaper.""" + + schema = tools.BY_NAME["session_start"].schema + jsonschema.validate({"app": "foot"}, schema) + jsonschema.validate({"app": "foot", "home": "/tmp/h"}, schema) + jsonschema.validate({"app": "foot", "ephemeral_home": True}, schema) + with pytest.raises(jsonschema.ValidationError): + jsonschema.validate({"app": "foot", "home": "/tmp/h", "ephemeral_home": True}, schema) + + +def test_a_gesture_without_a_lease_is_refused_before_the_cli_is_run(session): + """The lease is required, so the schema refuses and no argv is built.""" + + fake, connected = session() + + async def go(): + async with connected as client: + await client.initialize() + return await client.call_tool("pointer_click", {"id": "s-1"}) + + result = run(go) + assert result.isError + assert "lease" in result.content[0].text + # The point of a schema refusal: the CLI was never reached. + assert fake.calls == [] + + +# ── calls ────────────────────────────────────────────────────────────────── + + +def test_a_successful_call_carries_the_protocol_object_as_structured_content(session): + reply = {"ok": True, "sessions": []} + fake, connected = session(stdout=json.dumps(reply, indent=2)) + + async def go(): + async with connected as client: + await client.initialize() + return await client.call_tool("session_list", {}) + + result = run(go) + assert not result.isError + assert result.structuredContent == reply + assert fake.calls == [["session", "list", "--json"]] + + +def test_a_refused_call_arrives_as_a_tool_error_an_agent_can_read(session): + reply = {"ok": False, "error": "no_lease", "reason": "no pointer lease for s-1"} + _, connected = session( + stderr=json.dumps(reply, indent=2), exit_code=int(ExitCode.NO_LEASE) + ) + + async def go(): + async with connected as client: + await client.initialize() + return await client.call_tool( + "pointer_click", {"id": "s-1", "lease": "stale"} + ) + + result = run(go) + assert result.isError is True + assert result.structuredContent["exit_code"] == int(ExitCode.NO_LEASE) + text = result.content[0].text + assert "exit 9 (NO_LEASE)" in text + assert "pointer_acquire" in text + + +def test_a_frame_arrives_as_image_content_beside_its_geometry(session): + frame = mcp_fake.png(width=64, height=48) + _, connected = session(write_png=frame, stdout="/tmp/ignored.png\n") + + async def go(): + async with connected as client: + await client.initialize() + return await client.call_tool("shot", {}) + + result = run(go) + assert not result.isError + kinds = [block.type for block in result.content] + assert kinds == ["text", "image"] + text, image = result.content + assert "64x48 image/png" in text.text + assert image.mimeType == "image/png" + + import base64 + + assert base64.b64decode(image.data) == frame + + +def test_a_tool_that_does_not_exist_names_the_ones_that_do(session): + """And is an error. The SDK turns a raised McpError into this shape anyway.""" + + fake, connected = session() + + async def go(): + async with connected as client: + await client.initialize() + return await client.call_tool("session_detonate", {}) + + result = run(go) + assert result.isError is True + assert "no such tool: 'session_detonate'" in result.content[0].text + assert "session_touch" in result.content[0].text + assert fake.calls == [] + + +def test_a_handler_that_raises_is_reported_to_the_agent_and_not_only_logged(): + """A CLI process would have died with a traceback and status 1; so does this.""" + + fake = mcp_fake.FakeCli(raises=RuntimeError("the broker said something odd")) + result = server.call(invoke.Runner(fake), "session_list", {}) + + assert result.isError is True + assert result.structuredContent["exit_code"] == invoke.GENERIC_FAILURE + assert "the broker said something odd" in result.content[0].text + + +def test_the_transport_is_moved_off_the_descriptor_the_cli_prints_to(): + """The one thing an in-process CLI call could break, asserted directly.""" + + read_fd, write_fd = os.pipe() + saved_out, saved_err = os.dup(1), os.dup(2) + log_read, log_write = os.pipe() + try: + os.dup2(write_fd, 1) + os.dup2(log_write, 2) + _, stdout = server.claim_transport() + # After claiming, this process's own stdout is the log (fd 2), not the + # stream the client reads. + assert os.path.sameopenfile(1, 2) + assert not os.path.sameopenfile(1, stdout.wrapped.fileno()) + # ...and stdin cannot eat a request. + assert os.readlink(f"/proc/self/fd/0") == os.devnull + finally: + os.dup2(saved_out, 1) + os.dup2(saved_err, 2) + for fd in (saved_out, saved_err, read_fd, write_fd, log_read, log_write): + try: + os.close(fd) + except OSError: + pass + + +def test_the_listing_is_what_the_entry_point_prints(capsys): + """`--list-tools` is the package's own install check; keep it honest.""" + + assert server.main(["--list-tools"]) == 0 + printed = capsys.readouterr().out.splitlines() + assert len(printed) == len(tools.TOOLS) + assert printed[0].split("\t")[0] == tools.TOOLS[0].name + + +def test_content_for_a_text_only_result_has_no_image_block(): + blocks = server.content_for(tools.Result(text="hello")) + assert [block.type for block in blocks] == ["text"] + assert isinstance(blocks[0], types.TextContent) diff --git a/tests/unit/test_mcp_tools.py b/tests/unit/test_mcp_tools.py new file mode 100644 index 0000000..8e66a21 --- /dev/null +++ b/tests/unit/test_mcp_tools.py @@ -0,0 +1,553 @@ +"""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, which is every verb of the CLI. +#: Written out rather than derived from the table, because a list derived from +#: the thing it checks cannot notice a missing entry. +EXPECTED = { + # frames + "status", "shot", "record", "run", + # lifecycle + "session_start", "session_list", "session_status", "session_touch", + "session_kill", "session_gc", "session_adopt", "session_logs", + "session_container", "session_reconcile", + # pointer + "pointer_acquire", "pointer_move", "pointer_click", "pointer_scroll", + "pointer_down", "pointer_up", "pointer_release", "pointer_state", + # keyboard + "keyboard_type", "keyboard_key", "keyboard_down", "keyboard_up", +} + + +def test_every_cli_verb_has_a_tool_and_nothing_else_does(): + assert set(tools.BY_NAME) == EXPECTED + + +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(): + """`session_container` with an id reconciles, which is a write.""" + + read_only = {tool.name for tool in tools.TOOLS if tool.read_only} + assert read_only == { + "status", + "shot", + "session_list", + "session_status", + "session_logs", + "pointer_state", + } + assert not tools.BY_NAME["session_container"].read_only + # `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 verbs the CLI's own note names as NOT counting as activity. Taken from +#: the rule, so a tool that stopped carrying the warning is a failure here. +NON_ACTIVITY = { + "session_list", + "session_status", + "session_logs", + "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", +} + + +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 + for verb in ("session_list", "session_status", "session_logs", "session_gc"): + assert verb in tools.ACTIVITY_NOTE + assert "do 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", []) + + +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_list", {}) + assert calls == [["session", "list", "--json"]] + _, calls = call("session_list", {"all": True}) + assert calls == [["session", "list", "--json", "--all"]] + _, calls = call("session_list", {"all": False}) + assert calls == [["session", "list", "--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_pointer_state_takes_no_session_because_there_is_one_cursor(call): + _, calls = call("pointer_state", {}) + assert calls == [["session", "pointer", "state", "--json"]] + assert tools.BY_NAME["pointer_state"].schema["properties"] == {} + + +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"]] + + +def test_logs_has_no_follow_because_a_tool_call_must_return(call): + assert "follow" not in tools.BY_NAME["session_logs"].schema["properties"] + _, calls = call("session_logs", {"id": "s-1", "lines": 5}) + assert calls == [["session", "logs", "--json", "--lines=5", "--", "s-1"]] + + +def test_status_is_not_run_with_json_because_the_verb_has_none(call): + _, calls = call("status", {}, stdout="services:\n") + assert calls == [["status"]] + + +# ── what each tool makes of the answer ───────────────────────────────────── + + +def test_a_successful_session_verb_passes_the_protocol_object_through(call): + reply = {"ok": True, "sessions": [{"id": "s-1", "state": "running"}]} + result, _ = call("session_list", {}, 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 "pointer_state" 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_list", + {}, + 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()