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

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

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

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

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

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

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

No files matched your search

+152
View File
@@ -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)
+389
View File
@@ -0,0 +1,389 @@
"""The runner: how the CLI is called in process, decoded, and mapped to a code.
Most of this drives a recording stand-in (:class:`mcp_fake.FakeCli`), because
the subject is what this layer decides -- the argv list and the mapping. Three
tests drive the **real** entry point, against a control socket that does not
exist: that is the honest way to prove the dispatch, the capture and the
exit-code mapping against the CLI's actual parser without standing a daemon up.
"""
from __future__ import annotations
import contextlib
import os
import signal
import mcp_fake
import pytest
from hhstreamd.protocol import ExitCode
from hhstream_mcp import invoke, media
@pytest.fixture(autouse=True)
def _isolated(monkeypatch, tmp_path):
mcp_fake.isolate(monkeypatch, tmp_path)
# ── the call ───────────────────────────────────────────────────────────────
def test_the_argv_reaches_the_entry_point_unchanged():
fake = mcp_fake.FakeCli(stdout="hello\n")
outcome = invoke.Runner(fake).run(["session", "list", "--json"])
assert outcome.ok
assert outcome.stdout == "hello\n"
assert fake.argv == ["session", "list", "--json"]
assert outcome.argv == ["session", "list", "--json"]
def test_a_metacharacter_is_one_argument_and_never_a_statement():
"""There is no shell between a tool and the CLI, and no string either."""
fake = mcp_fake.FakeCli()
nasty = "; rm -rf / #"
invoke.Runner(fake).run(["session", "keyboard", "type", "--", "s1", nasty])
assert fake.argv == ["session", "keyboard", "type", "--", "s1", nasty]
def test_what_the_cli_prints_is_captured_and_not_leaked_to_the_transport(capsys):
"""A print on stdout here would be a parse error at the client."""
fake = mcp_fake.FakeCli(stdout="on stdout\n", stderr="on stderr\n")
outcome = invoke.Runner(fake).run(["status"])
assert outcome.stdout == "on stdout\n"
assert outcome.stderr == "on stderr\n"
escaped = capsys.readouterr()
assert escaped.out == ""
assert escaped.err == ""
def test_sys_exit_is_the_exit_code_a_process_would_have_had():
"""argparse refuses with `sys.exit(2)`; handlers exit on a missing tool."""
fake = mcp_fake.FakeCli(raises=SystemExit(2))
assert invoke.Runner(fake).run(["session"]).returncode == int(ExitCode.USAGE)
# `sys.exit("message")` is status 1 in a real process, and the message is
# the exit code object rather than something printed.
fake = mcp_fake.FakeCli(raises=SystemExit("hhstream: grim is not on PATH"))
assert invoke.Runner(fake).run(["shot"]).returncode == invoke.GENERIC_FAILURE
fake = mcp_fake.FakeCli(raises=SystemExit(None))
assert invoke.Runner(fake).run(["status"]).returncode == 0
def test_an_uncaught_exception_becomes_exit_one_with_its_traceback():
"""What a CLI process would have done, rather than a transport error."""
fake = mcp_fake.FakeCli(raises=RuntimeError("boom"))
outcome = invoke.Runner(fake).run(["session", "list", "--json"])
assert outcome.returncode == invoke.GENERIC_FAILURE
assert "RuntimeError: boom" in outcome.stderr
assert "Traceback" in outcome.stderr
def test_a_keyboard_interrupt_is_not_swallowed_as_a_tool_result():
"""BaseException is caught on purpose; the code still says "failed"."""
fake = mcp_fake.FakeCli(raises=KeyboardInterrupt())
outcome = invoke.Runner(fake).run(["session", "list"])
assert outcome.returncode == invoke.GENERIC_FAILURE
def test_a_call_runs_with_the_serialising_lock_held():
"""The CLI prints to a process-global stdout, so one call at a time.
Asserted from inside the call rather than by racing two threads and hoping
their output interleaves: a race that passes by luck is not a test. The
private name is the point -- what is being asserted is that this specific
lock is held while a handler runs.
"""
def probing(argv):
free = invoke._ONE_AT_A_TIME.acquire(blocking=False)
if free:
invoke._ONE_AT_A_TIME.release()
print("free" if free else "held", end="")
return 0
assert invoke.Runner(probing).run(["status"]).stdout == "held"
# ── decoding ───────────────────────────────────────────────────────────────
def test_the_protocol_object_is_read_from_stdout_on_success():
fields = {"ok": True, "id": "s-1", "session": {"state": "running"}}
fake = mcp_fake.FakeCli(stdout=mcp_fake.reply(**fields))
assert invoke.Runner(fake).run(["session", "status", "--json"]).payload() == fields
def test_the_protocol_object_is_read_from_stderr_on_failure():
"""The CLI's own split: an error goes to stderr whatever the output mode."""
fields = {"ok": False, "error": "no_lease", "reason": "no pointer lease for s-1"}
fake = mcp_fake.FakeCli(
stderr=mcp_fake.reply(**fields), exit_code=int(ExitCode.NO_LEASE)
)
outcome = invoke.Runner(fake).run(["session", "pointer", "click", "--json"])
assert not outcome.ok
assert outcome.payload() == fields
def test_an_object_printed_under_a_bare_line_is_still_found():
"""`session start` prints the id beside its object; parsing must survive it."""
fake = mcp_fake.FakeCli(stdout='s-1\n{\n "ok": true,\n "id": "s-1"\n}\n')
assert invoke.Runner(fake).run(["session", "start"]).payload() == {
"ok": True,
"id": "s-1",
}
def test_no_json_at_all_is_none_rather_than_an_invention():
fake = mcp_fake.FakeCli(stdout="services:\n hyprland-headless.service active\n")
assert invoke.Runner(fake).run(["status"]).payload() is None
def test_a_json_array_is_not_mistaken_for_the_protocol_object():
assert invoke.first_json_object("[1, 2, 3]") is None
assert invoke.first_json_object('[{"a": 1}]') == {"a": 1}
# ── the real entry point, with nothing listening ───────────────────────────
def test_the_real_cli_refuses_a_bad_flag_with_the_frozen_usage_code():
"""argparse's own refusal, through the CLI's own parser, mapped to exit 2."""
outcome = invoke.Runner().run(
["session", "pointer", "click", "--json", "--button=nonsense", "--", "s-1"]
)
assert outcome.returncode == int(ExitCode.USAGE)
assert "invalid choice" in outcome.stderr
# And nothing escaped onto the real stdout: argparse prints usage there for
# --help and to stderr for an error, and both are captured.
assert outcome.stdout == ""
def test_the_real_cli_reports_an_unreachable_broker_as_the_frozen_code():
"""No socket, no daemon, no fake: the mapping end to end."""
outcome = invoke.Runner().run(["session", "list", "--json"])
assert outcome.returncode == int(ExitCode.DAEMON_UNREACHABLE)
payload = outcome.payload()
assert payload is not None
assert payload["error"] == "daemon_unreachable"
def test_the_real_cli_refuses_a_gesture_with_no_lease_without_a_broker():
"""Exit 9 is produced by the CLI before the socket is touched at all."""
outcome = invoke.Runner().run(
["session", "pointer", "click", "--json", "--", "s-1"]
)
assert outcome.returncode == int(ExitCode.NO_LEASE)
assert (outcome.payload() or {}).get("error") == "no_lease"
def test_an_unreachable_frame_socket_earns_the_hint_the_sg_re_exec_replaces():
"""The one capability lost by calling the CLI in process, said out loud."""
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=1)).run(["shot"])
assert "cannot read" in outcome.stderr
assert "sg hhstream" in outcome.stderr
def test_the_hint_is_absent_when_the_socket_is_readable(tmp_path, monkeypatch):
readable = tmp_path / "stream.sock"
readable.write_bytes(b"")
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(readable))
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=1)).run(["shot"])
assert "sg hhstream" not in outcome.stderr
def test_a_session_verb_never_earns_the_frame_socket_hint():
"""It has nothing to do with the control socket, so it must not be offered."""
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=int(ExitCode.BUSY))).run(
["session", "pointer", "acquire", "--json", "--", "s-1"]
)
assert "sg hhstream" not in outcome.stderr
# ── the exit-code table ────────────────────────────────────────────────────
@pytest.mark.parametrize(
"code",
[
ExitCode.USAGE,
ExitCode.NO_SUCH_SESSION,
ExitCode.BAD_STATE,
ExitCode.DAEMON_UNREACHABLE,
ExitCode.POLICY,
ExitCode.TIMEOUT,
ExitCode.BUSY,
ExitCode.NO_LEASE,
ExitCode.COMPOSITOR,
],
)
def test_every_frozen_exit_code_has_a_remedy_naming_itself(code):
"""A new code in the frozen table must not fall through to a generic line."""
text = invoke.remedy_for(int(code))
assert text.startswith(f"exit {int(code)} ({code.name})")
assert int(code) in invoke.REMEDY
def test_the_lease_codes_say_the_two_different_things_an_agent_must_do():
"""8 and 9 are the pair that must never read alike (CONTRACT-sessions.md §4)."""
busy = invoke.remedy_for(int(ExitCode.BUSY))
none_held = invoke.remedy_for(int(ExitCode.NO_LEASE))
assert "pointer_state" in busy and "wait" in busy
assert "pointer_acquire" in none_held
# "acquire one" must not be the advice for BUSY: that is the one confusion
# the two codes exist to prevent.
assert "pointer_acquire" not in busy
def test_an_unclassified_code_is_still_a_failure_and_says_so():
text = invoke.remedy_for(42)
assert "exit 42 (UNCLASSIFIED)" in text
assert "do not assume anything happened" in text
def test_generic_failure_is_its_own_case():
"""Exit 1 is the frame verbs', and is not in the broker's frozen table."""
assert invoke.GENERIC_FAILURE not in [int(code) for code in ExitCode]
assert "grim" in invoke.remedy_for(invoke.GENERIC_FAILURE)
# ── launch, for `run` ──────────────────────────────────────────────────────
def test_launch_leaves_the_application_running_in_its_own_session(wayland):
"""`run` launches and forgets, and a killed server must not take it along."""
spawned = invoke.Runner().launch(["sleep", "30"], settle=0.3)
try:
assert not spawned.exited
assert spawned.pid > 0
os.kill(spawned.pid, 0)
# Its own session, so a client that kills this server's process group
# does not kill the desktop with it.
assert os.getsid(spawned.pid) == spawned.pid
assert os.getsid(spawned.pid) != os.getsid(0)
finally:
with contextlib.suppress(ProcessLookupError):
os.kill(spawned.pid, signal.SIGTERM)
def test_launch_reports_an_application_that_died_inside_the_window(wayland):
spawned = invoke.Runner().launch(["false"], settle=5.0)
assert spawned.exited
assert spawned.pid > 0
def test_launch_hands_back_what_a_failing_application_said(wayland):
spawned = invoke.Runner().launch(
["sh", "-c", "echo 'cannot open display' >&2; exit 3"], settle=5.0
)
assert spawned.exited
assert "cannot open display" in spawned.stderr
def test_launch_refuses_a_command_that_is_not_on_path_rather_than_forking(wayland):
spawned = invoke.Runner().launch(["definitely-not-a-program-here"], settle=5.0)
assert spawned.exited
assert spawned.pid == 0
assert "no executable" in spawned.stderr
def test_launch_passes_on_the_cli_s_own_refusal_when_there_is_no_compositor(tmp_path, monkeypatch):
"""`env_for_session` exits with the message; it is handed on verbatim."""
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(tmp_path / "empty" / "stream.sock"))
(tmp_path / "empty").mkdir()
spawned = invoke.Runner().launch(["true"], settle=1.0)
assert spawned.exited
assert spawned.pid == 0
assert "no wayland socket" in spawned.stderr
assert "is the compositor up?" in spawned.stderr
@pytest.fixture
def wayland(workdir, monkeypatch):
"""A runtime directory with something `env_for_session` accepts in it.
A real AF_UNIX socket, because that function checks `is_socket()` -- an
empty file would make it refuse for a reason these tests are not about.
The suite's `workdir` fixture and not `tmp_path`, because an AF_UNIX
address is capped near 108 bytes and pytest's own paths are longer than
that.
"""
import socket
listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
listener.bind(str(workdir / "wayland-0"))
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(workdir / "stream.sock"))
yield workdir
listener.close()
# ── artefact readers ───────────────────────────────────────────────────────
def test_a_png_is_sniffed_by_its_header_not_its_extension():
image = media.sniff(mcp_fake.png(width=13, height=7))
assert image is not None
assert (image.media_type, image.width, image.height) == ("image/png", 13, 7)
def test_a_jpeg_under_a_png_filename_is_still_a_jpeg():
"""The publisher serves `image/jpeg` on the deployment machine."""
image = media.sniff(mcp_fake.jpeg(width=6, height=3))
assert image is not None
assert (image.media_type, image.width, image.height) == ("image/jpeg", 6, 3)
def test_an_unrecognised_format_is_none_rather_than_a_guess():
assert media.sniff(b"GIF89a\x00\x00") is None
assert media.sniff(b"") is None
def test_the_measured_record_rate_is_read_off_the_cli_s_own_line():
found = media.recording("/tmp/out.mp4 (57 frames in 6.02s -> 9 fps)\n")
assert found is not None
assert (found.path, found.frames, found.seconds, found.fps) == ("/tmp/out.mp4", 57, 6.02, 9)
def test_a_record_line_in_an_unexpected_shape_is_not_half_parsed():
assert media.recording("/tmp/out.mp4\n") is None
assert media.recording("") is None
def test_temp_name_is_unique_per_process_and_under_a_named_directory():
first = invoke.temp_name("recording", ".mp4")
assert "hhstream-mcp" in first
assert first.endswith(".mp4")
assert str(os.getpid()) in first
+312
View File
@@ -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)
+553
View File
@@ -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()