diff --git a/docs/dev/vm-tests.md b/docs/dev/vm-tests.md index 02bd441d..0c34d991 100644 --- a/docs/dev/vm-tests.md +++ b/docs/dev/vm-tests.md @@ -48,6 +48,21 @@ place windows and answer questions about them, but it cannot take a screenshot. KWin wants a DRM render node, which needs a GPU. The test driver gives every aarch64 guest one `virtio-gpu-pci`; on x86_64 the node adds it, unless `komorebi.vm.renderNode` is false. +`session` is the headless node plus a login: plasma-login-manager logs the test +user in by itself, as in nixpkgs' own `plasma6` test, and Plasma draws on the +machine's display device. It is the node for anything that needs pixels. The +choice of login manager is made in +[`nodes/session.nix`](../../nix/tests/vm/nodes/session.nix) and nowhere else; +the file says how to switch to sddm, the other one that has been seen to work. +Its display is 1280x800, because screenshots are taken of the machine's one +display device: the `virtio-gpu-pci` that the test driver adds to every aarch64 +guest, and the default VGA of an x86_64 one. The node sets +`komorebi.vm.renderNode` to false, so that an x86_64 guest does not get a second +device: KWin would draw on it, and the screenshot would show the other one. + +On aarch64 under HVF, at time of writing (2026-10-27), the session has the +Wayland socket after 11 to 19 seconds and a painted desktop after 35 seconds. + ## The library Suites import from `komorebi_vm`, in @@ -66,10 +81,24 @@ the run. `outputs` counts the enabled outputs through `kscreen-doctor`, `spawn` starts a client, and `wait_for(predicate, timeout)` polls, with the timeout multiplied by `scale`. +- `Kde.session(machine, scale=)` attaches to the session node's own Plasma + session once its desktop is up, and `shot(name)` returns a screenshot as a + Pillow image, keeping `NAME.png` in the output directory. Poll for what the test needs with `wait_for`. A fixed sleep is too long on KVM and too short on TCG. +Two traps are worth knowing about before writing a screenshot test: + +- A splash screen is not a blank screen. KSplash has more than a thousand colors + on it, so "the screenshot is not blank" passes while Plasma is still + starting. `Kde.session` waits for the splash process to exit, and a test + should check a pixel it knows, such as the middle of a terminal. +- NixOS wraps programs, so a process's name is the wrapper's (`.plasmashell-wrapped`), + and `pgrep -x plasmashell` never matches. Match the command line instead, with + a bracket in the pattern (`pgrep -f '[p]lasmashell'`) so that the shell running + `pgrep` does not match itself. + ## Running a test on a Mac QEMU has to run on the Mac to use HVF, and the guest is Linux, so the guest's @@ -108,7 +137,7 @@ Add `git add -N` for new files first: a flake only sees files git knows about. ## Looking inside a failed run -`nix build -L` prints the guest's console. Run the driver by hand, as +`nix build -L` prints the guest's console, and a session test keeps its screenshots. Run the driver by hand, as `scripts/vm-mac` does, to keep the screenshots. For an interactive session build `driverInteractive` instead of `driver`, run it, and call `start_all()` and `machine.shell_interact()` at its prompt. In the guest, KWin's own log is diff --git a/nix/tests/vm/default.nix b/nix/tests/vm/default.nix index 96255143..66fc2b82 100644 --- a/nix/tests/vm/default.nix +++ b/nix/tests/vm/default.nix @@ -24,6 +24,7 @@ let fileset = ./lib; }; build-system = [ ps.setuptools ]; + dependencies = [ ps.pillow ]; doCheck = false; }; diff --git a/nix/tests/vm/lib/komorebi_vm/__init__.py b/nix/tests/vm/lib/komorebi_vm/__init__.py index 4d2c4b4a..6b771634 100644 --- a/nix/tests/vm/lib/komorebi_vm/__init__.py +++ b/nix/tests/vm/lib/komorebi_vm/__init__.py @@ -4,7 +4,7 @@ A suite imports what it needs from here: * [`Checks`](komorebi_vm.checks.Checks) counts checks and fails at the end. * [`Kde`](komorebi_vm.kde.Kde) is a KWin session inside a test machine, with - the tools to look at it (`kdotool`, `busctl`, `kscreen-doctor`). + the tools to look at it (`kdotool`, `busctl`, `kscreen-doctor`, screenshots). The library depends on the small [`Machine`](komorebi_vm.machine.Machine) protocol, not on the test driver, so `nix/tests/vm/lib/tests` can run it diff --git a/nix/tests/vm/lib/komorebi_vm/kde.py b/nix/tests/vm/lib/komorebi_vm/kde.py index 8b0faa4b..9c2c9fb5 100644 --- a/nix/tests/vm/lib/komorebi_vm/kde.py +++ b/nix/tests/vm/lib/komorebi_vm/kde.py @@ -5,6 +5,8 @@ import time from collections.abc import Callable from dataclasses import dataclass +from PIL import Image + from komorebi_vm.machine import Machine @@ -35,6 +37,10 @@ class Kde: side under different names and none touches another. Every command is run as the test user, with the environment of the named session. + A session node has one more: the user's own Plasma session, which + [`Kde.session`][] attaches to. Its bus is `$XDG_RUNTIME_DIR/bus` and its + Wayland socket is whatever the user manager says it is. + `scale` multiplies every wait: 1 under KVM, more where the machine is slower (HVF on a Mac, TCG anywhere). """ @@ -47,12 +53,16 @@ class Kde: user: str = "komorebi", uid: int = 1000, scale: float = 1.0, + bus: str | None = None, + wayland_display: str | None = None, ) -> None: self.machine = machine self.name = name self.user = user self.uid = uid self.scale = scale + self._bus = bus + self._wayland_display = wayland_display @classmethod def headless( @@ -78,6 +88,49 @@ class Kde: raise AssertionError(f"KWin did not come up:\n{log}") return kde + @classmethod + def session( + cls, + machine: Machine, + *, + user: str = "komorebi", + uid: int = 1000, + scale: float = 1.0, + timeout: float = 300, + ) -> "Kde": + """Attaches to the user's Plasma session once its desktop is up. + + The session is up when the shell is running, the user manager knows the + Wayland socket, and the splash screen has gone. The last condition is + the one a screenshot test depends on: a splash screen already has + thousands of colors on it. NixOS wraps its programs, so the processes + are found by their command lines (`pgrep -x` would see only the wrapper's + name), with the first letter in brackets so that the pattern does not + match the shell that runs `pgrep`. + """ + kde = cls(machine, "session", user=user, uid=uid, scale=scale) + kde._bus = f"unix:path={kde.runtime}/bus" + if not kde.wait_for(lambda: kde.run("pgrep -f '[p]lasmashell'")[0] == 0, timeout=timeout): + raise AssertionError("plasmashell did not start") + + def display() -> str: + out = kde.as_user("systemctl --user show-environment") + return next( + ( + line.split("=", 1)[1] + for line in out.splitlines() + if line.startswith("WAYLAND_DISPLAY=") + ), + "", + ) + + if not kde.wait_for(lambda: display() != "", timeout=timeout): + raise AssertionError("the user manager never learned the Wayland display") + kde._wayland_display = display() + if not kde.wait_for(lambda: kde.run("pgrep -f '[k]splashqml'")[0] != 0, timeout=timeout): + raise AssertionError("the splash screen did not go away") + return kde + @property def runtime(self) -> str: """The test user's runtime directory.""" @@ -88,8 +141,9 @@ class Kde: """The `VAR=value` words that put a command inside this session.""" pairs = { "XDG_RUNTIME_DIR": self.runtime, - "DBUS_SESSION_BUS_ADDRESS": f"unix:path={self.runtime}/session-{self.name}.bus", - "WAYLAND_DISPLAY": f"wayland-{self.name}", + "DBUS_SESSION_BUS_ADDRESS": self._bus + or f"unix:path={self.runtime}/session-{self.name}.bus", + "WAYLAND_DISPLAY": self._wayland_display or f"wayland-{self.name}", "KDE_SESSION_VERSION": "6", "XDG_CURRENT_DESKTOP": "KDE", "XDG_SESSION_TYPE": "wayland", @@ -174,6 +228,14 @@ class Kde: lines = self.run("kdotool getactivewindow")[1].strip().splitlines() return lines[-1] if lines else "" + def shot(self, name: str) -> Image.Image: + """Takes a screenshot of the machine's display and returns it, as RGB. + + The file is also kept as `NAME.png` in the test's output directory. + """ + self.machine.screenshot(name) + return Image.open(self.machine.out_dir / f"{name}.png").convert("RGB") + def outputs(self) -> int: """The number of outputs KWin has enabled.""" return int(self.sh("kscreen-doctor -j | jq '[.outputs[] | select(.enabled)] | length'")) diff --git a/nix/tests/vm/lib/komorebi_vm/machine.py b/nix/tests/vm/lib/komorebi_vm/machine.py index 6162ecf8..17a17e12 100644 --- a/nix/tests/vm/lib/komorebi_vm/machine.py +++ b/nix/tests/vm/lib/komorebi_vm/machine.py @@ -30,3 +30,7 @@ class Machine(Protocol): def fail(self, *commands: str) -> str: """Runs each command and fails the test if it exits with status 0.""" ... + + def screenshot(self, filename: str, /) -> None: + """Saves a PNG of the machine's display as `filename` in `out_dir`.""" + ... diff --git a/nix/tests/vm/lib/pyproject.toml b/nix/tests/vm/lib/pyproject.toml index 110f6bf6..3378f686 100644 --- a/nix/tests/vm/lib/pyproject.toml +++ b/nix/tests/vm/lib/pyproject.toml @@ -7,6 +7,7 @@ name = "komorebi-vm" version = "0.1.0" description = "Helpers for the NixOS VM tests of komorebi for KDE" requires-python = ">=3.12" +dependencies = ["pillow"] [tool.setuptools] packages = ["komorebi_vm"] diff --git a/nix/tests/vm/lib/tests/conftest.py b/nix/tests/vm/lib/tests/conftest.py index 089a9f9b..67827553 100644 --- a/nix/tests/vm/lib/tests/conftest.py +++ b/nix/tests/vm/lib/tests/conftest.py @@ -4,14 +4,15 @@ from collections.abc import Callable from pathlib import Path import pytest +from PIL import Image class FakeMachine: """Answers `execute` with the first matching reply, and records every command.""" - out_dir = Path("/tmp") + def __init__(self, out_dir: Path) -> None: + self.out_dir = out_dir - def __init__(self) -> None: self.commands: list[str] = [] self.replies: list[tuple[Callable[[str], bool], tuple[int, str]]] = [] @@ -26,6 +27,9 @@ class FakeMachine: return answer return 0, "" + def screenshot(self, filename: str, /) -> None: + Image.new("RGB", (4, 4), (10, 20, 30)).save(self.out_dir / f"{filename}.png") + def succeed(self, *commands: str) -> str: output = "" for command in commands: @@ -42,5 +46,5 @@ class FakeMachine: @pytest.fixture -def machine() -> FakeMachine: - return FakeMachine() +def machine(tmp_path: Path) -> FakeMachine: + return FakeMachine(tmp_path) diff --git a/nix/tests/vm/lib/tests/test_kde.py b/nix/tests/vm/lib/tests/test_kde.py index e96752e7..bf149f6a 100644 --- a/nix/tests/vm/lib/tests/test_kde.py +++ b/nix/tests/vm/lib/tests/test_kde.py @@ -100,3 +100,38 @@ def test_active_is_the_last_line(machine: FakeMachine) -> None: machine.replies.clear() machine.reply("getactivewindow", output="") assert Kde(machine, "main").active() == "" + + +def test_session_attaches_to_the_users_bus_and_the_display_the_manager_reports( + machine: FakeMachine, +) -> None: + machine.reply("show-environment", output="PATH=/bin\nWAYLAND_DISPLAY=wayland-1\n") + machine.reply("[k]splashqml", status=1) + + kde = Kde.session(machine, timeout=0) + + assert "WAYLAND_DISPLAY=wayland-1" in kde.env + assert "DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus" in kde.env + + +def test_session_waits_for_the_splash_screen_to_go(machine: FakeMachine) -> None: + machine.reply("show-environment", output="WAYLAND_DISPLAY=wayland-1\n") + machine.reply("[k]splashqml", status=0) + + with pytest.raises(AssertionError, match="splash"): + Kde.session(machine, timeout=0) + + +def test_session_fails_when_the_shell_never_starts(machine: FakeMachine) -> None: + machine.reply("[p]lasmashell", status=1) + + with pytest.raises(AssertionError, match="plasmashell"): + Kde.session(machine, timeout=0) + + +def test_shot_returns_the_screenshot_as_rgb(machine: FakeMachine) -> None: + image = Kde(machine, "main").shot("desktop") + + assert image.size == (4, 4) + assert image.getpixel((0, 0)) == (10, 20, 30) + assert (machine.out_dir / "desktop.png").exists() diff --git a/nix/tests/vm/nodes/headless.nix b/nix/tests/vm/nodes/headless.nix index 72b237ee..04655b61 100644 --- a/nix/tests/vm/nodes/headless.nix +++ b/nix/tests/vm/nodes/headless.nix @@ -23,8 +23,8 @@ }; virtualisation = { - memorySize = 3072; - cores = 2; + memorySize = lib.mkDefault 3072; + cores = lib.mkDefault 2; # KWin wants a DRM render node, which needs a GPU. The test driver adds one on aarch64 only. qemu.options = lib.optionals (config.komorebi.vm.renderNode && pkgs.stdenv.hostPlatform.isx86_64) [ "-device virtio-gpu-pci" diff --git a/nix/tests/vm/nodes/session.nix b/nix/tests/vm/nodes/session.nix new file mode 100644 index 00000000..ebc68060 --- /dev/null +++ b/nix/tests/vm/nodes/session.nix @@ -0,0 +1,52 @@ +# A real Plasma Wayland session that logs in by itself, on a machine that can draw. Everything the +# headless node has is here too, so a test can still start a virtual KWin next to it. +# +# The choice of login manager is made here and nowhere else. nixpkgs' own `plasma6` test uses +# plasma-login-manager, so that is what this node follows; sddm with a Wayland greeter is the other +# one that has been seen to work, and replacing the first block below with +# `services.displayManager.sddm = { enable = true; wayland.enable = true; };` and +# `services.displayManager.defaultSession = "plasma";` switches to it. +{ pkgs, ... }: +{ + imports = [ ./headless.nix ]; + + # the one display this node has is the one screenshots are taken of + komorebi.vm.renderNode = false; + + services.xserver.enable = true; + services.displayManager = { + plasma-login-manager.enable = true; + autoLogin = { + enable = true; + user = "komorebi"; + }; + }; + + virtualisation = { + memorySize = 4096; + cores = 4; + }; + + # An idle lock screen or a dimmed display changes what a screenshot shows, and a display that has + # gone to sleep gets no frame callbacks from KWin, so clients stop answering resizes. + environment.etc."xdg/kscreenlockerrc".text = '' + [Daemon] + Autolock=false + LockOnResume=false + ''; + environment.etc."xdg/powerdevilrc".text = '' + [AC][Display] + DimDisplayWhenIdle=false + TurnOffDisplayWhenIdle=false + + [AC][SuspendAndShutdown] + AutoSuspendAction=0 + ''; + + environment.systemPackages = [ pkgs.kdePackages.konsole ]; + + # Nothing adds a display device here (see komorebi.vm.renderNode above). The test driver gives + # every aarch64 guest a virtio-gpu, and an x86_64 guest has the default VGA; screenshots are taken + # of that one, and a second device would be a second head that KWin draws on and the screenshot + # never shows. +} diff --git a/nix/tests/vm/suites/render-smoke/default.nix b/nix/tests/vm/suites/render-smoke/default.nix new file mode 100644 index 00000000..743bab13 --- /dev/null +++ b/nix/tests/vm/suites/render-smoke/default.nix @@ -0,0 +1,5 @@ +{ + tier = "slow"; + kind = "session"; + timeoutMinutes = 10; +} diff --git a/nix/tests/vm/suites/render-smoke/test.py b/nix/tests/vm/suites/render-smoke/test.py new file mode 100644 index 00000000..77b0e621 --- /dev/null +++ b/nix/tests/vm/suites/render-smoke/test.py @@ -0,0 +1,44 @@ +# A Plasma session draws a desktop in the test machine, so that every test after this one can trust +# a screenshot. KSplash has thousands of colors on it too, so "not blank" is not the check: the +# splash has to be gone and a window has to be painted on the desktop. +import time + +from komorebi_vm import Checks, Kde + +start_all() +started = time.monotonic() +machine.wait_for_unit("multi-user.target") + +checks = Checks() + +kde = Kde.session(machine, scale=SCALE) +print(f"the desktop is up after {time.monotonic() - started:.0f}s") + + +def konsole() -> str: + return kde.run("kdotool search --class konsole | head -1")[1].strip() + + +kde.spawn("konsole") +checks.check("a window appears", kde.wait_for(lambda: konsole() != "", timeout=60)) +rect = kde.rect(konsole()) +checks.check("the window has a size", rect.w > 0 and rect.h > 0) + + +def painted() -> bool: + image = kde.shot("desktop") + center = image.getpixel((rect.x + rect.w // 2, rect.y + rect.h // 2)) + assert isinstance(center, tuple) + # the terminal's background is dark; the wallpaper behind it is not + return sum(center) < 3 * 90 + + +checks.check("the window is painted on the screen", kde.wait_for(painted, timeout=60)) + +image = kde.shot("desktop") +colors = image.getcolors(maxcolors=image.width * image.height) +assert colors is not None +print(f"the screenshot is {image.size[0]}x{image.size[1]} with {len(colors)} colors") +checks.check("the desktop behind it is drawn", len(colors) > 5000) + +checks.finish()