komorebi/docs/dev/e2e-to-unit.md

From e2e to unit: what the shared crates made testable natively

Paths (cutover stack): this document was written before the directories were renamed and keeps the paths of its time. Now: komorebi/ is komorebi-windows/, komorebi-for-kde/komorebi/ is komorebi-linux/, komorebi-for-mac/komorebi/ is komorebi-macos/, komorebi-for-kde/komorebi-hotkeys/ is komorebi-hotkeys/, komorebi-for-kde/nix/ and komorebi-for-mac/nix/ are nix/linux/ and nix/macos/, komorebi-for-kde/docs/ and komorebi-for-mac/docs/ are docs/linux/ and docs/macos/, schema*.json are in schemas/{windows,linux,macos}/, and every package is at version 0.2.0 (the 0.1.x numbers below are history).

Base: wip-cand5 plus the revisions that add the tests named here. Written 2026-10-31.

Before the shared crates, the Windows daemon could only be tested through a Windows guest (its crate does not compile on Linux) and the macOS daemon through nothing. Now Windows, KDE and macOS call the same komorebi-core (Container, Workspace, Monitor, update_shared and the platform hooks), komorebi-layouts, komorebi-scrolling, komorebi-settings, komorebi-protocol, komorebi-config, komorebi-transport and komorebic-core, so a native test of that code, on the stub platform (crates/komorebi-core/tests/common) or FakeBackend, protects all three. This document lists every e2e scenario, says whether that is now done, and ranks what is left.

What stays out of reach

The daemons' own process_command / process_event are per platform (Windows: Win32 types; macOS: Mac types), only the KDE one runs on FakeBackend. So a native test of "send this command, then the state is that" exists for KDE only; for Windows and macOS it holds as far as the command's work is done by shared Workspace/Monitor methods. Rule matching (should_act_individual) exists three times (Windows komorebi/src/window.rs:1178, KDE window.rs:661, macOS window.rs:1864), not in komorebi-config. Every row below says which of these a test reaches.

Classes

• A: already covered natively. B: coverable natively with the shared API, not yet. C: needs a real OS (compositor, Win32, timing, pointer, rendering, several processes).
• "Now" marks what this work added (revisions on wip-u-e2e2unit).
• Value: share of the gate it could stand in for. Effort S/M/L.
• Check counts: dynamic numbers where the gate printed them (layouts 111, commands 265), else the number of check call sites in the scenario file (static, lower than the runs).

Windows-origin scenarios (first: only e2e-testable on Windows, now native)

