Nomarchy/docs/TESTING.md

Testing Nomarchy

How to verify changes actually work — from cheap eval checks to booting the full desktop. Adapted from the previous Nomarchy iteration's agent docs.

The honesty rule (for humans and AI agents alike): for Waybar, Hyprland, or any visual change, the only reliable check is booting the live ISO. If you can't boot it (e.g. you're on macOS or have no KVM), say so rather than claiming success. "All Nix files parse" is not "the bar renders."

1. Cheap checks (always do these first)

nix flake check --no-build          # full module-system evaluation, no builds
nix-instantiate --parse <file>      # syntax-only, works even on macOS
python3 -m py_compile pkgs/nomarchy-theme-sync/nomarchy-theme-sync.py

nix flake check needs a Linux machine (or a Linux builder) since all outputs are x86_64-linux. It catches type errors, missing options, and bad merges — most breakage stops here. It also evaluates the downstream template through lib.mkFlake (including a real nixos-hardware profile), so template/wrapper drift fails fast too.

2. Build and boot the live ISO

# Build + boot in QEMU, one command:
tools/test-live-iso.sh

# Or by hand:
nix build .#nixosConfigurations.nomarchy-live.config.system.build.isoImage
# → result/iso/*.iso  — dd it to a USB stick for real hardware

The script prefers UEFI (OVMF) with a legacy-BIOS fallback, uses KVM when /dev/kvm is readable, and boots with virtio-vga-gl + gl=on — Hyprland and Ghostty need real OpenGL in the guest; without it the session may not start.

What the live environment gives you

• Auto-login as nomarchy (no password, passwordless sudo), greetd → Hyprland via initial_session; logging out lands on tuigreet.
• The flake is seeded writable at ~/.nomarchy (from the read-only /etc/nomarchy copy) — $NOMARCHY_PATH already points there.
• Locked flake inputs are pinned into the ISO store, so home-manager switch works without a network.

3. Verification checklist

Work through these in order; each one exercises a different layer.

#	Check	Verifies
1	Boots to Hyprland with Tokyo Night wallpaper visible	greetd autologin, awww, session start
2	Waybar shows at top, themed (blue accent on dark)	HM waybar module, palette baking
3	SUPER+Return opens Ghostty with Tokyo Night colors	terminal default, ANSI palette
4	btop in the terminal is themed	per-theme asset baking
5	nomarchy-theme-sync list prints 21 presets	package, baked themes dir
6	nomarchy-theme-sync apply gruvbox → state written, home-manager switch runs, desktop re-themes, wallpaper changes	the whole engine: state write, pure eval, HM rebuild, wallpaper hook
7	SUPER+SHIFT+T cycles wallpapers instantly (try tokyo-night: 4 of them)	the runtime wallpaper path
8	nomarchy-theme-sync apply summer-night → after the switch the bar has its own identity (light bar, different styling)	whole-swap waybar.css assets
9	Open a GTK app — dark theme matching the palette	Stylix layer
10	home-manager generations lists one generation per theme change; activating an older one rolls the theme back	atomicity / rollback story

Items 6 and 8 are the big ones — they prove the all-Home-Manager theming model end to end.

4. Testing the installer

The installer has an unattended mode for exactly this. Boot the live ISO in QEMU with a second, blank disk attached (e.g. -drive file=target.img,if=virtio,format=raw on a 20 G image), then in the live terminal:

sudo NOMARCHY_UNATTENDED=1 NOMARCHY_DISK=/dev/vda \
     NOMARCHY_USERNAME=me NOMARCHY_PASSWORD=test \
     NOMARCHY_FINISH=poweroff nomarchy-install

Then boot the VM again from the target disk (drop -cdrom). The machine must reach the themed desktop on its own — greeter autostart, wallpaper, Waybar — and nomarchy-theme-sync apply <x> must work. For the offline claim, add restrict=on to the -netdev and re-run the whole flow: it must behave identically (requires an ISO built from a clean git tree, which is what bakes the rev into the installer).

5. VM-specific gotchas

• No KVM (e.g. nested without acceleration): everything works but home-manager switch will be painfully slow. Don't read slowness as breakage.
• Black screen / session exits: almost always missing guest GL. Use the script's qemu flags; on real hardware check journalctl -b -u greetd.
• Tiny resolution: the live config forces monitor = ,highres,auto,1; if QEMU still picks 1024×768, resize the window — Hyprland follows.
• First theme switch is the slowest: it evaluates the flake on a RAM disk. Subsequent switches reuse the eval cache.

6. When something fails

• Session/login problems: journalctl -b -u greetd, then journalctl --user -b.
• Theme switch failures: run nomarchy-theme-sync apply <x> from a terminal — the home-manager output streams there. The state file is written before the rebuild, so after fixing you can just re-run home-manager switch --flake ~/.nomarchy.
• Report results faithfully: what booted, what rendered, what you could not verify and why.