### Setup for Echo Server

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

Defines the setup for an echo server test. It loads common setup, starts the server, and exports the port. This function runs once before all tests in the file.

```bash
setup_file() {
    load 'test_helper/common-setup'
    _common_setup
    PORT=$(project.sh start-echo-server 2>&1 >/dev/null)
    export PORT
}

@test "server is reachable" {
    nc -z localhost "$PORT"
}
```

--------------------------------

### Install Bats from Source

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/installation.md

Clone the Bats repository and use the install script to install Bats from source to a specified prefix.

```bash
$ git clone https://github.com/bats-core/bats-core.git
$ cd bats-core
$ ./install.sh /usr/local
```

--------------------------------

### Install Bats on Ubuntu

Source: https://github.com/bats-core/bats-core/wiki/Install-Bats-Using-a-Package

Installs Bats on Ubuntu by adding a PPA, updating package lists, and then installing the bats package.

```bash
sudo add-apt-repository ppa:duggan/bats
sudo apt-get update
sudo apt-get install bats
```

--------------------------------

### Setup and Teardown Hooks Order

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/writing-tests.md

Illustrates the execution order of setup, teardown, setup_file, teardown_file, setup_suite, and teardown_suite hooks in a multi-file test suite.

```text
setup_suite # from setup_suite.bash
  setup_file # from file 1, on entering file 1
    setup
      test1
    teardown
    setup
      test2
    teardown
  teardown_file # from file 1, on leaving file 1
  setup_file # from file 2,  on enter file 2
    setup
      test3
    teardown
  teardown_file # from file 2,  on leaving file 2
teardown_suite # from setup_suite.bash
```

--------------------------------

### Load helper libraries in Bats

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/faq.md

Helper libraries like bats-assert can be loaded using the 'load' function within the setup() function. Ensure the library is installed in a 'test_helper' directory.

```bash
setup() {
    load 'test_helper/bats-support/load' # this is required by bats-assert!
    load 'test_helper/bats-assert/load'
}

@test "test" {
    run echo test
    assert_output "test"
}
```

--------------------------------

### Install Bats from Source on Windows with Git Bash

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/installation.md

Clone the Bats repository and use the install script to install Bats from source to the HOME directory on Windows using Git Bash.

```bash
$ git clone https://github.com/bats-core/bats-core.git
$ cd bats-core
$ ./install.sh $HOME
```

--------------------------------

### Main Test File Setup

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

This bats test file sets up the testing environment by loading the common setup script. It ensures that shared configurations and paths are available for tests.

```bats
setup() {
    load 'test_helper/common-setup'
    _common_setup
}

```

--------------------------------

### Install Bats on openSUSE

Source: https://github.com/bats-core/bats-core/wiki/Install-Bats-Using-a-Package

Installs Bats on openSUSE using the zypper package manager.

```bash
zypper install bats
```

--------------------------------

### Load Bats Libraries in Setup

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/docker-usage.md

Loads the bats-support and bats-assert libraries within the setup function of a bats test file.

```bash
setup() {
    bats_load_library bats-support
    bats_load_library bats-assert
}
```

--------------------------------

### Alpine Linux Package Update Example

Source: https://github.com/bats-core/bats-core/blob/master/docs/releasing.md

Example of how to prepare an Alpine Linux package for a new Bats version, including fetching the zip archive and calculating its SHA512 sum.

```bash
curl -LOv https://github.com/bats-core/bats-core/archive/v1.1.0.zip
openssl sha512 v1.1.0.zip
```

--------------------------------

### Install Bats in Dockerfile

Source: https://github.com/bats-core/bats-core/wiki/Install

Integrate Bats into a Docker image by installing a specific tagged release. This example is suitable for Debian-based images.

```dockerfile
... 
# Set tagged release version of Bats to use. This could be also set in docker-compose.
ARG BATS_VERSION="1.7.0"

# Install bats
RUN batstmp="$(mktemp -d bats-core-${BATS_VERSION}.XXXX)" \
    && echo ${batstmp} \
    && cd ${batstmp} \
    && curl -SLO https://github.com/bats-core/bats-core/archive/refs/tags/v${BATS_VERSION}.tar.gz \
    && tar -zxvf v${BATS_VERSION}.tar.gz \
    && bash bats-core-${BATS_VERSION}/install.sh /usr/local \
    && rm -rf "${batstmp}"


```

--------------------------------

### Common Test Setup Script

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

This bash script provides common setup routines for tests, including loading bats support libraries and setting up the project root path. It's designed to be loaded by other test files.

```bash
#!/usr/bin/env bash

_common_setup() {
    load 'test_helper/bats-support/load'
    load 'test_helper/bats-assert/load'
    # get the containing directory of this file
    # use $BATS_TEST_FILENAME instead of ${BASH_SOURCE[0]} or $0,
    # as those will point to the bats executable's location or the preprocessed file respectively
    PROJECT_ROOT="$( cd "$( dirname "$BATS_TEST_FILENAME" )/.." >/dev/null 2>&1 && pwd )"
    # make executables in src/ visible to PATH
    PATH="$PROJECT_ROOT/src:$PATH"
}

```