Scenario (checks)	Behaviour	Class	Native test (cited, or proposed)	Eff.	Value
layouts (111)	8 layouts x counts: each window where the layout says, inside the work area, not over another	A now (arithmetic); C (OS frame equals tile)	crates/komorebi-core/tests/e2e_layouts.rs every_layout_tiles_every_container_inside_the_work_area_and_off_the_others (shared update_shared), komorebi-layouts/tests/layouts_everywhere.rs (calculate, 3 areas, 1-12 windows)	S	high: 3 min, can shrink to 1 layout smoke
flipping (3)	flip-layout mirrors every place, flip back restores	A now	e2e_layouts.rs a_flip_mirrors_the_tiles_of_the_workspace_as_a_set; layouts_everywhere.rs flips	S	med
layout_flip (10)	layout_flip config mirrors from the start; flip-layout toggles; per workspace	A now for the maths; B for config key to Workspace.layout_flip	same tests; proposed: komorebi-settings or core test that loads a workspace config with layout_flip and checks the field	S	med
padding (7)	workspace/container padding moves and shrinks tiles, setting back restores	A now	e2e_layouts.rs the_workspace_padding_moves_the_tiles_in...; existing update_shared.rs the_padding_of_the_workspace_wins_over_the_monitors_even_when_it_is_zero	S	med
tiling (6), closing (5), minimizing (4), floating (7)	windows share the area; a leaving container (closed/minimized/floated) gives the others room	A now (room) + A (floating/removal): workspace_layers.rs floating_* , workspace_containers.rs removing_*; C: the OS event	e2e_layouts.rs removing_a_container_gives_the_others_more_room	S	med
stacks (23)	stack/cycle-stack/unstack: one tile per stack, window in view has focus, others away	A: core workspace_containers.rs stacking_*, unstacking_*, container_behaviour.rs hide/restore; now e2e_layouts.rs a_stack_is_one_tile. B: cycle-stack has no shared method (daemon-side)	S	med (23 checks, 3 min)
tiling_off (6)	toggle-tiling leaves windows, tiling again tiles	A now	e2e_layouts.rs a_workspace_with_tiling_off_places_nothing...; update_shared.rs a_workspace_that_is_not_tiling_prunes_and_places_nothing	S	low
monocle (12)	monocle fills area, others away, toggle back; focus behaviours	A: workspace_layers.rs toggling_monocle_*, reintegrating_*, cycling_monocle_*; update_shared.rs a_monocle_container_gets_the_work_area_less_every_padding. Focus behaviour is daemon-side (B, needs seam)	-	-	med
maximizing (29)	toggle-maximize, unmaximize on float, monocle wins	A: workspace_layers.rs floating_the_maximized_window_*, update_shared.rs the_monocle_container_wins_over_a_maximized_window; user-maximize event C	-	-	med
promoting (4), moving (4), focus (7)	promote first tile, swap/cycle-move, focus order	A: workspace_containers.rs promoting_*, swapping_containers_*, cycling_wraps_*, directions_follow_the_layout_and_the_flip; focus OS agreement C	-	-	low
workspaces (8), workspace_moves (8)	send/move/focus workspace, last-workspace	A: monitor_workspaces.rs (focus, last focused, ensure, remove); the OS hide/show is C	-	-	med
commands (265, 7.6 min)	every komorebic command leaves the daemon alive, answers state, manages every window	A now for command line (crates/komorebic-core/tests/e2e_sweep.rs: every SWEEP/PRINTED line is a Windows command; macOS lacks exactly 8) and for the KDE model (komorebi-linux/tests/command_sweep.rs, about 185 messages, 0.2 s); B: same sweep for the Windows and macOS daemons (needs seam, below); C: stall-family (daemon busy 8 s), socket answering	S done / L for Win+mac	highest: biggest, flakiest scenario
unknown_monitor (12)	a window sent to a monitor that does not exist stays managed	B: shared Monitor/Workspace::add_container errors are covered (monitor_workspaces.rs adding_a_container_to_a_workspace_that_is_not_there_is_an_error); the daemon handler is per platform: needs seam	M	med (known flaky marker)
rules (12), rules_class (5), rules_exe (5), manage_rules (4), title_rule (5), startup_rules (5)	which window a rule catches (kind, strategy, composite, last wins, manage over ignore); the workspace it goes to	A now for matching, once for all three daemons: crates/komorebi-config/tests/rule_matching.rs (16 tests, KDE/macOS and Windows input shapes; the matching moved to komorebi_config::rules, see docs/dev/rule-matching.md); KDE keeps the manage-rule rescue test. Workspace of a rule: A in core: workspace_containers.rs initial_placement_rules_choose_where_a_new_window_goes. When-evaluated (open vs rename), hide/show: C	M to move the function into komorebi-config and test once for three daemons (recommended seam)	high
state_fidelity (5)	state names title/exe/class/path as opened	A: state_roundtrip.rs (kfw/kfde fixtures, the_fixtures_are_the_ones_the_e2e_library_has, a_windows_tiled_state_is_written_as_it_was_read); what the OS reports C	-	-	low
queries (3)	komorebic query X answers from the state, resize save/load round trip	B: state answers per query are StateQuery handling in the daemon; resize round trip needs process_command (KDE: resize.rs sizes_saved_to_a_file_are_loaded_back_from_it A)	M	low
config_reload (8)	file change reloads names, layout, rules	A for the merge/reset semantics: crates/komorebi-settings/tests/reload.rs (a_reload_merges_what_the_file_gives_and_resets_what_it_resets), src/handle.rs; C: the file watch and the reload message dropped while the lock is held (the NEW failing check in gate5 is that mechanism)	-	-	med
placement (1 x 5 cases)	initial_window_placement_rules first/last/Nth	A: workspace_containers.rs a_one_based_placement_index_is_zero_based_and_out_of_range_falls_back_after_the_focused, initial_placement_rules_choose_where_a_new_window_goes. The known Windows failure (number 2) is a daemon event-path matter	-	-	low
scrolling (46)	strip, edges, columns, two monitors	A: komorebi-scrolling/tests (rules 80, tiles 40, heights 20, pan 16) and update_shared.rs a_scrolling_workspace_*; the resting window at an edge on the OS is C	-	-	med
resize_commands (7), resize (26)	resize-axis widens and gives back; edge drag	A: resize_constraints.rs, update_shared.rs the_resize_constraints_are_enforced_before_the_layout_is_calculated; B (S): DefaultLayout::resize increase then decrease is the identity (no test in komorebi-layouts); the pointer drag and client rounding C	S	med
pausing (4)	paused daemon ignores new windows	A: komorebi-transport/src/pause.rs (the message filter); the event filter is per daemon (B needs seam)	-	-	low
hotplug (11), monitors (13)	unplug/plug a display, windows move, send-to-monitor	A for the model in monitor_workspaces.rs; the reconcile is per platform (Windows monitor_reconciliator, macOS own): B needs seam; the display itself C	L	med
lifecycle (7), lifecycle_hidden (13), locking (7), handover (6), fullscreen (6), display_change (4), focus_follows_mouse (7)	stop/start restores windows, screen lock, minimize/unmanage/manage, fullscreen, mode change, pointer focus	A for hide/restore: container_behaviour.rs restoring_*, workspace_layers.rs hiding_a_workspace_*; the process, session, OS events and pointer are C	-	-	-
Windows extras: bar (21), windows_padding, cloaking, config_file, tracking, second_display, display_change	bar process and window, 7 px border, cloaking, file watch, system focus setting, QXL display	bar schema: A (crates/komorebi-bar-core/tests/schema_oracle.rs); rest C	-	-	-

