How the Omarchy Testing Suite Is Organized: CLI, Shell, and Acceptance Layers

Omarchy splits its testing suite into three distinct layers—test/cli for command-line interface validation, test/shell.d/ for environment and helper tests, and test/acceptance.d/ for graphical end-to-end verification—coordinated by top-level runner scripts.

The Omarchy testing suite uses a layered architecture to balance execution speed with comprehensive coverage. The repository organizes tests across three specific paths that handle CLI routing, shell environment logic, and full-stack UI validation according to the omacom/omarchy source code. This structure allows developers to run fast, deterministic checks locally while isolating heavy graphical regressions to disposable virtual machines.

The Three-Layer Test Architecture

Omarchy categorizes tests by scope and execution environment. Each layer lives under the top-level test/ directory and serves a distinct purpose in the development workflow.

CLI Tests in test/cli

The test/cli file is a single, self-contained Bash script that drives the CLI router test suite. It verifies that the omarchy command-line interface correctly parses sub-commands, emits help output, and validates command metadata.

This script executes sub-tests covering:

• Help and version flag handling
• Command routing logic
• Metadata validation via omarchy commands --check
• Theme helper sanity checks

Because it runs without external dependencies, the CLI test layer completes in seconds, providing immediate feedback on core interface logic.

Shell Tests in test/shell.d/

The test/shell.d/ directory contains isolated shell scripts that exercise the Quickshell environment, hardware-detection helpers, UI-related commands, and migration scripts. Each test file follows the *-test.sh naming convention and focuses on a specific behavior.

The ./test/shell runner orchestrates these tests by iterating over every *.sh file in the directory and sourcing the shared harness from test/shell.d/base-test.sh. Typical assertions validate tray icon creation, theme staging logic, and power-profile toggles.

For example, a hardware detection test might assert:

# test/shell.d/tray-test.sh excerpt

assert_file_exists "$XDG_RUNTIME_DIR/omarchy/tray.sock"
assert_command_output "omarchy tray status" "visible"

These tests run on the host without requiring a graphical session, offering medium-speed feedback on environment-specific logic.

Acceptance Tests in test/acceptance.d/

The test/acceptance.d/ directory houses graphical end-to-end tests executed inside a disposable VM. These scripts validate the full UI experience—menu rendering, widget interaction, and visual feedback—using a headless X server and the omarchy-visual-verification skill.

Because they launch the full Omarchy UI and capture screenshots for comparison, these tests are slower and intentionally separated from the quick unit-test run. An acceptance script typically:

1. Launches the Omarchy UI process
2. Simulates menu navigation sequences
3. Takes screenshots at specific states
4. Compares output against expected assets in expected/

# test/acceptance.d/menu-visual-test.sh excerpt

omarchy launch-menu &
sleep 2
take_screenshot "menu_before.png"

# Simulate navigation...

compare_screenshot "menu_before.png" "expected/menu_before.png"

Test Orchestration Runners

Omarchy provides top-level runner scripts that coordinate execution across the three layers. These wrappers enforce consistent reporting and environment setup.

The ./test/all script combines all three layers. It executes $ROOT/test/cli, $ROOT/test/shell, and $ROOT/test/acceptance.d/ in sequence, allowing a single command to validate the entire system.

The ./test/shell runner specifically targets the shell test layer. It sources test/shell.d/base-test.sh to load shared assertion helpers, then loops through test files to report pass/fail status.

The ./test/acceptance runner manages the VM lifecycle. It spins up a temporary virtual machine, mounts the repository, runs the acceptance scripts, and reports visual diffs before destroying the instance.

Executing Specific Test Layers

Developers can invoke individual layers based on their current workflow needs.

Run the fast CLI validation:

./test/cli

Execute all shell environment tests:

./test/shell

Launch the full graphical acceptance suite:

./test/acceptance

Or invoke the comprehensive suite:

./test/all

Summary

• Omarchy testing suite organization relies on three distinct layers under test/ to separate concerns by execution speed and environment requirements.
• test/cli contains a single Bash script for fast, deterministic CLI routing and metadata validation.
• test/shell.d/ hosts focused shell scripts for Quickshell environment testing, executed by the ./test/shell runner using the shared base-test.sh harness.
• test/acceptance.d/ holds VM-based graphical tests that validate UI rendering and widget interactions via screenshot comparison.
• Top-level runners (./test/all, ./test/shell, ./test/acceptance) provide unified entry points for local development and CI pipelines.

Frequently Asked Questions

What distinguishes shell tests from acceptance tests in Omarchy?

Shell tests in test/shell.d/ validate logic and helpers without a graphical session, running directly on the host for rapid feedback. Acceptance tests in test/acceptance.d/ require a full desktop environment and execute inside a disposable VM to capture visual regressions in the UI. According to the Omarchy source, shell tests assert file existence and command output, while acceptance tests compare screenshots against expected assets.

How do I run only the CLI test layer?

Execute the ./test/cli script from the repository root. This single script runs the entire CLI router validation suite—including help output, version checks, and command metadata linting—independently of the shell or acceptance layers. It completes in seconds and requires no VM or graphical environment.

Why does Omarchy isolate acceptance tests in a virtual machine?

Acceptance tests launch the full Omarchy UI and manipulate graphical elements that require a running X server or Wayland session. By running these inside a disposable VM, the suite prevents host environment pollution, ensures consistent display server configuration, and safely captures screenshots without interfering with the developer's active desktop session. The ./test/acceptance runner manages this VM lifecycle automatically.

Where does Omarchy define shared test utilities for shell scripts?

The shared harness lives at test/shell.d/base-test.sh. The ./test/shell runner sources this file before executing individual test scripts, providing common assertion functions like assert_file_exists and assert_command_output that standardize validation across the shell test suite.

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