# How Test Suites Are Organized Within the Omarchy Repository

> Discover how Omarchy organizes its test suites for efficient development. Learn about CLI, shell integration, and acceptance tests coordinated by the aggregate runner.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: internals
- Published: 2026-08-19

---

**TLDR:** Omarchy organizes its automated tests into three distinct suites—CLI tests in `test/cli`, shell integration tests in `test/shell.d/`, and acceptance tests in `test/acceptance.d/`—coordinated by the aggregate runner `test/all` to balance fast feedback with comprehensive end-to-end coverage.

The basecamp/omarchy repository implements a layered testing architecture that separates command-line validation from shell environment integration and graphical acceptance testing. This organization allows developers to execute targeted test runs during development while maintaining rigorous end-to-end coverage through disposable virtual machines.

## Overview of Omarchy's Three-Layer Test Architecture

Omarchy's test suites are partitioned by execution environment and speed requirements. The **aggregate runner** `test/all` serves as the default CI entry point, while specialized directories isolate tests by their dependencies—ranging from headless CLI checks to graphical VM-based acceptance flows.

## The Aggregate Runner: `test/all`

Located at `test/all`, the aggregate runner orchestrates the complete non-graphical test execution for continuous integration. According to the basecamp/omarchy source code, this script sequentially invokes the CLI suite and the shell suite to provide comprehensive coverage without requiring a display server.

This entry point is optimized for CI pipelines because it excludes acceptance tests that demand a full graphical session. By separating concerns at the runner level, Omarchy ensures that every push triggers fast, reliable validation while reserving heavyweight UI tests for dedicated workflows.

## CLI Test Suite (`test/cli`)

The **CLI test suite** resides in the `test/cli` directory and contains focused, lightweight tests that verify the Omarchy binary's behavior. These tests execute the command-line interface to validate routing logic, command group organization, and command metadata correctness.

Because these tests operate without initializing a Quickshell environment or hardware detection layers, they provide immediate feedback during development. The CLI suite checks theme helpers and ensures that command metadata structures remain valid across changes, making it ideal for rapid iteration on command-line functionality.

## Shell Integration Suite (`test/shell.d/`)

The **shell integration suite** consists of individual Bash scripts located in `test/shell.d/`, each functioning as a self-contained test that drives the Quickshell environment. Unlike the CLI suite, these scripts initialize minimal Quickshell contexts to exercise hardware detection, plugins, UI widgets, and system-level helpers.

Specific test files include:

- [`test/shell.d/weather-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/weather-test.sh) – validates weather-related command execution
- [`test/shell.d/toggle-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/toggle-test.sh) – exercises toggle helper functionality
- [`test/shell.d/monitor-modeless-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/monitor-modeless-test.sh) – verifies monitor handling logic

This modular layout allows developers to add new integration tests without modifying existing files. Each script sets up its required environment, runs a specific command or plugin, and asserts expected outcomes, providing isolated validation of individual shell components.

## Acceptance Testing Suite (`test/acceptance.d/`)

The **acceptance test suite** in `test/acceptance.d/` contains end-to-end UI tests that execute inside disposable virtual machines to validate visual behavior and user-facing flows. These tests are explicitly excluded from the default `test/all` run because they require a full graphical session and cannot execute in headless CI environments.

Entry points such as [`test/acceptance.d/menu-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/acceptance.d/menu-test.sh) drive actual UI interactions to verify rendering accuracy, menu behaviors, and panel functionality. Developers invoke these tests manually or through dedicated VM workflows when validating graphical changes, ensuring that visual regressions are caught before deployment.

## Running the Test Suites

Developers can execute specific test layers depending on their current development context. The following commands demonstrate how to run each suite according to the basecamp/omarchy test organization:

```bash

# Execute the full non-graphical test suite (CLI + shell)

./test/all

# Run only the CLI tests for rapid command-line validation

./test/cli

# Execute a single shell integration test in isolation

./test/shell.d/toggle-test.sh

# Run acceptance tests (requires a VM with graphical session)

./test/acceptance.d/menu-test.sh

```

This structure enables targeted testing during feature development. When modifying routing logic, run `./test/cli` for immediate feedback. For shell plugin changes, execute the specific script in `test/shell.d/` rather than the full suite.

## Summary

- Omarchy's testing architecture separates concerns across three distinct suites: CLI tests in `test/cli`, shell integration tests in `test/shell.d/`, and acceptance tests in `test/acceptance.d/`
- The `test/all` aggregate runner coordinates CLI and shell suites for CI pipelines while excluding VM-dependent acceptance tests
- CLI tests provide fast validation of routing, command metadata, and theme helpers without initializing the Quickshell environment
- Shell tests in `test/shell.d/` are self-contained Bash scripts that initialize minimal Quickshell contexts to validate hardware detection, plugins, and UI widgets
- Acceptance tests require disposable VMs and validate graphical rendering, menu interactions, and panel behavior through scripts like [`test/acceptance.d/menu-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/acceptance.d/menu-test.sh)

## Frequently Asked Questions

### What is the difference between the CLI suite and the shell suite in Omarchy?

The **CLI suite** (`test/cli`) consists of lightweight tests that execute the Omarchy binary directly to verify command routing and metadata without initializing the Quickshell environment. The **shell suite** (`test/shell.d/`) contains individual Bash scripts that set up minimal Quickshell contexts to test hardware detection, plugins, and interactive widgets, making them heavier but more comprehensive for integration validation.

### How do I run a single test file without executing the entire Omarchy test suite?

Navigate to the specific test file and execute it directly. For shell integration tests, run `./test/shell.d/[filename].sh` (for example, [`./test/shell.d/weather-test.sh`](https://github.com/basecamp/omarchy/blob/main/./test/shell.d/weather-test.sh)). For acceptance tests, execute the individual script in `test/acceptance.d/` such as [`./test/acceptance.d/menu-test.sh`](https://github.com/basecamp/omarchy/blob/main/./test/acceptance.d/menu-test.sh), provided you have a graphical environment available.

### Why are acceptance tests excluded from the default CI pipeline in basecamp/omarchy?

Acceptance tests require a full graphical session running inside a disposable virtual machine to validate UI rendering and visual interactions. Since CI environments are typically headless and cannot provide the necessary display server infrastructure, these tests remain outside the `test/all` aggregate runner and are triggered manually or through dedicated VM workflows instead.

### Where should I add a new test for a custom shell plugin in Omarchy?

Add new shell plugin tests as self-contained Bash scripts in the `test/shell.d/` directory. Following the existing pattern seen in files like [`test/shell.d/toggle-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/toggle-test.sh), create a script that initializes a minimal Quickshell environment, executes your plugin's functionality, and asserts the expected output. This modular approach ensures your test runs independently without affecting existing validation logic.