# How Omarchy Performs Acceptance Tests and Visual Verification: A Complete Guide > Learn how Omarchy uses automated graphical acceptance tests and manual visual verification with screenshots and recordings to ensure code quality. Discover Omarchy's two-layer quality gate. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: how-to-guide - Published: 2026-08-20 --- **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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/panel-test.sh), [`menu-test.sh`](https://github.com/basecamp/omarchy/blob/main/menu-test.sh)) | | `test/acceptance/` | Harness that launches VMs, runs scripts, and aggregates results | According to the [Acceptance-Tests guide](https://github.com/basecamp/omarchy/blob/quattro/agents/skills/acceptance-tests.md) in [`agents/skills/acceptance-tests.md`](https://github.com/basecamp/omarchy/blob/main/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-.png` or `failure-.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): ```bash cd ../omarchy-iso ./bin/omarchy-iso-test release/.iso \ --reuse-base --sync-omarchy ../omarchy --no-preview ``` **For changes affecting binaries, configs, or shell code** (full rebuild): ```bash cd ../omarchy-iso ./bin/omarchy-iso-make --no-boot-offer --local-source ../omarchy ../omarchy-pkgs ./bin/omarchy-iso-test release/.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](https://github.com/basecamp/omarchy/blob/quattro/agents/skills/visual-verification.md) in [`agents/skills/visual-verification.md`](https://github.com/basecamp/omarchy/blob/main/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 ```bash # 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-.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: ```bash # 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 ```bash # ---- 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// 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`](https://github.com/basecamp/omarchy/blob/main/agents/skills/acceptance-tests.md) | Complete guide to VM-based acceptance testing | | [`agents/skills/visual-verification.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/visual-verification.md) | Manual UI verification procedures | | [`test/acceptance.d/base-test.sh`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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//` within the ISO repository. Each step produces either `success-.png` or `failure-.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.