--------------------------------

### Install Bats with npm

Source: https://github.com/bats-core/bats-core/wiki/Install-Bats-Using-a-Package

Installs the bats-core npm package globally using npm.

```bash
$ npm install -g bats
```

--------------------------------

### Install Bats Core with Homebrew on macOS

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/installation.md

Use this command to install Bats Core if you have Homebrew installed on macOS.

```bash
$ brew install bats-core
```

--------------------------------

### Setup Function to Add Script Directory to PATH

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

Define a setup function within the test file to add the script's directory to the system's PATH. This allows scripts to be called without specifying their relative path.

```bash
setup() {
    # get the containing directory of this file
    # use $BATS_TEST_FILENAME instead of ${BASH_SOURCE[0]} or $0,
    # as those will point to the bats executable's location or the preprocessed file respectively
    DIR="$( cd "$( dirname "$BATS_TEST_FILENAME" )" >/dev/null 2>&1 && pwd )"
    # make executables in src/ visible to PATH
    PATH="$DIR/../src:$PATH"
}

@test "can run our script" {
    # notice the missing ./
    # As we added src/ to $PATH, we can omit the relative path to `src/project.sh`.
    project.sh
}
```

--------------------------------

### Install Newer Bats-core on Alpine Linux

Source: https://github.com/bats-core/bats-core/wiki/Install-Bats-Using-a-Package

Installs the newer bats-core version on Alpine Linux by downloading, unzipping, and installing from source.

```bash
sudo apk add coreutils ncurses
curl -#L https://github.com/bats-core/bats-core/archive/master.zip | unzip - 
sudo bash bats-core-master/install.sh /usr/local
rm -rf ./bats-core-master
```

--------------------------------

### Install Bats with bpkg

Source: https://github.com/bats-core/bats-core/wiki/Install-Bats-Using-a-Package

Installs the bats-core package globally using the bpkg package manager.

```bash
$ bpkg install -g bats-core/bats-core
```

--------------------------------

### Bats Test Setup with Load Paths

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

Configures the Bats test environment by loading necessary helper libraries and setting up the PATH to include executables from the src directory.

```bash
setup() {
    load 'test_helper/bats-support/load'
    load 'test_helper/bats-assert/load'
    # ... the remaining setup is unchanged

    # get the containing directory of this file
    # use $BATS_TEST_FILENAME instead of ${BASH_SOURCE[0]} or $0,
    # as those will point to the bats executable's location or the preprocessed file respectively
    DIR="$( cd "$( dirname "$BATS_TEST_FILENAME" )" >/dev/null 2>&1 && pwd )"
    # make executables in src/ visible to PATH
    PATH="$DIR/../src:$PATH"
}
```

--------------------------------

### Install Bats from GitHub Branch Archive

Source: https://github.com/bats-core/bats-core/wiki/Install

Download and install Bats from the master branch archive. Use this for the latest development version.

```bash
branch=master
batstmp="$(mktemp -d bats-core-"${branch}".XXXXX)"
pushd "${batstmp}" &> /dev/null || return 11
curl -sSLO https://github.com/bats-core/bats-core/archive/refs/heads/"${branch}".zip
unzip -qo "${branch}".zip
sudo bash "${batstmp}"/bats-core-"${branch}"/install.sh /usr/local
popd &> /dev/null || return 12
command -v bats && rm -rf "${batstmp}"
```

--------------------------------

### Example Announcement Text

Source: https://github.com/bats-core/bats-core/blob/master/docs/releasing.md

An example announcement for a new Bats version, suitable for platforms like Gitter, highlighting availability on Homebrew and NPM, and its eventual inclusion in Alpine Linux.

```text
v1.1.0 is now available via Homebrew and npm:
https://github.com/bats-core/bats-core/releases/tag/v1.1.0

It'll eventually be available in Alpine via the edge branch of the community
repo once alpinelinux/aports#4696 gets merged. (Check /etc/apk/repositories to
ensure this repo is enabled.)
```

--------------------------------

### Install Bats on Fedora

Source: https://github.com/bats-core/bats-core/wiki/Install-Bats-Using-a-Package

Installs Bats on Fedora using the dnf package manager.

```bash
sudo dnf install bats
```

--------------------------------

### Install Bats on macOS

Source: https://github.com/bats-core/bats-core/wiki/Install-Bats-Using-a-Package

Installs Bats on macOS using the Homebrew package manager.

```bash
brew install bats-core
```

--------------------------------

### Install Bats from GitHub Release

Source: https://github.com/bats-core/bats-core/wiki/Install

Download and install a specific tagged release of Bats from GitHub. This method is suitable for reproducible builds.

