BATS Testing Framework

BATS (Bash Automated Testing System) is a TAP-compliant testing framework for Bash 3.2+. Think of it as JUnit for Bash—structured, repeatable testing for shell scripts.

Workflow Decision Tree

Creating New Test Suite

•Initialize project structure (see "Project Setup" below)
•Create test files with .bats extension
•Load helper libraries in setup()
•Write tests using @test blocks

Writing Tests

•Testing script output? → Use run + assert_output
•Testing exit codes? → Use run + assert_success/assert_failure
•Testing file operations? → Use bats-file assertions
•Mocking external commands? → See gotchas.md

Debugging Failures

•Test hangs? → Check for background tasks holding FD 3
•Pipes don't work? → Use bash -c wrapper or bats_pipe
•Negation doesn't fail? → Use run ! (BATS 1.5+)
•Variables disappear? → Don't use run for assignments
•See gotchas.md for complete troubleshooting

Project Setup

Recommended Structure

code

project/
├── src/
│   └── my_script.sh
├── test/
│   ├── bats/                    # bats-core submodule
│   ├── test_helper/
│   │   ├── bats-support/        # Output formatting
│   │   ├── bats-assert/         # Assertions
│   │   ├── bats-file/           # Filesystem assertions
│   │   └── common-setup.bash    # Shared setup logic
│   ├── unit/
│   │   └── parser.bats
│   └── integration/
│       └── api.bats
└── .gitmodules

Initialize Submodules

bash

git submodule add https://github.com/bats-core/bats-core.git test/bats
git submodule add https://github.com/bats-core/bats-support.git test/test_helper/bats-support
git submodule add https://github.com/bats-core/bats-assert.git test/test_helper/bats-assert
git submodule add https://github.com/bats-core/bats-file.git test/test_helper/bats-file

Common Setup Helper

Create test/test_helper/common-setup.bash:

bash

_common_setup() {
    load "$BATS_TEST_DIRNAME/test_helper/bats-support/load"
    load "$BATS_TEST_DIRNAME/test_helper/bats-assert/load"
    load "$BATS_TEST_DIRNAME/test_helper/bats-file/load"
    
    PROJECT_ROOT="$(cd "$BATS_TEST_DIRNAME/.." && pwd)"
    export PATH="$PROJECT_ROOT/src:$PATH"
}

Test File Template

bash

#!/usr/bin/env bats

setup_file() {
    # Runs ONCE before all tests in file (expensive setup)
    export SHARED_RESOURCE="initialized"
}

setup() {
    # Runs before EACH test
    load 'test_helper/common-setup'
    _common_setup
    TEST_DIR="$BATS_TEST_TMPDIR"
}

teardown() {
    # Runs after EACH test (cleanup)
    rm -rf "$TEST_DIR" 2>/dev/null || true
}

teardown_file() {
    # Runs ONCE after all tests (final cleanup)
    unset SHARED_RESOURCE
}

@test "describe expected behavior" {
    run my_command arg1 arg2
    
    assert_success
    assert_output --partial "expected substring"
}

The `run` Helper

run captures exit status and output in a subshell:

bash

run command arg1 arg2

# Available after run:
$status              # Exit code
$output              # Combined stdout+stderr
${lines[@]}          # Array of output lines
${lines[0]}          # First line

# Implicit status checks (BATS 1.5+)
run -1 failing_command      # Expect exit code 1
run ! command               # Expect non-zero exit
run --separate-stderr cmd   # Separate $output and $stderr

Critical: run always returns 0 to BATS. Always check $status explicitly or use assertions.

Core Assertions (bats-assert)

bash

# Exit status
assert_success                    # $status == 0
assert_failure                    # $status != 0
assert_failure 1                  # $status == 1

# Output
assert_output "exact match"
assert_output --partial "substring"
assert_output --regexp "^[0-9]+$"

# Lines
assert_line "any line matches"
assert_line --index 0 "first line"
assert_line --partial "substring"

# Negations
refute_output "not this"
refute_line "not in output"

File Assertions (bats-file)

bash

