# What Are Omarchy's CLI Tests and Shell Tests? A Complete Guide to the Testing Architecture

> Explore Omarchy's testing architecture. Understand CLI tests for command-line validation and shell tests for Quickshell desktop environment verification in this complete guide.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-20

---

**Omarchy's test suite consists of two distinct layers: CLI tests in `test/cli/` for command-line validation and shell tests in `test/shell.d/` for Quickshell desktop environment verification.**

Omarchy, Basecamp's Quickshell-based Linux desktop environment, ships with a comprehensive Bash-based testing framework. The source code reveals a dual-suite architecture designed to validate both programmatic CLI behavior and interactive UI components without requiring a graphical display in CI environments.

## CLI Tests: Command-Line Interface Validation

The **CLI test suite** resides in `test/cli/`, a directory reserved for automated scripts that invoke `omarchy-*` commands directly.

Due to permission constraints in the analysis, the `test/cli/` directory appeared empty in the quattro branch, but the test runner infrastructure remains in place. When populated, these tests verify:

- **Exit codes** from `omarchy` subcommands
- **Output matching** against expected version strings and help text
- **Side effects** such as configuration file updates

The CLI suite integrates with the master runner at `test/all`, which executes any scripts found in this directory before proceeding to shell tests.

### Example CLI Test Structure

When present, a CLI test such as [`test/cli/version-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/cli/version-test.sh) follows this pattern:

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

# test/cli/version-test.sh (hypothetical example based on architecture)

source test/shell.d/base-test.sh

test_version_output() {
    local output
    output=$(omarchy version)
    assert_contains "$output" "$(cat VERSION)"
}

run_test test_version_output

```

## Shell Tests: Quickshell Desktop Verification

The **shell test suite** represents Omarchy's primary testing surface. Located in `test/shell.d/`, this collection contains more than 80 `*.sh` files—each a self-contained Bash script that exercises specific UI features through temporary Quickshell sessions.

### Test Organization

| Category | Example Files | Coverage Area |
|----------|-------------|---------------|
| Menu interaction | [`menu-test.sh`](https://github.com/basecamp/omarchy/blob/main/menu-test.sh), [`launcher-test.sh`](https://github.com/basecamp/omarchy/blob/main/launcher-test.sh) | Application menus and launchers |
| System controls | [`power-test.sh`](https://github.com/basecamp/omarchy/blob/main/power-test.sh), [`brightness-test.sh`](https://github.com/basecamp/omarchy/blob/main/brightness-test.sh) | Power profiles, display settings |
| Notifications | [`notification-test.sh`](https://github.com/basecamp/omarchy/blob/main/notification-test.sh) | Alert systems and OSD |
| Configuration | [`config-test.sh`](https://github.com/basecamp/omarchy/blob/main/config-test.sh) | Runtime configuration changes |

### Key Shell Test Files

- **[`test/shell.d/base-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/base-test.sh)** — Shared utilities providing setup/teardown, assertions, and Quickshell session management
- **[`test/shell.d/menu-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/menu-test.sh)** — Validates the Omarchy menu renders expected items
- **`test/all`** — Master orchestrator that sequences both test suites

### Running Shell Tests Individually

```bash

# From repository root

./test/shell.d/menu-test.sh

```

This command:

1. Sources [`base-test.sh`](https://github.com/basecamp/omarchy/blob/main/base-test.sh) for helper functions
2. Spawns a temporary Quickshell instance
3. Opens the Omarchy menu via IPC or key simulation
4. Asserts expected menu items are present
5. Performs clean shutdown

## The Master Test Runner: `test/all`

The `test/all` script serves as the universal entry point for Omarchy's testing infrastructure. According to the source analysis, this wrapper:

- Executes `./test/cli` if CLI tests exist
- Iterates through `test/shell.d/*.sh` and runs each sequentially
- Aggregates exit codes for CI reporting

### Full Suite Execution

```bash

# Run both CLI and shell tests

./test/all

```

```bash

# Run only shell tests (when CLI directory is empty)

./test/shell.d/*

```

## Testing Without Graphics: The CI Advantage

Omarchy's shell tests achieve **headless execution** through Quickshell's ability to run in offscreen or dummy backend modes. This architectural decision—documented in [`docs/testing.md`](https://github.com/basecamp/omarchy/blob/main/docs/testing.md)—enables:

- GitHub Actions and similar CI platforms to validate desktop behavior
- Deterministic test results without display server dependencies
- Rapid feedback loops during development

The helper functions in [`test/shell.d/base-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/base-test.sh) abstract platform differences, providing a consistent interface for:

- Session lifecycle management
- Synchronization primitives (wait-for-condition loops)
- Output capture and assertion macros

## Adding New Tests: File Patterns and Conventions

The analysis reveals strict organizational conventions:

| Pattern | Purpose |
|---------|---------|
| `test/cli/*.sh` | CLI command validation |
| `test/shell.d/*-test.sh` | Individual UI feature tests |
| [`test/shell.d/base-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/base-test.sh) | Reserved for shared utilities (not executed directly) |

New shell tests must:

1. Source [`base-test.sh`](https://github.com/basecamp/omarchy/blob/main/base-test.sh) via relative path
2. Define test functions prefixed with `test_`
3. Call `run_test <function_name>` for each test case
4. Exit with status 0 on success, non-zero on failure

## Summary

- **CLI tests** in `test/cli/` validate `omarchy-*` command behavior through direct invocation and output inspection
- **Shell tests** in `test/shell.d/` comprise 80+ Bash scripts testing Quickshell UI components in temporary sessions
- **`test/all`** orchestrates both suites sequentially for unified execution
- **[`test/shell.d/base-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/base-test.sh)** provides shared utilities enabling headless CI execution
- All tests are **Bash-native**, require no GUI display, and integrate with standard CI pipelines

## Frequently Asked Questions

### What does `test/all` actually do?

`test/all` is the master test runner that sequentially executes the CLI test suite (if test files exist in `test/cli/`) followed by every `*-test.sh` script in `test/shell.d/`. It aggregates exit codes and provides a unified pass/fail result suitable for CI integration.

### Why might `test/cli/` appear empty?

The `test/cli/` directory is reserved for CLI-specific tests but may be unpopulated in certain branches (such as quattro) where CLI validation is handled through other means or pending implementation. The test runner infrastructure remains prepared to execute any scripts placed there.

### How do shell tests run without a display server?

Omarchy's shell tests leverage Quickshell's ability to run with offscreen or dummy backends. The helper functions in [`test/shell.d/base-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/base-test.sh) manage session startup with appropriate flags, allowing full UI testing in headless CI environments without X11 or Wayland.

### Where is the testing documentation located?

Repository documentation for Omarchy's testing strategy, environment variable requirements, and contribution guidelines resides in [`docs/testing.md`](https://github.com/basecamp/omarchy/blob/main/docs/testing.md) at the repository root, as referenced in the source analysis.