# Bats — Bash Automated Testing System

> A TAP-compliant testing framework for Bash that makes it easy to verify that shell scripts and command-line programs behave as expected.

## Install

Save in your project root:

# Bats — Bash Automated Testing System

## Quick Use
```bash
# Install
npm install -g bats

# Create test file: test.bats
# @test "addition works" {
#   result="$(echo 2+2 | bc)"
#   [ "$result" -eq 4 ]
# }

# Run
bats test.bats
```

## Introduction
Bats (Bash Automated Testing System) is a testing framework for Bash scripts and command-line tools. Each test is a Bash function prefixed with `@test`, and assertions use standard Bash test constructs. Output follows the TAP (Test Anything Protocol) format for integration with CI systems.

## What Bats Does
- Runs test cases written as annotated Bash functions in `.bats` files
- Produces TAP-compatible output for CI and test aggregation tools
- Supports setup and teardown functions at the file and test level
- Provides helper libraries for assertions, file operations, and output matching
- Runs tests in parallel for faster execution on large test suites

## Architecture Overview
Bats preprocesses each `.bats` file, extracting `@test` blocks into individual Bash functions. Each test runs in its own subshell to ensure isolation. The test runner collects exit codes and output, then formats results as TAP. Helper libraries (bats-assert, bats-support, bats-file) provide higher-level assertion functions that produce informative failure messages.

## Self-Hosting & Configuration
- Install via npm (`npm install -g bats`), Homebrew, or clone the repository and run `./install.sh`
- Place test files with the `.bats` extension in a `test/` directory
- Load helper libraries with `bats_load_library` or `load` commands in each test file
- Use `setup_file` and `teardown_file` for one-time per-file initialization and cleanup
- Run tests in parallel with `bats --jobs N` for faster feedback

## Key Features
- Simple syntax using standard Bash test expressions and commands
- TAP-compliant output that works with any TAP consumer or CI system
- Test isolation via subshells preventing state leakage between tests
- Parallel test execution with the `--jobs` flag
- Official helper libraries: bats-assert for assertions, bats-file for filesystem checks, bats-support for utilities

## Comparison with Similar Tools
- **ShellCheck** — a static linter for shell scripts; Bats is a runtime test framework that verifies behavior
- **shunit2** — an older xUnit-style testing framework for Bash; Bats offers simpler syntax and TAP output
- **BATS (original)** — the unmaintained predecessor; bats-core is the actively maintained community fork
- **pytest with subprocess** — usable for testing CLI tools from Python; Bats keeps tests in native Bash

## FAQ
**Q: Can Bats test any command-line program, not just Bash scripts?**
A: Yes. Bats can test any program that runs from the command line. Tests invoke commands and check exit codes and output.

**Q: How do I share setup across multiple test files?**
A: Use `setup_file` and `teardown_file` within each file, or create a common helper file loaded with the `load` command.

**Q: Does Bats support test filtering?**
A: Yes. Use `bats --filter "pattern"` to run only tests whose names match the given regex.

**Q: Can I generate JUnit XML output for CI?**
A: Yes. Use the `--formatter junit` flag or the `bats-junit-formatter` to produce JUnit-compatible XML reports.

## Sources
- https://github.com/bats-core/bats-core
- https://bats-core.readthedocs.io/

---
Source: https://tokrepo.com/en/workflows/asset-8279ffce
Author: AI Open Source