bats-support

0.3.0 verified Sat Apr 25 auth: no javascript

bats-support is a supporting library for Bats (Bash Automated Testing System) test helpers, providing common functions for error reporting, output formatting, and language tools. Version 0.3.0 is the latest stable release with no active maintenance cadence announced. It serves as a dependency for higher-level assertion libraries like bats-assert, focusing on internal helper utilities rather than end-user assertions. Key differentiators include its lightweight shell implementation, strict adherence to Bats conventions, and compatibility with both Bats 0.4 and 1.x. The library was renamed from bats-core to bats-support, with GitHub redirects ensuring backward compatibility.

Common errors

error bats: load: bats-support/load: file not found ↓

cause bats-support is not installed or BATS_LIB_PATH is not set correctly.

fix

Install bats-support via git submodule or npm, and ensure BATS_LIB_PATH includes the parent directory of bats-support.

error bats: unknown option: --indirect ↓

cause Using an older version of bats-support that does not support the --indirect flag.

fix

Update bats-support to version 0.2.0 or later which introduced --indirect.

error TypeError: batslib_err is not a function ↓

cause Using Unix 'type' command or other shell that doesn't recognize batslib_err as a function (likely due to incorrect sourcing order).

fix

Ensure 'load bats-support/load' is placed before any calls to bats-support functions.

Warnings

breaking Repository renamed from bats-core to bats-support; all references (submodules, clones) redirect automatically but should be updated. ↓

fix Update git submodule and file references to the new repository URL: https://github.com/bats-core/bats-support.git

deprecated Direct sourcing of individual source files (e.g., 'source bats-support/src/output.bash') is deprecated; always use 'load'. ↓

fix Replace with: load 'bats-support/load'

gotcha The 'fail' function reads from stdin if no argument is provided; piping to fail without checking may lead to unexpected failures. ↓

fix Always supply a message argument unless you intentionally want to pipe input.

Install

npm install bats-support

yarn add bats-support

pnpm add bats-support

Imports

fail
wrong
```
source bats-support/load.bash
```
correct
```
load 'bats-support/load'
```
Use the Bats 'load' function to properly initialize all helpers; direct sourcing may cause path issues.
batslib_is_caller
wrong
```
source bats-support/src/caller.bash
```
correct
```
load 'bats-support/load'
```
All functions are exposed via the main load file; importing individual source files is incorrect and unsupported.
batslib_err
wrong
```
require 'bats-support'
```
correct
```
load 'bats-support/load'
```
This library is not a Node.js or Ruby gem; use 'load' from within a Bats test file, not a package manager.

Quickstart

Demonstrates loading bats-support, using fail helper for custom error messages, and batslib_is_caller for call stack inspection.

#!/usr/bin/env bats
load 'bats-support/load'

@test 'fail helper works' {
  run some-command
  if [ "$status" -ne 0 ]; then
    fail "Expected success, but command failed with status $status"
  fi
}

@test 'batslib_is_caller example' {
  run bash -c '
    function my_helper {
      batslib_is_caller --indirect "teardown" && echo "called from teardown"
    }
    my_helper
  '
  [ "$output" = "called from teardown" ]
}