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

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.

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, 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 – Validates menu system functionality
• panel-command-path-test.sh – Verifies PATH resolution in panels
• 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:

./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, which provides common setup, teardown, and assertion functions. The template follows this structure:

#!/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 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. 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:

./test/cli

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

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:

./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 and 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 and 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. 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.

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