```bash
tag=1.1.0
batstmp="$(mktemp -d bats-core-"${tag}".XXXXX)"
pushd "${batstmp}" &> /dev/null || return 11
curl -sSLO https://github.com/bats-core/bats-core/archive/refs/tags/v"${tag}".tar.gz
tar -zxvf v"${tag}".tar.gz
sudo bash "${batstmp}"/bats-core-"${tag}"/install.sh /usr/local
popd &> /dev/null || return 12
command -v bats && rm -rf "${batstmp}"
```

--------------------------------

### Install Bats with Basher

Source: https://github.com/bats-core/bats-core/wiki/Install-Bats-Using-a-Package

Installs the GIT master version of bats-core/bats-core using the Basher package manager. Set BASHER_FULL_CLONE=true for full clone.

```bash
basher install bats-core/bats-core
```

--------------------------------

### Install Bats on Arch Linux

Source: https://github.com/bats-core/bats-core/wiki/Install-Bats-Using-a-Package

Installs the bats-core package on Arch Linux using an AUR helper like pacaur.

```bash
pacaur -Sa bats-core
```

--------------------------------

### Install Bats as Root using GNU Stow

Source: https://github.com/bats-core/bats-core/wiki/Install-Bats-Using-GNU-Stow

Installs Bats to a system-wide Stow directory. This method requires root privileges and ensures older versions are removed before installing the new one.

```bash
stow=/usr/local/stow
version=$(libexec/bats -v | tr A-Z a-z | tr ' ' -)

# Unstow older versions of Bats.
shopt -s nullglob
old_bats=(`find "$stow" -type d -name bats-*")
for package in "${old_bats[@]}"; do
    sudo stow --dir="$stow" --delete $(basename "$package")
done

sudo ./install.sh "${stow}/${version}"
sudo stow --dir="$stow" --restow "$version"
```

--------------------------------

### Install Bats npm Package Globally

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/installation.md

Install the Bats npm package globally for system-wide access.

```bash
# To install globally:
$ npm install -g bats
```

--------------------------------

### Test for Helper Script

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

This bats test file loads common setup and tests the `_is_first_run` function from the helper script. It uses temporary files to simulate different run states.

```bats
setup() {
    load 'test_helper/common-setup'
    _common_setup

    source "$PROJECT_ROOT/src/helper.sh"
}

teardown() {
    rm -f "$NON_EXISTENT_FIRST_RUN_FILE"
    rm -f "$EXISTING_FIRST_RUN_FILE"
}

@test "Check first run" {
    NON_EXISTENT_FIRST_RUN_FILE=$(mktemp -u) # only create the name, not the file itself

    assert _is_first_run "$NON_EXISTENT_FIRST_RUN_FILE"
    refute _is_first_run "$NON_EXISTENT_FIRST_RUN_FILE"
    refute _is_first_run "$NON_EXISTENT_FIRST_RUN_FILE"

    EXISTING_FIRST_RUN_FILE=$(mktemp)
    refute _is_first_run "$EXISTING_FIRST_RUN_FILE"
    refute _is_first_run "$EXISTING_FIRST_RUN_FILE"
}

```

--------------------------------

### Load a test helper library

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/writing-tests.md

Use `bats_load_library` to load system-wide libraries. Set `BATS_LIB_PATH` to a colon-delimited list of directories where libraries are installed.

```bash
bats_load_library test_helper
```

--------------------------------

### Echo Server Implementation

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

Provides the implementation for starting an echo server using ncat. It listens on a specified port and echoes received data. The process ID is stored for later termination.

```bash
case $1 in
    start-echo-server) 
        echo "Starting echo server"
        PORT=2000
        ncat -l $PORT -k -c 'xargs -n1 echo' 2>/dev/null & 
        echo $! > /tmp/project-echo-server.pid
        echo "$PORT" >&2
    ;; 
    *) 
        echo "NOT IMPLEMENTED!" >&2
        exit 1
    ;; 
esac
```

--------------------------------

### Install Old Bats on Alpine Linux

Source: https://github.com/bats-core/bats-core/wiki/Install-Bats-Using-a-Package

Installs the older version of Bats on Alpine Linux, requiring coreutils and optionally ncurses for pretty output.

```bash
# coreutils is needed because busybox `readlink` is not supported by BATS
sudo apk add coreutils bats
sudo apk add ncurses # Needed to support 'pretty' output
```

--------------------------------

### Demonstrate Locale-Specific Signal Error

Source: https://github.com/bats-core/bats-core/blob/master/docs/CONTRIBUTING.md

This example demonstrates how using lowercase signal names can lead to errors in specific locales, while uppercase names work correctly.

```bash
echo "tr_TR.UTF-8 UTF-8" >> /etc/locale.gen && locale-gen tr_TR.UTF-8 # Ubuntu derivatives
LC_CTYPE=tr_TR.UTF-8 LC_MESSAGES=C bash -c 'trap - int && echo success'
bash: line 0: trap: int: invalid signal specification
LC_CTYPE=tr_TR.UTF-8 LC_MESSAGES=C bash -c 'trap - INT && echo success'
success

