# Omarchy Testing Strategies: Shell, CLI, and Acceptance Testing Explained

> Explore Omarchy testing strategies: shell, CLI, and acceptance tests. Learn how this framework ensures robust software with integrated tests for reliable performance. Read the guide now.

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

---

**The Omarchy framework employs a three-tier testing architecture that combines Bash-based shell integration tests in `test/shell.d/`, isolated CLI unit tests in `test/cli/`, and full-system acceptance tests in `test/acceptance.d/`, all orchestrated through `./test/all` and documented in [`docs/testing.md`](https://github.com/basecamp/omarchy/blob/main/docs/testing.md).**

The `basecamp/omarchy` repository implements a rigorous testing methodology designed to validate Quickshell-based desktop environment functionality. These Omarchy testing strategies prioritize running "the real thing as close to a user's session as possible," ensuring that shell commands, CLI routing, and graphical interfaces remain stable across updates.

## Overview of the Omarchy Testing Philosophy

According to the source documentation in [`docs/testing.md`](https://github.com/basecamp/omarchy/blob/main/docs/testing.md), the testing philosophy centers on spawning actual Omarchy sessions rather than mocking dependencies. This approach validates real-world interactions through **shell tests** that exercise the complete stack, **CLI tests** that verify pure logic paths, and **acceptance tests** that catch rendering and interaction regressions in a headless VM.

### Layered Testing Architecture

The repository organizes validation into three complementary layers:

- **Shell-script tests**: End-to-end Bash scripts in `test/shell.d/` that spawn fresh Omarchy sessions and verify system integration
- **CLI tests**: Unit-style validation of command-line routing and utilities located in `test/cli/`
- **Acceptance tests**: Full-screen graphical validation within `test/acceptance.d/` that serves as the "gold standard" for UI correctness

## Shell-Based End-to-End Testing

The shell test suite provides comprehensive coverage of Quickshell commands, plugins, menus, power-profile handling, and system-d integration. This suite contains over 80 self-contained Bash scripts that execute commands through the same entry points users access.

### Test Locations and Structure

Individual test files reside in `test/shell.d/` following the naming convention `*-test.sh`. Key examples include:

- [`menu-test.sh`](https://github.com/basecamp/omarchy/blob/main/menu-test.sh) – Validates menu system functionality
- [`panel-command-path-test.sh`](https://github.com/basecamp/omarchy/blob/main/panel-command-path-test.sh) – Verifies PATH resolution in panels
- [`update-lock-test.sh`](https://github.com/basecamp/omarchy/blob/main/update-lock-test.sh) – Checks update locking mechanisms

The `test/shell` wrapper automatically loads all files matching `test/shell.d/*-test.sh` and reports aggregate success or failure.

### Running the Shell Suite

Execute the shell-specific test harness from the repository root:

```bash
./test/shell

```

This command initializes the test environment, executes each script in `test/shell.d/`, and provides detailed output regarding assertions and failures.

### Writing New Shell Tests

New tests should source the shared framework from [`test/shell.d/base-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/base-test.sh), which provides common setup, teardown, and assertion functions. The template follows this structure:

```bash
#!/usr/bin/env bash

# test/shell.d/example-feature-test.sh

# shellcheck disable=SC2034

. "$(dirname "$0")/base-test.sh"

omarchy-session-start

omarchy foo --bar

assert_file_exists "$HOME/.config/omarchy/foo.cfg"
assert_process_running omarchy-foo

omarchy-session-stop

```

The [`base-test.sh`](https://github.com/basecamp/omarchy/blob/main/base-test.sh) library handles session lifecycle management, logging, and standardized assertion reporting.

## CLI and Router Testing

The CLI test suite focuses on the command-line router, command-metadata parsing, and helper utilities. These tests validate argument parsing and output formatting without launching a full desktop session.

### CLI Test Structure

CLI tests live in `test/cli/` with shared utilities in `test/cli.d/` such as [`assert.sh`](https://github.com/basecamp/omarchy/blob/main/assert.sh). These scripts test pure logic paths including:

- Command routing logic
- Argument parsing edge cases
- Output formatting and metadata retrieval

### Executing CLI Tests

Run the CLI-specific validation using:

```bash
./test/cli

```

Individual CLI test files can also be executed directly for targeted debugging:

```bash
bash test/cli/cli-router-test.sh

```

## Acceptance Testing for Graphical Components

The acceptance layer in `test/acceptance.d/` provides functional testing that drives the actual UI including menus, notifications, and panels. These tests require a headless VM environment and validate visual outcomes that cannot be inspected through shell scripts alone.

The acceptance suite catches regressions in rendering, window management, and interactive behaviors. According to the repository structure, these tests are executed through the Omarchy acceptance-test runner within the CI pipeline.

## CI Orchestration and Automation

Continuous integration is configured in `.github/workflows/` to execute the comprehensive test suite on every push and pull request. The CI workflow invokes `./test/all`, which aggregates the shell, CLI, and acceptance suites and aborts the build upon any failure.

Running the complete validation locally mirrors the CI behavior:

```bash
./test/all

```

This entry point ensures that all three testing layers pass before code is considered production-ready.

## Shared Testing Utilities

Reusable testing infrastructure resides in [`test/shell.d/base-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/base-test.sh) and [`test/cli.d/assert.sh`](https://github.com/basecamp/omarchy/blob/main/test/cli.d/assert.sh). These helper libraries provide:

- **Session management**: `omarchy-session-start` and `omarchy-session-stop` functions
- **File assertions**: `assert_file_exists` for configuration validation
- **Process verification**: `assert_process_running` for daemon checking
- **Logging utilities**: Standardized output formatting for CI compatibility

Using these shared resources ensures consistency across the test suite and reduces boilerplate in individual test files.

## Summary

- **Shell tests** in `test/shell.d/` provide end-to-end integration coverage using Bash scripts that spawn real Omarchy sessions
- **CLI tests** in `test/cli/` validate routing and utility logic without requiring a full desktop environment
- **Acceptance tests** in `test/acceptance.d/` serve as the gold standard for graphical and interactive functionality
- **CI orchestration** through `./test/all` and `.github/workflows/` ensures comprehensive validation on every code change
- **Shared utilities** in [`test/shell.d/base-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/base-test.sh) and [`test/cli.d/assert.sh`](https://github.com/basecamp/omarchy/blob/main/test/cli.d/assert.sh) provide common assertions and session management

## Frequently Asked Questions

### How do I run only the shell-based tests in Omarchy?

Execute `./test/shell` from the repository root directory. This command loads all test files matching `test/shell.d/*-test.sh` and reports results without running the CLI or acceptance suites.

### What distinguishes shell tests from CLI tests in the Omarchy framework?

**Shell tests** spawn actual Omarchy sessions and verify side effects such as file creation and running processes through [`test/shell.d/base-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/base-test.sh). **CLI tests** focus on pure logic validation for argument parsing and routing without initializing a desktop session, residing in `test/cli/`.

### Where should I place new acceptance tests for graphical features?

New acceptance tests belong in the `test/acceptance.d/` directory. These tests run in a headless VM environment and should validate visual and interactive behaviors that cannot be inspected through shell command output alone.

### How does the Omarchy CI pipeline validate pull requests?

The CI configuration in `.github/workflows/` executes `./test/all`, which aggregates the shell, CLI, and acceptance test suites. The pipeline aborts if any test layer reports failure, ensuring that only fully validated code merges to the main branch.