Bats Testing Patterns
Master Bash Automated Testing System (Bats) for comprehensive shell script testing. Use when writing tests for shell scripts, CI/CD pipelines, or requiring test-driven development of shell utilities.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Bats Testing Patterns when an AI agent needs a reusable SKILL.md workflow for this job: Master Bash Automated Testing System (Bats) for comprehensive shell script testing. Use when writing tests for shell scripts, CI/CD pipelines, or requiring test-driven development of shell utilities.
When not to use it
Skip Bats Testing Patterns when the task is outside the writing category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/bats-testing-patterns # Save SKILL.md to ~/.claude/skills/bats-testing-patterns/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/bats-testing-patterns/SKILL.md. For a shared project, commit the folder at .claude/skills/bats-testing-patterns/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Bats Testing Patterns skill for this task: Writing unit tests for shell scripts. Confirm any required inputs or files before making changes.
What supports this recommendation?
90/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 100/100
- Practical detail
- 100/100
- Source evidence
- 63/100
- Source signals
- 80/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Bats Testing Patterns
Comprehensive guidance for writing comprehensive unit tests for shell scripts using Bats (Bash Automated Testing System), including test patterns, fixtures, and best practices for production-grade shell testing.
## When to Use This Skill
- Writing unit tests for shell scripts - Implementing test-driven development (TDD) for scripts - Setting up automated testing in CI/CD pipelines - Testing edge cases and error conditions - Validating behavior across different shell environments - Building maintainable test suites for scripts - Creating fixtures for complex test scenarios - Testing multiple shell dialects (bash, sh, dash)
## Detailed patterns and worked examples
Detailed pattern documentation lives in `references/details.md`. Read that file when the navigation tier above is insufficient.
## Testing Error Conditions
```bash #!/usr/bin/env bats
@test "Function fails with missing file" { run my_function "/nonexistent/file.txt" [ "$status" -ne 0 ] [[ "$output" == *"not found"* ]] }
@test "Function fails with invalid input" { run my_function "" [ "$status" -ne 0 ] }
@test "Function fails with permission denied" { touch "$TMPDIR/readonly.txt" chmod 000 "$TMPDIR/readonly.txt" run my_function "$TMPDIR/readonly.txt" [ "$status" -ne 0 ] chmod 644 "$TMPDIR/readonly.txt" # Cleanup }
@test "Function provides helpful error message" { run my_function --invalid-option [ "$status" -ne 0 ] [[ "$output" == *"Usage:"* ]] } ```
### Testing with Dependencies
```bash #!/usr/bin/env bats
setup() { # Check for required tools if ! command -v jq &>/dev/null; then skip "jq is not installed" fi
export SCRIPT="${BATS_TEST_DIRNAME}/../bin/script.sh" }
@test "JSON parsing works" { skip_if ! command -v jq &>/dev/null run my_json_parser '{"key": "value"}' [ "$status" -eq 0 ] } ```
### Testing Shell Compatibility
```bash #!/usr/bin/env bats
@test "Script works in bash" { bash "${BATS_TEST_DIRNAME}/../bin/script.sh" arg1 }
@test "Script works in sh (POSIX)" { sh "${BATS_TEST_DIRNAME}/../bin/script.sh" arg1 }
@test "Script works in dash" { if command -v dash &>/dev/null; then dash "${BATS_TEST_DIRNAME}/../bin/script.sh" arg1 else skip "dash not installed" fi } ```
### Parallel Execution
```bash #!/usr/bin/env bats
@test "Multiple independent operations" { run bash -c 'for i in {1..10}; do my_operation "$i" & done wait' [ "$status" -eq 0 ] }
@test "Concurrent file operations" { for i in {1..5}; do my_function "$TMPDIR/file$i" & done wait [ -f "$TMPDIR/file1" ] [ -f "$TMPDIR/file5" ] } ```
## Test Helper Pattern
### test_helper.sh
```bash #!/usr/bin/env bash
# Source script under test export SCRIPT_DIR="${BATS_TEST_DIRNAME%/*}/bin"
# Common test utilities assert_file_exists() { if [ ! -f "$1" ]; then echo "Expected file to exist: $1" return 1 fi }
assert_file_equals() { local file="$1" local expected="$2"
if [ ! -f "$file" ]; then echo "File does not exist: $file" return 1 fi
local actual=$(cat "$file") if [ "$actual" != "$expected" ]; then echo "File contents do not match" echo "Expected: $expected" echo "Actual: $actual" return 1 fi }
# Create temporary test directory setup_test_dir() { export TEST_DIR=$(mktemp -d) }
cleanup_test_dir() { rm -rf "$TEST_DIR" } ```
## Integration with CI/CD
### GitHub Actions Workflow
```yaml name: Tests
on: [push, pull_request]
jobs: test: runs-on: ubuntu-latest
steps: - uses: actions/checkout@v3
- name: Install Bats run: | npm install --global bats
- name: Run Tests run: | bats tests/*.bats
- name: Run Tests with Tap Reporter run: | bats tests/*.bats --tap | tee test_output.tap ```
### Makefile Integration
```makefile .PHONY: test test-verbose test-tap
test: bats tests/*.bats
test-verbose: bats tests/*.bats --verbose
test-tap: bats tests/*.bats --tap
test-parallel: bats tests/*.bats --parallel 4
coverage: test # Optional: Generate coverage reports ```
## Best Practices
1. **Test one thing per test** - Single responsibility principle 2. **Use descriptive test names** - Clearly states what is being tested 3. **Clean up after tests** - Always remove temporary files in teardown 4. **Test both success and failure paths** - Don't just test happy path 5. **Mock external dependencies** - Isolate unit under test 6. **Use fixtures for complex data** - Makes tests more readable 7. **Run tests in CI/CD** - Catch regressions early 8. **Test across shell dialects** - Ensure portability 9. **Keep tests fast** - Run in parallel when possible 10. **Document complex test setup** - Explain unusual patterns
Intended uses
- Writing unit tests for shell scripts
- Implementing test-driven development (TDD) for scripts
- Setting up automated testing in CI/CD pipelines
- Testing edge cases and error conditions
- Validating behavior across different shell environments
- Building maintainable test suites for scripts
- Creating fixtures for complex test scenarios
- Testing multiple shell dialects (bash, sh, dash)
Implementation notes
- Test one thing per test - Single responsibility principle
- Use descriptive test names - Clearly states what is being tested
- Clean up after tests - Always remove temporary files in teardown
- Test both success and failure paths - Don't just test happy path
- Mock external dependencies - Isolate unit under test
- Use fixtures for complex data - Makes tests more readable
- Run tests in CI/CD - Catch regressions early
- Test across shell dialects - Ensure portability
- Keep tests fast - Run in parallel when possible
- Document complex test setup - Explain unusual patterns
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.