```

--------------------------------

### Homebrew Formula Update Example

Source: https://github.com/bats-core/bats-core/blob/master/docs/releasing.md

Example of how to update a Homebrew formula for a new Bats version, including fetching the tarball, calculating its SHA256 sum, and using 'brew bump-formula-pr'.

```bash
curl -LOv https://github.com/bats-core/bats-core/archive/v1.1.0.tar.gz
openssl sha256 v1.1.0.tar.gz
# Add the --dry-run flag to see the individual steps without executing.
brew bump-formula-pr \
  --url=https://github.com/bats-core/bats-core/archive/v1.1.0.tar.gz \
  --sha256=855d8b8bed466bc505e61123d12885500ef6fcdb317ace1b668087364717ea82
```

--------------------------------

### Install Bats npm Package as a Dev Dependency

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/installation.md

Install the Bats npm package into your project and save it as a dev dependency in package.json.

```bash
# To install into your project and save it as one of the "devDependencies" in
# your package.json:
$ npm install --save-dev bats
```

--------------------------------

### Run Bats Tests

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/usage.md

Example of invoking Bats to run test files. Specify paths to .bats files or directories containing them. The -r flag enables recursive searching.

```bash
$ bats addition.bats
```

--------------------------------

### Example Bats Warning Output

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/warnings/index.md

Demonstrates the typical output format for Bats warnings, which appear on stderr after all other test results. This example shows a BW01 warning.

```bash
BW01.bats
✓ Trigger BW01

1 test, 0 failures


