Jamie-BitFlight/bash-testing

Bash Testing

Testing frameworks and patterns for shell scripts, focusing on shunit2 and shellspec.

Framework Selection

Framework	Strengths	Best For
shunit2	xUnit style, simple, portable	Unit tests, function testing
shellspec	BDD style, modern, extensive	Behavior specs, full projects

shunit2

Installation

# Download directly
curl -L https://github.com/kward/shunit2/raw/master/shunit2 -o shunit2

# Or via package manager
apt install shunit2
brew install shunit2

Basic Test Structure

#!/usr/bin/env bash

# Source the script being tested
source ./my_script.sh

# Test functions start with test
test_addition() {
    result=$(add 2 3)
    assertEquals "2 + 3 should equal 5" "5" "$result"
}

test_string_output() {
    result=$(greet "World")
    assertEquals "Hello, World" "$result"
}

test_file_creation() {
    create_temp_file
    assertTrue "Temp file should exist" "[ -f /tmp/testfile ]"
}

test_exit_code() {
    validate_input "valid"
    assertEquals "Should return 0 for valid input" 0 $?
}

# Setup and teardown
oneTimeSetUp() {
    # Run once before all tests
    export TEST_DIR=$(mktemp -d)
}

oneTimeTearDown() {
    # Run once after all tests
    rm -rf "$TEST_DIR"
}

setUp() {
    # Run before each test
    cd "$TEST_DIR"
}

tearDown() {
    # Run after each test
    rm -f "$TEST_DIR"/*
}

# Load shunit2
source shunit2

shunit2 Assertions

# Equality
assertEquals [message] expected actual
assertNotEquals [message] unexpected actual

# Null/Empty
assertNull [message] value
assertNotNull [message] value

# Boolean/Status
assertTrue [message] condition
assertFalse [message] condition

# Same reference (string comparison)
assertSame [message] expected actual
assertNotSame [message] unexpected actual

# Contains (in string)
assertContains [message] container content

# Exit status
assertEquals 0 $?

Testing Functions in Isolation

Code examples

#!/usr/bin/env bash
# test_my_functions.sh

source ./my_functions.sh

test_calculate_sum_empty() {
    result=$(calculate_sum)
    assertEquals "Empty sum should be 0" "0" "$result"
}

test_calculate_sum_single() {
    result=$(calculate_sum 5)
    assertEquals "5" "$result"
}

test_calculate_sum_multiple() {
    result=$(calculate_sum 1 2 3 4 5)
    assertEquals "15" "$result"
}

test_validate_email_valid() {
    validate_email "[email protected]"
    assertTrue "Valid email should pass" $?
}

test_validate_email_invalid() {
    validate_email "not-an-email"
    assertFalse "Invalid email should fail" $?
}

source shunit2

shellspec

Installation

# Via curl
curl -fsSL https://git.io/shellspec | sh

# Via Homebrew
brew install shellspec

# Via package managers
apt install shellspec

Directory Structure

project/
├── lib/
│   └── functions.sh
├── spec/
│   ├── spec_helper.sh
│   ├── functions_spec.sh
│   └── support/
│       └── fixtures/
└── .shellspec

Configuration (.shellspec)

--require spec_helper
--format documentation
--color

Basic Spec Structure

Code examples

shellspec Matchers

# Output matchers
The output should eq "exact match"
The output should include "partial"
The output should start with "prefix"
The output should end with "suffix"
The output should match pattern "*glob*"
The output should be blank

# Status matchers
The status should be success    # exit 0
The status should be failure    # exit non-zero
The status should eq 1          # specific code

# Variable matchers
The variable VAR should eq "value"
The variable VAR should be defined
The variable VAR should be undefined

# File matchers
The file "path" should be exist
The file "path" should be file
The file "path" should be directory
The file "path" should be readable

# Path matchers
The path "file.txt" should be exist

Mocking in shellspec

Describe 'deploy function'
  # Mock external command
  curl() {
    echo "mocked response"
    return 0
  }

  It 'calls API endpoint'
    When call deploy "server"
    The output should include "mocked response"
  End
End

Describe 'file operations'
  # Mock with function override
  Mock rm
    echo "rm called with: $*"
  End

  It 'attempts to remove file'
    When call cleanup_temp
    The output should include "rm called with"
  End
End

Spec Helper

# spec/spec_helper.sh

# Load common functions
spec_helper_precheck() {
  minimum_version "0.28.0"
}

spec_helper_loaded() {
  # Set up test environment
  export TEST_MODE=true
}

spec_helper_configure() {
  # Import project functions
  import 'lib/functions.sh'
}

Testing Patterns

Testing Exit Codes

# shunit2
test_success_exit() {
    run_command "valid_input"
    assertEquals 0 $?
}

test_error_exit() {
    run_command "invalid_input"
    assertEquals 1 $?
}

# shellspec
It 'exits 0 on success'
  When call run_command "valid_input"
  The status should eq 0
End

Testing stdout and stderr

# shunit2
test_stdout() {
    result=$(my_function 2>/dev/null)
    assertEquals "expected output" "$result"
}

test_stderr() {
    error=$(my_function 2>&1 >/dev/null)
    assertContains "$error" "error message"
}

# shellspec
It 'outputs to stdout'
  When call my_function
  The stdout should eq "expected output"
End

It 'outputs error to stderr'
  When call my_function
  The stderr should include "error message"
End

Testing with Fixtures

# Setup test fixtures
setUp() {
    TEST_DIR=$(mktemp -d)
    cat > "$TEST_DIR/config.json" <<EOF
{
    "key": "value"
}
EOF
}

tearDown() {
    rm -rf "$TEST_DIR"
}

test_config_parsing() {
    result=$(parse_config "$TEST_DIR/config.json")
    assertEquals "value" "$result"
}

Testing Interactive Functions

# Provide input via heredoc
test_interactive() {
    result=$(my_prompt <<EOF
yes
EOF
)
    assertEquals "confirmed" "$result"
}

# Or use printf
test_with_input() {
    result=$(printf 'yes\n' | my_prompt)
    assertEquals "confirmed" "$result"
}

Running Tests

# shunit2
./test_script.sh

# shellspec
shellspec                    # Run all specs
shellspec spec/file_spec.sh  # Run specific spec
shellspec --format tap       # TAP output
shellspec --jobs 4           # Parallel execution

Best Practices

1. One assertion per test when practical
2. Descriptive test names explaining what's tested
3. Isolate tests - no dependencies between tests
4. Test edge cases - empty input, special characters, large data
5. Clean up resources in tearDown
6. Mock external commands - don't test curl, test your logic
7. Test exit codes not just output