🧪 ZSHAND Testing Guide¶

tests/
├── 🎯 run_all.zsh              Master test runner (entry point)
├── 🔧 bootstrap_env.zsh        Test environment setup
├── 🔧 test_helpers.zsh         Common assertions & utilities (~1600 lines)
├── 🔧 ensure_bundles_fresh.zsh Pre-test bundle validation
├── 📟 bin/                      Tests for bin/* CLI tools
├── 🏗️ build/                    Tests for build system
├── ⚙️ core/                     Tests for core modules
├── 📦 dependencies/             Dependency version checks
├── 📂 file-system/              Filesystem operation tests
├── 🛠️ functions/                Tests for user-facing functions
├── 🪨 hooks/                    Tests for integration hooks
├── 📥 installers/               Tests for system installers
├── 🔐 private_functions/        Tests for internal functions
├── 🧱 shared_functions/         Tests for shared utilities
├── 🚀 startup/                  Tests for startup scripts
├── 🧪 tests-tests/              Meta-tests (test infrastructure itself)
├── 🎨 ui/                       UI rendering tests
└── ⌨️ widgets/                   Tests for ZLE widgets

# Run everything
zsh tests/run_all.zsh

# Run specific test suites
zsh tests/run_all.zsh core functions

# Run with debug output
zsh tests/run_all.zsh --debug

# Run with full trace (command-level verbosity)
zsh tests/run_all.zsh --verbose

# Run with LLM context on failures (AI debugging)
zsh tests/run_all.zsh --llm

bin  build  core  dependencies  file-system  functions
hooks  installers  private_functions  shared_functions
startup  tests-tests  ui  widgets

# Run all ShellSpec specs
just test

# Run specific spec file
just test spec/functions/dcopy_spec.sh

# Run specific directory
just test spec/core/

# Run with coverage (Kcov)
just test-coverage

#!/usr/bin/env zsh
# Test file for: functions/my_function.zsh

# Source test helpers
source "${0:A:h}/../test_helpers.zsh"

# Source the function under test
source "${PROJECT_ROOT}/functions/my_function.zsh"

# ── Tests ───────────────────────────────────────────────────────────────────

test_my_function_happy_path() {
    local result
    result=$(my_function "valid_input")
    assert_equals "expected_output" "$result" "Should return expected output"
}

test_my_function_missing_arg() {
    my_function 2>/dev/null
    assert_equals 1 $? "Should exit 1 when argument missing"
}

test_my_function_edge_case() {
    local result
    result=$(my_function "  spaces  ")
    assert_not_empty "$result" "Should handle whitespace input"
}

# ── Run ─────────────────────────────────────────────────────────────────────
run_tests

#!/usr/bin/env shellspec
# ── my_function_spec — Tests for my_function ──────────────────────────────

Describe "my_function"
  # Setup: source the function
  setup() {
    source "$PROJECT_ROOT/functions/my_function.zsh"
  }
  Before 'setup'

  Describe "happy path"
    It "returns 0 on valid input"
      When call my_function "valid_input"
      The status should be success
      The output should include "expected"
    End

    It "handles multiple arguments"
      When call my_function "arg1" "arg2"
      The status should be success
    End
  End

  Describe "error handling"
    It "exits 1 when argument missing"
      When call my_function
      The status should be failure
      The stderr should include "ERROR:"
    End

    It "exits 1 when file not found"
      When call my_function "/nonexistent/path"
      The status should be failure
    End
  End

  Describe "edge cases"
    It "handles empty string input"
      When call my_function ""
      The status should be failure
    End

    It "handles paths with spaces"
      When call my_function "/path/with spaces/file"
      The status should be success
    End
  End
End

# Run with coverage (generates HTML report)
just test-coverage

# View coverage report
open coverage/index.html

# Framework test runner with debug
zsh tests/run_all.zsh --debug core

# ShellSpec with verbose output
shellspec --format documentation spec/core/

# Run just the failing suite
zsh tests/run_all.zsh --debug core

# Run just the failing test file
zsh tests/core/test_08_audit.zsh

# Run with zsh trace (shows every command)
zsh -x tests/core/test_08_audit.zsh