test(mcp): the argv each tool builds, the mapping, and the server in a guest
101 unit tests under `tests/unit/` and one new VM check. The unit suite's subject is the only thing this layer decides: the argv list. `mcp_fake.FakeCli` is a recording stand-in put where the CLI goes, so every test can assert on the exact argv a tool handed over -- the `=` form of each flag, the `--` before each positional, the omission of a flag the caller did not give. Three tests drive the **real** entry point against a control socket that does not exist, which proves the dispatch, the capture and the exit-code mapping against the CLI's actual parser with no daemon standing up: argparse's exit 2 for a bad `--button`, exit 5 for the unreachable broker, exit 9 for a gesture with no lease. `test_mcp_server.py` imports the MCP SDK unconditionally and runs the server in process over the SDK's memory transport. It is not allowed to skip: the tool table is stdlib and tested without the SDK, but whether every schema validates and every name is one the specification allows is a question only the SDK can answer, and a file that skipped when it was absent would be green in exactly the build where that mattered. `checks/unit.nix` therefore puts `mcp` in the test environment and `hhstream-mcp` on PYTHONPATH beside `hhstream`. `checks/vm-mcp.nix` boots the session machine with `mcp.enable = true` and drives the real binary over a real pipe with `checks/lib/mcp_client.py` -- raw JSON-RPC, deliberately not the SDK's client, for the reason `tests/assert_stream.py` is a second implementation of the frame contract. It asserts the handshake, the 26-tool listing with its annotations and its two rules, a call that reaches the live broker, `shot` as image content, the lease granted/used/returned against the real driver, and exits 9 and 3 arriving as tool errors. The geometry assertion in that check is one it got wrong first time and now records: the published frame is 2560x720 on a guest configured for 1280x720, because the publisher's default capture takes the whole compositor layout and a session's container is a second output beside the main one. `shot` with the container's own `output` is the one that is exactly 1280x720. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
This commit is contained in:
1 parent
549c73e8ae
commit
fea55eecde
8 files changed
+1984
-3
No files matched your search
+8
-1
@@ -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; });
|
||||
}
|
||||
Executable
+175
@@ -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())
|
||||
+20
-2
@@ -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 \
|
||||
|
||||
@@ -0,0 +1,375 @@
|
||||
# checks.<system>.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
|
||||
'';
|
||||
}
|
||||
)
|
||||
@@ -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)
|
||||
@@ -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
|
||||
@@ -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)
|
||||
@@ -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()
|
||||
Reference in new issue
Block a user