assert_file_exists "/path/to/file"
assert_dir_exists "/path/to/dir"
assert_file_executable "/path/to/script"
assert_file_not_empty "/path/to/file"
assert_file_contains "/path/to/file" "search text"

Temporary Directories

Variable	Scope	Use Case
`$BATS_TEST_TMPDIR`	Per test	Always use for isolation
`$BATS_FILE_TMPDIR`	Per file	Shared fixtures in `setup_file`
`$BATS_RUN_TMPDIR`	Per run	Rarely needed

bash

@test "file operations" {
    echo "data" > "$BATS_TEST_TMPDIR/file.txt"
    run process_file "$BATS_TEST_TMPDIR/file.txt"
    assert_success
    # Automatically cleaned up
}

Mocking External Commands

Mock via PATH manipulation:

bash

@test "mock curl" {
    mkdir -p "$BATS_TEST_TMPDIR/bin"
    cat > "$BATS_TEST_TMPDIR/bin/curl" <<'EOF'
#!/bin/bash
echo '{"status":"ok"}'
EOF
    chmod +x "$BATS_TEST_TMPDIR/bin/curl"
    export PATH="$BATS_TEST_TMPDIR/bin:$PATH"
    
    run script_using_curl
    assert_output --partial "status"
}

Running Tests

bash

# Basic execution
bats test/                           # All tests
bats -r test/                        # Recursive
bats --jobs 4 test/                  # Parallel

# Filtering
bats --filter "login" test/          # By name regex
bats --filter-tags api,!slow test/   # By tags
bats --filter-status failed test/    # Re-run failures

# Output formats
bats --formatter junit --output ./reports test/  # JUnit for CI
bats --timing test/                              # Show durations

Tagging Tests

bash

# bats test_tags=api,smoke
@test "user login" { }

# Run tagged tests
bats --filter-tags api test/           # Has 'api'
bats --filter-tags api,!slow test/     # Has 'api' but not 'slow'

Skip Tests

bash

@test "not ready" {
    skip "Feature not implemented"
}

@test "requires docker" {
    command -v docker || skip "Docker not installed"
    run docker ps
}

CI/CD Integration

GitHub Actions

yaml

- name: Run tests
  run: ./test/bats/bin/bats --formatter junit --output ./reports test/

- name: Publish results
  uses: EnricoMi/publish-unit-test-result-action@v2
  if: always()
  with:
    files: reports/report.xml

GitLab CI

yaml

test:
  script:
    - bats --formatter junit --output reports/ test/
  artifacts:
    reports:
      junit: reports/report.xml

Reference Documentation

•Common pitfalls and debugging: See references/gotchas.md
•Complete assertion reference: See references/assertions.md
•Real-world project examples: See references/projects.md
•CI/CD integration patterns: See references/ci-integration.md

Quick Troubleshooting

Problem	Solution
Test passes but should fail	Use `assert_failure` or check `$status`
Pipes don't work with `run`	Use `run bash -c "cmd1 \| cmd2"`
`! true` doesn't fail test	Use `run ! true` (BATS 1.5+)
Variables lost after `run`	Don't use `run` for assignments
Test hangs indefinitely	Close FD 3 for background tasks: `cmd 3>&- &`
Output has ANSI colors	Use `strip_colors` helper or `NO_COLOR=1`

Code Style

•Use run for capturing output, direct execution for state changes
•Always check $status or use assertions
•Prefer $BATS_TEST_TMPDIR over hardcoded paths
•Mock external dependencies, not internal logic
•Name tests to describe expected behavior

BATS Testing Framework

Workflow Decision Tree

Creating New Test Suite

Writing Tests

Debugging Failures

Project Setup

Recommended Structure

Initialize Submodules

Common Setup Helper

Test File Template

The run Helper

Core Assertions (bats-assert)

File Assertions (bats-file)

Temporary Directories

Mocking External Commands

Running Tests

Tagging Tests

Skip Tests

CI/CD Integration

GitHub Actions

GitLab CI

Reference Documentation

Quick Troubleshooting

Code Style

The `run` Helper