komorebi/docs/dev/suite-ledger.md

Shared scenarios and platform extras: what moved where

A suite runs shared scenarios (komorebi_vm.core.scenarios) and what only its platform can check (komorebi_vm.platforms.kde.extras), with the checks labelled [shared] and [kde]. This is the ledger of the checks a suite stopped making because a shared check makes them, so that none is dropped without a replacement. A check that only KDE can make stays, as an extra.

hotplug

The suite had its own sections, then ran the shared scenario "the same, through the neutral platform". The sections the shared scenario repeats are gone; the rest are kde_hotplug steps.

Was (section)	Now
1, the daemon answers with both monitors; three windows on the left; the monitor's size; tiled	extra setup
2, the scale of the left output changes and returns	extra scale
3, move-to-monitor 1: containers, KWin's OutputChange, tiled on the right	extra sent_by_the_daemon
4, the user moves a window to the right output	extra sent_by_the_user
5, one monitor after the unplug	shared "after a display is unplugged the daemon has one monitor fewer"
5, all three windows on the left monitor	shared "... the daemon still manages every window", and "every window is on the displays that are left"
5, tiled inside the screen that is left, not on each other	shared "... tiled and clear of each other"
5, the daemon alive, its focus KWin's	extra after
6, two monitors again	shared "after a display is plugged in the daemon has a monitor for it again"
6, still three windows	shared "... still manages every window"
6, each window somewhere it can be seen	shared "... each where it can be seen"
7, a window moved to the other output again is followed	extra after
8, the daemon runs and answers	extra after

Not kept: that the daemon's container count on the left monitor is 3 after the unplug. The shared scenario checks the managed count and where the windows are, not the count of containers per monitor. The windows are where the layout puts them, which is what that count stood for.

The suite goes from 25 checks plus the shared ones to 28, which is the shared 11 and 17 of KDE's.

commands

The suite had its own layout loop (section 2) and then called the shared layouts, sweep and prints. Nothing the shared scenarios check was removed except as listed; the rest moved to kde_commands, which reads KWin and the daemon's log.

