feat(nix): the Platform protocol and the first neutral scenario

A scenario drives the daemon and looks at the desktop only through a
Platform: start the daemon, komorebic, state as a Snapshot, spawn a window,
os_window (the OS's own account of its frame, which is the oracle: the
daemon's state is what is under test), work_area, activate and screenshot.
Only what a scenario uses is there; a method is added with the first
scenario that needs it.

scenarios.tiling opens windows and checks, against the OS's frames, that
each is where the layout says, inside the work area and clear of the
others. Its tests run it against a fake platform that tiles correctly and
against two that do not.
This commit is contained in:
LGUG2Z committed 2026-10-30 12:02:55 -07:00
1 parent b02df47e34
commit 2c5e8f57dc
4 files changed
+265

No files matched your search

@@ -0,0 +1,90 @@
"""What a scenario needs of a platform: the hands and the eyes, behind methods.
A scenario drives the daemon and looks at the desktop only through a
[`Platform`](komorebi_vm.core.platform.Platform), so that the same scenario runs on KDE and on
Windows. A platform may implement a method on the host (QMP on QEMU) or in the guest (an agent); a
scenario cannot tell.
Only what a scenario uses today is here. A method is added with the first scenario that needs it,
and takes the shape both platforms can give.
"""
from dataclasses import dataclass
from typing import Protocol
from PIL import Image
from komorebi_vm.core.geometry import Rect
from komorebi_vm.core.snapshot import Snapshot
@dataclass(frozen=True)
class Client:
"""A window a scenario opened. `title` is its identity: a scenario gives each its own."""
title: str
@dataclass(frozen=True)
class OsWindow:
"""What the operating system says about a window, which is the oracle of a scenario.
The daemon's own state is the thing under test and is never its own oracle.
"""
title: str
frame: Rect
"""The visible frame: the compositor's on KDE, the DWM's extended frame on Windows."""
focused: bool
class Platform(Protocol):
"""A machine with a desktop and a daemon to test."""
@property
def tolerance(self) -> int:
"""How far a window's frame may be short of the one asked for, in pixels.
A terminal sizes itself to whole cells; a test window has no granularity.
"""
...
def wait_for(self, predicate: "Predicate", timeout: float = 10) -> bool:
"""Polls `predicate` until it holds or `timeout` seconds, scaled for this host, pass."""
...
def start_komorebi(self) -> None:
"""Starts the daemon from a clean state and waits until it answers."""
...
def komorebic(self, *args: str) -> str:
"""Runs `komorebic` with `args` and returns what it printed. Fails if it does."""
...
def state(self) -> Snapshot:
"""The daemon's state."""
...
def spawn(self, title: str) -> Client:
"""Opens a window with this title and waits until the platform has it."""
...
def os_window(self, client: Client) -> OsWindow | None:
"""What the operating system says about the window, or `None` if it has none."""
...
def work_area(self) -> Rect:
"""The area of the first display that windows may take."""
...
def activate(self, client: Client) -> None:
"""Gives the window the focus, as a click on it would."""
...
def screenshot(self, name: str) -> Image.Image:
"""The display as an image, kept under `name` with the other artifacts of the run."""
...
class Predicate(Protocol):
def __call__(self) -> bool: ...
@@ -0,0 +1 @@
"""Scenarios that run on every platform, written against `komorebi_vm.core.platform.Platform`."""
@@ -0,0 +1,65 @@
"""Windows that open are tiled: each where the layout says, none over another, all on screen."""
from komorebi_vm.core.checks import Checks
from komorebi_vm.core.geometry import Rect
from komorebi_vm.core.platform import Platform
def _where_the_layout_says(frame: Rect, want: Rect, tolerance: int) -> bool:
"""The same place, and the size up to `tolerance` short of what was asked for."""
return (
(frame.x, frame.y) == (want.x, want.y)
and 0 <= want.w - frame.w <= tolerance
and 0 <= want.h - frame.h <= tolerance
)
def run(
platform: Platform, checks: Checks, titles: tuple[str, ...] = ("win1", "win2", "win3")
) -> None:
"""Opens a window for each title and checks, against the OS's own account of the frames, that
the daemon has tiled them.
The daemon must be running, on a workspace with no window, with a tiling layout.
"""
clients = [platform.spawn(title) for title in titles]
area = platform.work_area()
def managed() -> bool:
return platform.state().managed() == len(titles)
checks.check("the daemon manages every window", platform.wait_for(managed, timeout=20))
def placed() -> bool:
workspace = platform.state().workspace()
layout = workspace.latest_layout
frames = [platform.os_window(c) for c in clients]
if len(layout) != len(titles) or any(f is None for f in frames):
return False
# the layout's rectangles are in the order of the containers, which is not the order the
# windows opened in: each window is matched with its own container's rectangle
by_title = {w.title: layout[i] for i, c in enumerate(workspace.containers) for w in c[:1]}
return all(
f is not None and _where_the_layout_says(f.frame, by_title[f.title], platform.tolerance)
for f in frames
)
checks.check(
"every window is where the layout says, as the OS reports it",
platform.wait_for(placed, timeout=20),
)
frames = [f.frame for c in clients if (f := platform.os_window(c)) is not None]
checks.check("the OS has a frame for every window", len(frames) == len(titles))
for client, frame in zip(clients, frames, strict=False):
checks.check(f"{client.title} is inside the work area", frame.inside(area))
for i, a in enumerate(frames):
for j in range(i + 1, len(frames)):
checks.check(
f"{clients[i].title} and {clients[j].title} do not overlap",
not a.overlaps(frames[j]),
)
checks.check(
"the windows share the work area: none takes all of its width",
all(f.w < area.w - platform.tolerance for f in frames),
)
+109
View File
@@ -0,0 +1,109 @@
"""The tiling scenario against a platform that tiles correctly, and against ones that do not."""
from PIL import Image
from komorebi_vm.core.checks import Checks
from komorebi_vm.core.geometry import Rect
from komorebi_vm.core.platform import Client, OsWindow
from komorebi_vm.core.scenarios import tiling
from komorebi_vm.core.snapshot import Snapshot, parse
class FakePlatform:
"""A desktop in memory: `spawn` opens a window, and the frames are the ones it is given."""
tolerance = 24
def __init__(self, frames: list[Rect]) -> None:
self.frames = frames
self.opened: list[str] = []
def wait_for(self, predicate, timeout: float = 10) -> bool: # noqa: ANN001
return predicate()
def spawn(self, title: str) -> Client:
self.opened.append(title)
return Client(title)
def state(self) -> Snapshot:
return parse(_state(self.opened))
def os_window(self, client: Client) -> OsWindow | None:
i = self.opened.index(client.title)
return OsWindow(client.title, self.frames[i], focused=False)
def work_area(self) -> Rect:
return Rect(0, 0, 1920, 1080)
def start_komorebi(self) -> None:
pass
def komorebic(self, *args: str) -> str:
return ""
def activate(self, client: Client) -> None:
pass
def screenshot(self, name: str) -> Image.Image:
return Image.new("RGB", (4, 4))
def _state(titles: list[str]) -> dict:
width = 1920 // len(titles)
rects = [
{"left": i * width, "top": 0, "right": width, "bottom": 1080} for i in range(len(titles))
]
windows = [
{"id": i + 1, "rect": rects[i], "details": {"title": t, "exe": "", "class": "", "path": ""}}
for i, t in enumerate(titles)
]
workspace = {
"name": None,
"containers": {
"elements": [
{"id": str(i), "locked": False, "windows": {"elements": [w], "focused": 0}}
for i, w in enumerate(windows)
],
"focused": 0,
},
"monocle_container": None,
"maximized_window": None,
"floating_windows": {"elements": [], "focused": 0},
"layout": {"Default": "Columns"},
"tile": True,
"latest_layout": rects,
}
monitor = {
"id": 1,
"size": {"left": 0, "top": 0, "right": 1920, "bottom": 1080},
"workspaces": {"elements": [workspace], "focused": 0},
}
return {"monitors": {"elements": [monitor], "focused": 0}}
def test_windows_that_are_tiled_pass() -> None:
platform = FakePlatform(
[Rect(0, 0, 640, 1080), Rect(640, 0, 640, 1080), Rect(1280, 0, 640, 1080)]
)
checks = Checks()
tiling.run(platform, checks)
assert checks.failed == 0
assert checks.passed > 0
def test_windows_over_each_other_fail() -> None:
platform = FakePlatform(
[Rect(0, 0, 700, 1080), Rect(640, 0, 640, 1080), Rect(1280, 0, 640, 1080)]
)
checks = Checks()
tiling.run(platform, checks)
assert any("overlap" in f for f in checks.failures)
def test_a_window_off_the_screen_fails() -> None:
platform = FakePlatform(
[Rect(0, 0, 640, 1080), Rect(640, 0, 640, 1080), Rect(1500, 0, 640, 1080)]
)
checks = Checks()
tiling.run(platform, checks)
assert any("inside the work area" in f for f in checks.failures)