The following warnings were encountered during tests:
BW01: `run`'s command `=0 actually-intended-command with some args` exited with code 127, indicating 'Command not found'. Use run's return code checks, e.g. `run -127`, to fix this message.
      (from function `run' in file lib/bats-core/test_functions.bash, line 299,
       in test file test/fixtures/warnings/BW01.bats, line 3)

```

--------------------------------

### Install Bats as User using GNU Stow

Source: https://github.com/bats-core/bats-core/wiki/Install-Bats-Using-GNU-Stow

Installs Bats to a user-specific Stow directory. This method does not require root privileges and allows for clean management of Bats versions within the user's home directory.

```bash
mkdir ~/stow
stow=~/stow
version=$(libexec/bats -v | tr A-Z a-z | tr ' ' -)

# Unstow older versions of Bats.
shopt -s nullglob
old_bats=(`find "$stow" -type d -name bats-*")
for package in "${old_bats[@]}"; do
    stow --dir="$stow" --delete $(basename "$package")
done

./install.sh "${stow}/${version}"
stow --dir="$stow" --restow "$version"
```

--------------------------------

### Travis CI - Add Bats Dependency

Source: https://github.com/bats-core/bats-core/wiki/Install

Configure Travis CI to install Bats from the master branch for testing builds. Ensures Bats is in the PATH.

```yaml
language: bash
dist: xenial
#addons:
#  apt:
#    update: true
#    packages:
#    - xz-utils
#    - pv

env:
  global:
  - export PATH="/usr/local/bin:$PATH"

before_install:
- | 
  if [ "$TRAVIS_OS_NAME" = "linux" ]; then
    branch=master
    batstmp="$(mktemp -d bats-core-"${branch}".XXXX)"
    pushd "${batstmp}" &> /dev/null || return 11
    curl -sSLO https://github.com/bats-core/bats-core/archive/refs/heads/"${branch}".zip
    unzip -qo "${branch}".zip
    sudo bash "${batstmp}"/bats-core-"${branch}"/install.sh /usr/local
    popd &> /dev/null || return 12
  fi

script:
  - bats test/test.bats

```

--------------------------------

### Set test timeout

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/faq.md

A test timeout can be set by defining the $BATS_TEST_TIMEOUT variable before setup() begins. This can be done on the command line, in free code, or in setup_file().

```bash
# Example of setting timeout in setup_file()
setup_file() {
  export BATS_TEST_TIMEOUT=5 # 5 seconds
}
```

--------------------------------

### Bats Test with Piped Output Filtering

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

Demonstrates a common pitfall where piping the output of `run` prevents the pipe from being correctly interpreted. This example shows the incorrect usage.

```bash
run project.sh 2>&1 | grep Welcome
```

--------------------------------

### Create and Make Project Script Executable

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

Create the project script file and set its execute permissions. This is a prerequisite for the test to pass.

```console
mkdir src/
echo '#!/usr/bin/env bash' > src/project.sh
chmod a+x src/project.sh
```

--------------------------------

### Run All Tests

Source: https://github.com/bats-core/bats-core/blob/master/docs/CONTRIBUTING.md

Execute all test suites in the project. Ensure your environment is set up correctly before running tests.

```sh
bin/bats test
```

--------------------------------

### Basic Bats Test Cases

Source: https://github.com/bats-core/bats-core/blob/master/README.md

Demonstrates how to define test cases in a Bats test file using special syntax for test descriptions and assertions.

```bash
#!/usr/bin/env bats

@test "addition using bc" {
  result="$(echo 2+2 | bc)"
  [ "$result" -eq 4 ]
}

@test "addition using dc" {
  result="$(echo 2 2+p | dc)"
  [ "$result" -eq 4 ]
}
```

--------------------------------

### Initial Test Case for Nonexistent Script

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

Write a basic test case to verify if a script can be executed. This test will initially fail as the script does not exist.

```bash
@test "can run our script" {
    ./project.sh
}
```

--------------------------------

### Build and Run Bats Project Tests with Docker

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/docker-usage.md

Clones the bats-core repository, builds the bats Docker image, and then runs tests within the container using the TAP formatter.

```bash
$ git clone https://github.com/bats-core/bats-core.git
Cloning into 'bats-core'...
remote: Counting objects: 1222, done.
remote: Compressing objects: 100% (53/53), done.
remote: Total 1222 (delta 34), reused 55 (delta 21), pack-reused 1146
Receiving objects: 100% (1222/1222), 327.28 KiB | 1.70 MiB/s, done.
Resolving deltas: 100% (661/661), done.

$ cd bats-core/
$ docker build --tag bats/bats:latest .
...
$ docker run -it bats/bats:latest --formatter tap /opt/bats/test
```

--------------------------------

### Build and Run Bats Docker Image

Source: https://github.com/bats-core/bats-core/wiki/Docker-Usage-Examples

Builds the Bats Docker image from the current directory and runs its tests using the --tap option. Useful for testing the Bats framework itself.

```bash
$ git clone https://github.com/bats-core/bats-core.git
Cloning into 'bats-core'...
remote: Counting objects: 1222, done.
remote: Compressing objects: 100% (53/53), done.
remote: Total 1222 (delta 34), reused 55 (delta 21), pack-reused 1146
Receiving objects: 100% (1222/1222), 327.28 KiB | 1.70 MiB/s, done.
Resolving deltas: 100% (661/661), done.

$ cd bats-core/
$ docker build --tag bats/bats:latest .
...
$ docker run -it --rm bats/bats:latest --tap /opt/bats/test
```

--------------------------------

### Run Local Test Suite with Docker

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/installation.md

Run a local test suite from your machine within a Docker container by mounting the current directory.

```bash
$ docker run -it -v "${PWD}:/code" bats/bats:latest test
```

--------------------------------

### Load a specific file from a library

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/writing-tests.md

To load a specific file or entry point within a library, append the file name to the library name, separated by a slash. This allows for more granular control over library loading.

```bash
bats_load_library library_name/file_to_load
```

--------------------------------

### Use Custom Formatter

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/usage.md

You can use your own custom formatter by providing an absolute path to the formatter executable with the `--formatter` option.

```bash
$ bats --formatter /absolute/path/to/my-formatter addition.bats
addition using bc WORKED
addition using dc FAILED
```

--------------------------------

### Run a command and assert its status and output

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/writing-tests.md

Use the `run` helper to execute a command and capture its exit status, output, and the command itself. Assertions can then be made on the `$status`, `$output`, and `$BATS_RUN_COMMAND` variables.

```bash
run foo nonexistent_filename
[ "$status" -eq 1 ]
[ "$output" = "foo: no such file 'nonexistent_filename'" ]
[ "$BATS_RUN_COMMAND" = "foo nonexistent_filename" ]
```

--------------------------------

### Build Bats Docker Image

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/installation.md

Build a local Docker image for Bats Core from its repository.

```bash
$ git clone https://github.com/bats-core/bats-core.git
$ cd bats-core
$ docker build --tag bats/bats:latest .
```

--------------------------------

### Bats Command Line Options

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/usage.md

Displays all available command-line options for the Bats interpreter. Use -h or --help to invoke.

```text
Bats 1.13.0
Usage: bats [OPTIONS] <tests>
       bats [-h | -v]

  <tests> is the path to a Bats test file, or the path to a directory
  containing Bats test files (ending with ".bats")

  --abort                   Stop execution of suite on first failed test
  -c, --count               Count test cases without running any tests
  --code-quote-style <style>
                            A two character string of code quote delimiters
                            or 'custom' which requires setting $BATS_BEGIN_CODE_QUOTE and
                            $BATS_END_CODE_QUOTE. Can also be set via $BATS_CODE_QUOTE_STYLE
  --line-reference-format   Controls how file/line references e.g. in stack traces are printed:
                              - comma_line (default): a.bats, line 1
                              - colon:  a.bats:1
                              - uri: file:///tests/a.bats:1
                              - custom: provide your own via defining bats_format_file_line_reference_custom
                                        with parameters <filename> <line>, store via `printf -v "$output"`
  -f, --filter <regex>      Only run tests that match the regular expression
  --negative-filter <regex> Only run tests that do not match the regular expression
  --filter-status <status>  Only run tests with the given status in the last completed (no CTRL+C/SIGINT) run.
                            Valid <status> values are:
                              failed - runs tests that failed or were not present in the last run
                              missed - runs tests that were not present in the last run
  --filter-tags <comma-separated-tag-list>
                            Only run tests that match all the tags in the list (&&).
                            You can negate a tag via prepending '!'.
                            Specifying this flag multiple times allows for logical or (||):
                            `--filter-tags A,B --filter-tags A,!C` matches tags (A && B) || (A && !C)
  -F, --formatter <type>    Switch between formatters: pretty (default),
                              tap (default w/o term), tap13, junit, /<absolute path to formatter>
  --gather-test-outputs-in <directory>
                            Gather the output of failing *and* passing tests
                            as files in directory (if existing, must be empty)
  -h, --help                Display this help message
  -j, --jobs <jobs>         Number of parallel jobs (requires GNU parallel or shenwei356/rush)
  --parallel-binary-name    Name of parallel binary
  --no-tempdir-cleanup      Preserve test output temporary directory
  --errexit                 Enable errexit (set -e) for commands run in `run`
  --no-parallelize-across-files
                            Serialize test file execution instead of running
                            them in parallel (requires --jobs >1)
  --no-parallelize-within-files
                            Serialize test execution within files instead of
                            running them in parallel (requires --jobs >1)
  --report-formatter <type> Switch between reporters (same options as --formatter)
  -o, --output <dir>        Directory to write report files (must exist)
  -p, --pretty              Shorthand for "--formatter pretty"
  --print-output-on-failure Automatically print the value of `$output` on failed tests
  -r, --recursive           Include tests in subdirectories
  --show-output-of-passing-tests
                            Print output of passing tests
  -t, --tap                 Shorthand for "--formatter tap"
  -T, --timing              Add timing information to tests
  -x, --trace               Print test commands as they are executed (like `set -x`)
  --verbose-run             Make `run` print `$output` by default
  -v, --version             Display the version number

  For more information, see https://github.com/bats-core/bats-core
```

--------------------------------

### Run a Single Test File

Source: https://github.com/bats-core/bats-core/blob/master/docs/CONTRIBUTING.md

Execute a specific test file. Useful for debugging or focusing on a particular test case.

```sh
bin/bats test/file.bats
```

--------------------------------

### Shell Script with File-Based State

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

This shell script implements logic to display a welcome message only on the first execution by checking for the existence of a specific file. It also echoes a 'NOT IMPLEMENTED!' message to stderr and exits with a non-zero status.

```bash
#!/usr/bin/env bash

FIRST_RUN_FILE=/tmp/bats-tutorial-project-ran

if [[ ! -e "$FIRST_RUN_FILE" ]]; then
    echo "Welcome to our project!"
    touch "$FIRST_RUN_FILE"
fi

echo "NOT IMPLEMENTED!" >&2
exit 1
```

--------------------------------

### Running Bats Tests

Source: https://github.com/bats-core/bats-core/blob/master/README.md

Command to execute Bats tests in TAP (Test Anything Protocol) format.

```sh
bin/bats --tap test
```

--------------------------------

### Run Bats Project Tests with Mounted Volume

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/docker-usage.md

Builds the bats Docker image and then runs tests from the mounted bats-core repository within the container.

```bash
$ docker run -it -v "$PWD:/opt/bats" bats/bats:latest /opt/bats/test
```

--------------------------------

### Run Bats Tests by Mounting Local Directory

Source: https://github.com/bats-core/bats-core/wiki/Docker-Usage-Examples

Mounts the current working directory into the Bats Docker container at /opt/bats and executes tests within that directory. Useful for running tests for a project directly from your local machine.

```bash
$ docker run -it -v "$(pwd):/opt/bats" --workdir /opt/bats bats/bats:latest test
```

--------------------------------

### Basic Script with Error Output

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

A simple bash script that prints a welcome message to stdout and an error message to stderr, then exits with a non-zero status.

```bash
#!/usr/bin/env bash

echo "Welcome to our project!"

echo "NOT IMPLEMENTED!" >&2
exit 1
```

--------------------------------

### Load common code from a file

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/writing-tests.md

Use the `load` command to source Bash script files relative to the current test file or from absolute paths. Errors during loading will cause Bats to exit.

```bash
load test_helper.bash
```

--------------------------------

### Run Bats Version with Docker

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/installation.md

Execute the Bats version command using the official Bats Docker image.

```bash
$ docker run -it bats/bats:latest --version
```

--------------------------------

### Generate and Output Report Files

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/usage.md

Use `--report-formatter` to generate test report files and `--output` to specify the directory where the report should be stored. By default, reports are saved in the current working directory.

```text
$ bats --report-formatter junit addition.bats --output /tmp
1..2
ok 1 addition using bc
ok 2 addition using dc
```

```xml
<?xml version="1.0" encoding="UTF-8"?>
<testsuites time="0.073">
<testsuite name="addition.bats" tests="2" failures="0" errors="0" skipped="0">
    <testcase classname="addition.bats" name="addition using bc" time="0.034" />
    <testcase classname="addition.bats" name="addition using dc" time="0.039" />
</testsuite>
</testsuites>
```

--------------------------------

### Bats Test Using a Helper Function for Piped Output

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

A workaround for piping output with `run` by encapsulating the command and its piping within a helper function. This ensures the pipe is correctly processed.

```bash
get_projectsh_welcome_message() {
    project.sh  2>&1 | grep Welcome
}

@test "Check welcome message" {
    run get_projectsh_welcome_message
    assert_output 'Welcome to our project!'
```

--------------------------------

### Helper Script Functionality

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

This bash script defines a function to check if a file exists, indicating a first run. It's intended to be sourced by test files.

```bash
#!/usr/bin/env bash

_is_first_run() {
    local FIRST_RUN_FILE=${1-/tmp/bats-tutorial-project-ran}
    if [[ ! -e "$FIRST_RUN_FILE" ]]; then
        touch "$FIRST_RUN_FILE"
        return 0
    fi
    return 1
}

```

--------------------------------

### Show All Unique Contributors for a File

Source: https://github.com/bats-core/bats-core/wiki/Git-Codebook

Lists all unique contributors for a specified file. It uses 'git log' to retrieve author emails and sorts them uniquely.

```sh
git log --reverse -1 --format='%aE' [--follow] <File> | sort -u
```

--------------------------------

### Loading `.sh` Files with `load`

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/gotchas.md

The `load` function is intended for `.bash` files and appends `.bash` by default. Use `source` to load standard `.sh` files.

```bash
# To load a .sh file:
source my_script.sh
```

--------------------------------

### Create Signed Git Tag

Source: https://github.com/bats-core/bats-core/blob/master/docs/releasing.md

Create a new signed, annotated Git tag for the release. The tag annotation should include changelog notes, formatted appropriately.

```bash
git tag -a -s <VERSION>
```

--------------------------------

### Push New Version Commit and Tag to GitHub

Source: https://github.com/bats-core/bats-core/blob/master/docs/releasing.md

Push the commit containing version updates and the new tag to GitHub to prepare for creating a release.

```bash
git push --follow-tags
```

--------------------------------

### Skip a test with a reason

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/writing-tests.md

Provide a reason for skipping a test by passing a string argument to the `skip` command. This reason will be displayed when the test is skipped.

```bash
@test "A test I don't want to execute for now" {
  skip "This command will return zero soon, but not now"
  run foo
  [ "$status" -eq 0 ]
}
```

--------------------------------

### Test command failure using run !

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/writing-tests.md

Use `run !` to test that a command fails (exits with a non-zero status). This is the recommended way to test command failures, as Bash's `!` operator behavior with `set -e` can be counterintuitive.

```bash
run ! command args ...
```

--------------------------------

### Publish to NPM

Source: https://github.com/bats-core/bats-core/blob/master/docs/releasing.md

Publish the new version of Bats to the NPM registry. For verification, 'npm pack' can be used to test the tarball locally before publishing.

```bash
npm publish
```

--------------------------------

### Conditional Test Execution Based on Bats Version

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/warnings/BW02.md

Demonstrates how to use `bats_require_minimum_version` to conditionally execute tests. The first test requires Bats 1.5.0 or higher, while the second test has no version dependency.

```bash
@test test {
    bats_require_minimum_version 1.5.0
    # pre 1.5.0 the flag --separate-stderr would be interpreted as command to run
    run --separate-stderr some-command
    [ $output = "blablabla" ]
}

@test test2 {
    run some-other-command # no problem executing on earlier version
}
```

--------------------------------

### Add Bats and Libraries as Git Submodules

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

Include bats and its testing libraries (bats-support, bats-assert) as submodules in your project to manage dependencies.

```console
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
```

--------------------------------

### Handling Negated Statements with `run`

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/gotchas.md

For negated commands that should fail a test, use `run !` on Bats 1.5.0+ or `! x || false` for older versions. This ensures the test fails as expected.

```bash
# For Bats 1.5.0 and above:
run ! some_command

# For older Bats versions:
! some_command || false
```

--------------------------------

### Run Bats Internal Test Suite with Docker

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/installation.md

Execute the internal test suite of Bats within its Docker container.

```bash
$ docker run -it bats/bats:latest /opt/bats/test
```

--------------------------------

### Corrected Test Case with Script Path

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

Update the test case to use the correct relative path to the project script after creating the script file.

```bash
@test "can run our script" {
    ./src/project.sh
}
```

--------------------------------

### Run Isolated Bats Test Suite

Source: https://github.com/bats-core/bats-core/wiki/Docker-Usage-Examples

Mounts only the 'test' directory from the current working directory into the Bats Docker container at /test and executes the tests. Suitable for test suites that do not depend on project files outside the test directory.

```bash
$ docker run -it -v "$(pwd)/test:/test" bats/bats:latest /test
```

--------------------------------

### Show Original Committer for a File

Source: https://github.com/bats-core/bats-core/wiki/Git-Codebook

Retrieves the author email of the original committer for a file, following its history.

```sh
git log -n1 --follow --format='%aE' <File>
```

--------------------------------

### Test command success using run -0

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/writing-tests.md

Use `run -0` to explicitly test that a command succeeds (exits with status 0). This is equivalent to simply running the command directly, as Bats sets `set -e` by default.

```bash
run -0 command args ...
```

--------------------------------

### Use the 'cat' Formatter for Debugging

Source: https://github.com/bats-core/bats-core/blob/master/docs/CONTRIBUTING.md

Run Bats with the 'cat' formatter to view raw test output. This is an internal debugging tool and does not process test outputs.

```sh
bin/bats --formatter cat
```

--------------------------------

### Bats Test Asserting Partial Output

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

Uses the `--partial` option with `assert_output` to check if a specific substring exists within the script's output, rather than requiring an exact match. This test passes if 'Welcome to our project!' is found anywhere in the output.

```bash
@test "Check welcome message" {
    run project.sh
    assert_output --partial 'Welcome to our project!'
```

--------------------------------

### Run Bats Tests in Docker with Mounted Volume

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/docker-usage.md

Mounts the current directory to /code inside the container and runs tests located at /code/test. Useful for isolated test suites.

```bash
$ docker run -it -v "$PWD:/code" bats/bats:latest /code/test
```

--------------------------------

### Run a command expecting a specific non-zero exit status

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/writing-tests.md

Use `run -N` where N is the expected exit status. This is a shorthand for checking if a command fails with a specific status code.

```bash
run -1 foo nonexistent_filename
[ "$output" = "foo: no such file 'nonexistent_filename'" ]
```

--------------------------------

### Bash Test with Conditional Skipping

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/tutorial.md

This Bash script demonstrates how to conditionally skip a test if a prerequisite file already exists. It includes a `teardown` function that does nothing and a test that checks for a file before running the main test logic.

```bash
teardown() {
    : # Look Ma! No cleanup!
}

@test "Show welcome message on first invocation" {
    if [[ -e /tmp/bats-tutorial-project-ran ]]; then
        skip 'The FIRST_RUN_FILE already exists'
    fi

    run project.sh
    assert_output --partial 'Welcome to our project!'

    run project.sh
    refute_output --partial 'Welcome to our project!'
}
```

--------------------------------

### Define test-specific tags

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/writing-tests.md

Use the `# bats test_tags=` directive to assign tags to the immediately following test case. Tags are comma-separated.

```bash
# bats test_tags=tag:1, tag:2, tag:3
@test "first test" {
  # ...
}

@test "second test" {
  # ...
}
```

--------------------------------

### Test Execution Output

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/usage.md

Shows the typical output when running Bats tests from a terminal, indicating passed tests with a checkmark.

```text
 ✓ addition using bc
```

--------------------------------

### Show Contributions for Current File Version

Source: https://github.com/bats-core/bats-core/wiki/Git-Codebook

Displays the author email and ISO datetime of the commit for the current file version. It iterates through unique commit SHAs found by 'git blame'.

```sh
git blame "$1" | cut -d' ' -f 1 | sort -u | while read sha1; do
  git show -s --format="%aE %cI" $sha1
done
```

--------------------------------

### Passing Parameters via Environment Variables

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/gotchas.md

Bats does not support passing parameters directly to test files or tests, especially when using a shebang. Use environment variables as a workaround.

```bash
#!/usr/bin/env bats

@test "test with params" {
  # Access parameters via environment variables
  run printenv MY_PARAM
  [ "$output" = "my_value" ]
}

# To run: MY_PARAM=my_value bats your_test_file.bats
```

--------------------------------

### Prefer printf over echo

Source: https://github.com/bats-core/bats-core/blob/master/docs/CONTRIBUTING.md

Use `printf` instead of `echo` for generating output. `printf` offers more consistent behavior across different Bash versions and compilation methods.

```bash
printf "Hello, %s!\n" "World"

```

--------------------------------

### Use asserts instead of raw bash comparisons

Source: https://github.com/bats-core/bats-core/blob/master/docs/source/faq.md

For debugging failing tests, use Bats' built-in assert functions like assert_output and assert_success/assert_failure. These provide more informative output on failure compared to raw bash comparisons.

```bash
@test test {
    run echo test failed
    assert_output "test"
    # instead of
    [ "$output" = "test" ]
}
```

--------------------------------

### Markdown Comments

Source: https://github.com/bats-core/bats-core/wiki/GitHub-Syntax

Demonstrates various styles of comments in Markdown that are compatible with GitHub. These use the opaque part of a URI-ref to store comments.

```markdown
[//]: # "Here are some comment styles for you, using the opaque part of a URI-ref"
[//]: # "to store comments as references with unused reference ID's."
[//]: # (Compatible with online GitHub at least)
[//]: # (test test test)
```