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

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 follows this pattern:

#!/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, launcher-test.sh	Application menus and launchers
System controls	power-test.sh, brightness-test.sh	Power profiles, display settings
Notifications	notification-test.sh	Alert systems and OSD
Configuration	config-test.sh	Runtime configuration changes

Key Shell Test Files

• test/shell.d/base-test.sh — Shared utilities providing setup/teardown, assertions, and Quickshell session management
• 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

# From repository root

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

This command:

1. Sources 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

# Run both CLI and shell tests

./test/all

# 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—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 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	Reserved for shared utilities (not executed directly)

New shell tests must:

1. Source 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 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 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 at the repository root, as referenced in the source analysis.

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