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

> Discover how the Omarchy testing suite organizes CLI, shell, and acceptance layers in test/cli, test/shell.d/, and test/acceptance.d/ for effective validation. Learn more.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-09

---

**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`](https://github.com/omacom/omarchy/blob/main/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:

```bash

# 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/`

```bash

# 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`](https://github.com/omacom/omarchy/blob/main/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:

```bash
./test/cli

```

Execute all shell environment tests:

```bash
./test/shell

```

Launch the full graphical acceptance suite:

```bash
./test/acceptance

```

Or invoke the comprehensive suite:

```bash
./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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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.