How Omarchy Performs Acceptance Tests and Visual Verification: A Complete Guide

Omarchy validates every code change through a two-layer quality gate: automated graphical acceptance tests running inside disposable VMs, followed by manual visual verification using built-in screenshot and screen-recording tools.

Omarchy's testing strategy combines automated functional validation with human visual inspection to ensure both correctness and pixel-perfect UI fidelity. This article examines how the basecamp/omarchy repository implements acceptance testing and visual verification, drawing directly from the source code and documentation.

---

Graphical Acceptance Test Architecture

Omarchy's acceptance suite exercises a real desktop environment inside a temporary virtual machine. This validates session health, shell surfaces, panels, keyboard navigation, representative applications, and system-setup flows—far beyond what unit tests can cover.

Test Organization and Location

Acceptance test scripts reside in test/acceptance.d/ with a shared helper library:

Path	Purpose
test/acceptance.d/base-test.sh	Shared helper functions imported by all test scripts
test/acceptance.d/*-test.sh	Individual test implementations (e.g., panel-test.sh, menu-test.sh)
test/acceptance/	Harness that launches VMs, runs scripts, and aggregates results

According to the Acceptance-Tests guide in agents/skills/acceptance-tests.md, this structure separates test logic from orchestration concerns.

VM-Based Execution Model

Each acceptance test run follows a strict lifecycle:

1. Spin-up – Launch a temporary VM using the sibling omarchy-iso repository
2. Sync and run – The omarchy-iso-test command boots the ISO, synchronizes the current Omarchy checkout, and executes each *-test.sh script
3. Visual capture – Every step produces either success-<step>.png or failure-<step>.png
4. Artifact collection – Screenshots and logs aggregate under the ISO harness's timestamped test-runs/ directory

This VM isolation guarantees zero side effects on the developer's machine. The suite automatically restores modified user state, closes applications it opened, and records every visually distinct state.

Acceptance Test Commands

For UI-only changes (fast path with reusable base VM):

cd ../omarchy-iso
./bin/omarchy-iso-test release/<iso>.iso \
  --reuse-base --sync-omarchy ../omarchy --no-preview

For changes affecting binaries, configs, or shell code (full rebuild):

cd ../omarchy-iso
./bin/omarchy-iso-make --no-boot-offer --local-source ../omarchy ../omarchy-pkgs
./bin/omarchy-iso-test release/<generated-iso>.iso --no-preview

The --reuse-base flag dramatically speeds iteration when only UI code changes, while --no-preview runs headlessly for CI environments.

---

Visual Verification Workflow

Automated screenshots catch functional regressions, but manual visual verification ensures UI styling, layout, animations, panels, menus, notifications, and screen-recording flows render correctly. The Visual-Verification guide in agents/skills/visual-verification.md documents this process.

Four-Step Verification Process

1. Capture baseline – Record the current state before changes
2. Apply change – Trigger the UI modification (reload panel, toggle menu, etc.)
3. Capture candidate – Record the resulting state
4. Compare visually – Inspect for clipping, overlap, stale state, focus issues, and regressions

Screenshot and Screen-Recording Commands

# Full-screen screenshot with automatic save

omarchy capture screenshot fullscreen save

# Interactive region selection

omarchy screenshot

# Record full-screen video for animation verification

omarchy screenrecord --fullscreen

# ... exercise the changed behavior ...

omarchy screenrecord --stop-recording

Screenshots save automatically to ~/Pictures/omarchy-<timestamp>.png. Recordings produce short MP4 files ideal for frame-by-frame animation review.

Keyboard Automation with wtype

For repeatable UI flows requiring keyboard interaction, wtype simulates key presses without manual input:

# Example: navigate right, then confirm

wtype -k Right -k Return

This enables scripted visual verification—automated navigation with human inspection of the resulting screenshots.

---

Testing Layer Comparison

Layer	Execution Context	Primary Commands	Output Artifacts
Acceptance Tests	Disposable VM via omarchy-iso	omarchy-iso-test, omarchy-iso-make, test/acceptance.d/*-test.sh	success-*.png, failure-*.png, logs in test-runs/
Visual Verification	Live Omarchy session	omarchy capture screenshot, omarchy screenrecord, wtype	PNG screenshots, MP4 recordings

The acceptance suite guarantees functional correctness across the full desktop stack. Visual verification ensures pixel-perfect UI fidelity after each change. Neither substitutes for the other.

---

Complete Verification Example

# ---- AUTOMATED ACCEPTANCE (UI-only change) ----

cd ../omarchy-iso
./bin/omarchy-iso-test release/2024.08.iso \
  --reuse-base --sync-omarchy ../omarchy --no-preview

# Results: test-runs/<timestamp>/ contains all success/failure PNGs and logs

# ---- MANUAL VISUAL VERIFICATION (new panel layout) ----

# 1. Baseline capture

omarchy capture screenshot fullscreen save

# 2. Trigger change

omarchy restart-panel my-panel

# 3. Candidate capture

omarchy capture screenshot fullscreen save

# 4. Inspect both images side-by-side for regressions

---

Key Documentation and Source Files

File	Description
agents/skills/acceptance-tests.md	Complete guide to VM-based acceptance testing
agents/skills/visual-verification.md	Manual UI verification procedures
test/acceptance.d/base-test.sh	Shared test helper functions
test/acceptance.d/*-test.sh	Individual acceptance test implementations
test/acceptance/	VM harness and result aggregation
docs/testing.md	High-level testing strategy overview

These resources define how Omarchy validates both functional behavior and visual integrity before merge.

---

Summary

• Acceptance tests run in disposable VMs via omarchy-iso, executing test/acceptance.d/*-test.sh scripts and capturing success-*.png/failure-*.png artifacts
• Visual verification requires manual inspection using omarchy capture screenshot fullscreen save, omarchy screenrecord, and optional wtype keyboard automation
• UI-only changes use --reuse-base for fast iteration; binary/config changes require full ISO rebuild via omarchy-iso-make
• Complete isolation prevents test pollution—every run starts fresh, restores state, and closes applications automatically

---

Frequently Asked Questions

What triggers a full ISO rebuild versus reusing the base VM?

Use --reuse-base for UI-only changes (HTML, CSS, JavaScript, shell scripts). Run omarchy-iso-make for changes affecting binaries, system configurations, or compiled components that alter the base system image.

Where do acceptance test screenshots get stored?

The omarchy-iso-test harness collects all PNGs and logs under test-runs/<timestamp>/ within the ISO repository. Each step produces either success-<step>.png or failure-<step>.png for immediate visual diagnosis.

Can visual verification be fully automated?

No. While wtype enables scripted navigation and omarchy capture automates screenshot collection, human inspection remains required for detecting visual regressions like clipping, misalignment, focus indicators, and animation timing issues that pixel-comparison tools miss.

How do I run acceptance tests without a GUI?

Add the --no-preview flag to omarchy-iso-test. This runs the VM headlessly while still capturing screenshots and logs for later review—ideal for CI/CD pipelines and remote servers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}