Was (section)	Now
1, the daemon answers with both outputs; five windows	extra setup
2, every layout with five windows: inside the outputs, apart, healthy	shared layouts; the extra repeats it at five windows, see below
2, every layout with three, two and one windows	extra layouts_by_count
2, each window where the daemon last asked KWin for it	extra layouts_by_count (KDE only: reads the daemon's log)
3, the layouts and the sweep of commands	shared layouts and sweep
3, replace-configuration made the window manager from the file	extra replace_configuration
3b, minimize, unmanage, manage	extra handover
3c, a title rule decides when the window has its title	extra title_rule
4, every command that only prints	shared prints
4, komorebic query ..., quick-save-resize, save-resize	extra queries (candidates for the shared list)
5, every window is where the daemon last asked; a clean stop	extra at_the_end

The extra's layout loop still goes through five windows, for the daemon's log check at that count; it states its overlap verdict for five windows too, so that one is made twice. Dropping it from the extra would lose the five-window where asked check, which is KDE's.

drag-resize

The suite's own cases are all KDE's: the pointer put to the pixel, and eight drags of edges and corners checked against frames, tiles and neighbors. None of them is removed; they moved to kde_drag_resize as pointer_is_exact and edge_cases, and the suite calls the shared resize and focus_follows_mouse after them, as before. The shared resize makes one drag of one edge, which the extra's win1:right:... cases also make: that is a repeat by design, because the extra reads the daemon's tiles and the frames together, and the shared one reads only the system.

One run of the suite failed win2:left:-240,0 ("frame R moved -96 but was not dragged": the terminal's frame four cells short of an unchanged tile) and the next passed; not seen again.

core-e2e

The suite had sections 1 to 11 of its own, written against KWin and the daemon's log, and then ran the shared scenarios in section 12 through the neutral platform. Sections 2 to 8 made, with KDE's tools, the checks the shared tiling, focus, moving, monocle, minimizing and closing make. They are gone; what only KDE can read stayed, as kde_core steps after the shared one.

Was (section)	Now
1, the script is loaded into KWin, which runs it; the daemon answers	extra start
2, every window is where the daemon asked for it	extra windows_where_asked, after each shared step that moves windows
2, inside the screen; windows apart; none takes the full width; the daemon manages the three	shared tiling ("where the layout says", "do not overlap", "share the work area")
2, KWin and the daemon agree on the focus, by the daemon's log	extra focus_agrees_with_the_log
2, the daemon's state focuses the window KWin does	shared tiling and focus
3, 4, the focus by hand, focus right/left, cycle-focus	shared focus
4, moving the focus moved no window	extra windows_where_asked after focus
5, move right, cycle-move previous, the focus kept	shared moving; extra windows_where_asked after it
6, monocle fills the work area, the state says so, back on the tile	shared monocle
6, monocle focus behaviour cycle	extra monocle_focus_behaviour (a candidate for the shared scenario)
7, minimize and restore	shared minimizing; extra windows_where_asked after it
8, close, the others share the screen, the daemon manages the rest	shared closing
8, KWin carried out every command	extra bridge_did_everything
9, a clean stop undoes what a monocle did	extra parking (opens two windows of its own)
10, a crash with a monocle on leaves nothing stuck	extra parking
11, KWin restarts under the daemon	extra kwin_restart (the kwin-restart suite also covers it)
13, komorebic stop: the socket, the script, the window stays	extra stopped

Changed on purpose: the lifecycle sections run after the shared scenarios, on windows of their own, so that the stop and the crash no longer depend on windows a shared scenario left behind. The daemon's frame log is read after four shared steps, not after every one.

Also learned while moving it:

• KWin carried out every command was one check after section 8, over a log of three windows' worth of commands. After every shared step, over the whole corpus, the bridge logs could not do for a geo that targets a window a scenario closed a moment later. That is a race, not a failure, so the check now counts only a command for a window that is still open, and runs after each shared step so that a real failure names its scenario. A failure there with the window alive is a finding.
• After a daemon restart the daemon's focused window can differ from the one KWin has active, and activating a window KWin already has active sends no event. parking activates another window first. Whether the daemon should pick up KWin's active window at start is not decided here.

workspace-rules

The suite made, with KDE's tools, the checks that the shared rules and startup_rules make. It keeps the part that is KWin's: a workspace is a virtual desktop.

Was (section)	Now
1, an initial rule sends a window to workspace 1; it is put away	shared rules
1, it is on the parking desktop while desktop 1 shows; on desktop 2 once shown, not parked; tiled where asked	extra desktops
1, the other window is where it opened (desktop 1)	extra desktops
2, the user takes the window back; an initial rule does not send it again	shared rules
2, a rule by the name of a workspace (chat) sends a window; desktop 3 when shown	extra named_rule (the shared scenarios use indexes)
2, a new window is an event that applies the rules again	extra named_rule (a candidate for the shared rules)
2, enforce-workspace-rules sends the initial rule's window again	shared rules
3, the rules are cleared; a window that opens stays on the workspace in front	shared rules; extra cleared (the daemon's global state has no rule; desktop of the new window)
4, a komorebi.json rule, with a window open before the daemon	shared startup_rules

The extras open windows of their own and close them, so that the shared scenarios start from a daemon with none.

placement

Was (section)	Now
1, no rules: after the one in focus	shared placement
2, every window to the primary tile	shared placement
3, by the number of the place, as a number and as text	shared placement
4, by the app id (Class), by the title, and after the one in focus	extra by_app_id (the shared scenario matches by title only; a candidate for it)
5, Exe foot.exe matches foot	extra by_program (KDE: no .exe on this port)

workspace-switch

Nearly everything this suite checks is KWin's: a workspace is a virtual desktop. The shared workspaces and workspace_moves scenarios, which core-e2e runs, check that send-to-workspace and focus-workspace put windows away and back with the focus agreed; here the same commands are read on KWin's desktops. The suite is the extra workspace_switch.run; its one dropped check, "the daemon answers komorebic", is what platform.start_komorebi() waits for. The shared scenario is not called from this suite, because it starts from windows on the first workspace and this suite's own start state is a daemon that has not yet turned on KWin's per-output desktops.

scrolling

The shared scrolling scenario (run by core-e2e) puts each window in view in turn. This suite is about the windows that are not in view: where KWin keeps the columns that scroll off the screen, and that the strip follows the focus. All of it is KWin's; it is the extra scrolling.run, with no check dropped.

stacks

Ported whole as the extra stacks.run: all 54 checks. It reads the parking desktop and KWin's desktops (kdotool), which the shared stacks and monocle scenarios do not. It still repeats, on KWin's side, some of what they check: that cycling the stack shows the other window and puts the first away, focus by place in the stack, and a monocle over a stack (sections 3, 4 and 8). The repeats read a different oracle (the parking desktop, not the operating system's hidden), so they are kept for now; slimming them needs the shared scenarios to report what they leave to be read, which is the stage hook that was left out. Sections 10 and 11 (a crash, a clean stop) are the stack-all form of core-e2e's parking.

kwin-restart

Ported whole as the extra kwin_restart.run (two restarts, 19 checks as run). core-e2e had a section that restarted KWin once with the same four checks; it is gone, and core-e2e now only opens the window afterwards that its last section looks for.

The KDE-only suites

Moved as they were into komorebi_vm.platforms.kde.extras, one module per suite (kwin, kwin_events, kwin_contract, client_geometry, module, restart_survival, user_maximize, check, features, look, render_smoke, wallpaper, rdp, latency, run_kde, live_resize, focus_follows_mouse, lock_sleep, keys_engine, keys_static, keys_corpus). Each module has run(machine, checks, scale), which is the body of the old script; the suite script only starts the machine and calls run_suite(checks, platform_only("kde", ...)). The three keys-* suites share one script, keys-corpus.py, as before. No check was dropped and none was added; these have no shared scenario to repeat. What each makes on a real KDE, run once after the move:

Suite	Passed
kwin	8
kwin-events	22
kwin-contract	15
client-geometry	26
user-maximize	14
check	23
latency	5 (once 4 and 1 failed: a p95 of 173 ms against 150 while the machine was loaded)
render-smoke	4
rdp	6
keys-static, keys-skhd, keys-whkd, keys-sxhkd	6, 4, 4, 4
lock-sleep	11
focus-follows-mouse	11
restart-survival	17
module	33
live-resize	7
look	40
wallpaper	22
features	30
keys-engine	34
run-kde	22

The moved modules have long lines the suite scripts were never linted for, so pyproject.toml lets them keep them (E501 per file); new extras do not get that.