macOS-origin behaviour: what the shared tests give besides the e2e

The shared e2e scenarios run on macOS in a Tart guest, by hand on a Mac (nix run .#e2e-macos, e2e/platforms/tart_macos/README.md; not in CI). What a macOS guest cannot do (a second display, a pointer, a lock screen) is still never e2e-tested. The shared-crate tests that exist protect its code path as far as the hooks do: state_roundtrip.rs a_macos_shaped_state_is_written_as_it_was_read_with_the_corner_last, a_macos_state_cannot_be_read_without_its_corner, the StubWindow that is Clone but not Copy, and now e2e_layouts.rs (the tiles every macOS tiling goes through). Proposed B tests, platform dependent and meant for the Mini: the hide-spot corner per monitor (hide_spot hook is StubState { spot }) with hide/restore on a stack, and komorebic-core macOS command set (e2e_sweep.rs pins which sweep commands macOS lacks).

KDE VM suites (33 suites with a test.py)

All of them need a headless or Plasma KWin: C. The model parts of them are already native through the KDE tests (komorebi-linux/tests, formerly komorebi-for-kde/komorebi/tests, about 880): core-e2e and hotplug, placement, workspace-rules, scrolling, stacks, user-maximize, commands, core-lock, focus-follows-mouse, wallpaper have a native model twin; kwin*, check, module, keys-*, look, features, rdp, render-smoke, latency, client-geometry, drag-resize, live-resize, lock-sleep, run-kde, restart-survival, kwin-restart are the compositor, the session, keys, pixels or timing (C). The commands suite's sweep now has a native twin (command_sweep.rs), so the suite can run a shorter sweep.

Counts

Scenario rows: Windows/shared 43 scenarios + 7 Windows extras = 50. Classified by what is left to do after this work: A (fully native for the shared logic, e2e only needed as a smoke) 22; A now (added by this work) 9 of those (layouts, flipping, layout_flip, padding, tiling, closing, minimizing, floating, tiling_off, stacks in part); B open 7 (commands for Windows/macOS daemons, unknown_monitor, queries, hotplug reconcile, pausing event path, rules for Windows/macOS copies, resize identity); C only 21 (lifecycle*, locking, display*, bar, extras, pointer, fullscreen, wallpaper rendering and the KDE suites). KDE VM: 0 A fully, 33 C (about 10 with a native model twin).

Time saved

The Windows gate is about 2.3 min per scenario for 35 scenarios (about 80 min), the KDE suites 15 x 1-13 min. Honest estimate:

• Today (what this work added): the arithmetic of layouts, flipping, layout_flip, padding, tiling and the room checks is native. A guest still has to show the daemon hands the tiles to the OS, so these scenarios shrink to one smoke each, or are merged into tiling: layouts (111 checks, about 3 min) to one layout and 3 windows saves about 2 min; flipping, layout_flip, padding, tiling_off, minimizing, closing, floating merged in tiling save about 7 x 2 = 14 min. About 16 min of 80 (20%) on Windows, plus commands: the 7.6 min scenario keeps 20 commands as a smoke and loses about 5 min once the Windows daemon is reachable by the sweep.
• If the B items existed (daemon model reachable natively for Windows and macOS, rule matching in one shared function, config key tests): another 12 scenarios (rules, rules_class, rules_exe, manage_rules, title_rule, startup_rules, state_fidelity, queries, config_reload, placement, workspaces, workspace_moves) become one smoke each: about 25 min. Total about 45 min of the 80 min gate (55%), and almost all the flaky checks (stall-family markers sit in commands, config_reload, resize, maximizing, floating, which are the ones with timing).
• KDE VM: the model twins let commands, placement, workspace-rules, hotplug, scrolling run with fewer cases; this is about 20-30 VM minutes of the 15 suites, not measured.

Not saved: boot and golden image (3 s from a state), the C scenarios.

Seams that are missing (report only, nothing added)

1. The daemon's process_command and process_event are per platform. A model-level CommandHandler<P> in komorebi-core (taking SocketMessage, mutating Monitor/Workspace, calling hooks) would let one sweep (command_sweep.rs) protect Windows and macOS: commands, unknown_monitor, queries, pausing, handover, moving, focus, monocle focus behaviour.
2. should_act / should_act_individual three times: move into komorebi-config (it already has MatchingRule, MatchingStrategy): one test file would replace the rule matching logic of rules, rules_class, rules_exe, manage_rules, title_rule, startup_rules for all daemons.
3. Monitor reconciliation (Windows monitor_reconciliator, macOS own, KDE reconcile.rs) is not in komorebi-core: a pure reconcile(old: &[MonitorSnapshot], new: &[MonitorSnapshot]) -> Plan would make hotplug and unknown_monitor native.
4. cycle-stack, cycle-stack-index, focus-stack-window are daemon methods, not Container methods; moving them into komorebi-core::Container would make the stacks scenario native beyond the existing stack/unstack tests.
5. Event filtering while paused (allowed_while_paused is shared, the event path is not).

Tests added, with the e2e check each mirrors

Test file	Tests	Mirrors
komorebi-layouts/tests/layouts_everywhere.rs	8	layouts, flipping, layout_flip, padding, tiling, closing
crates/komorebi-core/tests/e2e_layouts.rs	6	layouts, flipping, layout_flip, padding, closing, minimizing, floating, stacks, tiling, tiling_off
komorebi-linux/tests/rule_matching.rs	13	rules, rules_class, rules_exe, manage_rules, title_rule
komorebi-linux/tests/command_sweep.rs	1 (185 messages)	commands
crates/komorebic-core/tests/e2e_sweep.rs	3	commands

Each test says what stays e2e: the OS frame equals the tile, borders, event timing, the daemon's own hooks.