Overview

This is a proposal describing how a Bats helper library should look and behave. These guidelines and the libraries following them resulted from the discussion about introducing a Standard Library of Test Helpers for Bats.

Topics:

Installation
Loading
Testing

Libraries:

bats-support (formerly bats-core) - supporting library for test helpers
bats-assert - common assertions
bats-file - filesystem related assertions

Installation

There are multiple supported installation methods. One may be better than the others depending on your case. Make sure to install the required dependencies as well (e.g. install bats-support when installing bats-assert).

npm

If your project is managed by npm, the recommended installation method is also via npm.

$ npm install --save-dev https://github.com/ztombol/bats-support
$ npm install --save-dev https://github.com/ztombol/bats-assert

Homebrew

OS X users can use Homebrew to install libraries system-wide (see note below for alternatives).

The forumlae are in a tap for various shell utilities by @kaos, so enable the tap kaos/shell first.

$ brew tap kaos/shell

Then install the desired libraries.

$ brew install bats-assert
$ brew install bats-file

Note: The required dependencies, bats-support as well as bats from the core tap will be installed automatically for you, with any of the two previous commands.

Note: Homebrew installs packages in a system-wide /usr/local prefix by default. This is encouraged praxis when using brew, but optional. See Alternative Installs from the Homebrew documentation for details.

Git submodule

If your project uses Git, the recommended method of installation is via a submodule.

Note: The following example installs libraries in the ./test/test_helper directory.

$ git submodule add https://github.com/ztombol/bats-support test/test_helper/bats-support
$ git commit -m 'Add bats-support library'

Git clone

If you do not use Git for version control, simply clone the repository.

Note: The following example installs libraries in the ./test/test_helper directory.

$ git clone https://github.com/ztombol/bats-support test/test_helper/bats-support

Loading

A library is loaded by sourcing the load.bash file in its main directory.

Assuming that libraries are installed in test/test_helper, adding the following line to a file in the test directory loads the bats-support library.

load 'test_helper/bats-support/load'

For npm installations, load the libraries from node_modules:

load '../node_modules/bats-support/load'
load '../node_modules/bats-assert/load'

For brew installations, load the libraries from $(brew --prefix)/lib/ (the brew prefix is /usr/local by default):

TEST_BREW_PREFIX="$(brew --prefix)"
load "${TEST_BREW_PREFIX}/lib/bats-support/load.bash"
load "${TEST_BREW_PREFIX}/lib/bats-assert/load.bash"

Note: The load function sources a file (with .bash extension automatically appended) relative to the location of the current test file.

Note: The load function does NOT append a .bash extension automatically when loading a file using an absolute path.

If a library depends on other libraries, they must be loaded as well.

Simple loading helper

You can create a shorthand to simplify library loading.

# Load a library from the `${BATS_TEST_DIRNAME}/test_helper' directory.
#
# Globals:
#   none
# Arguments:
#   $1 - name of library to load
# Returns:
#   0 - on success
#   1 - otherwise
load_lib() {
  local name="$1"
  load "test_helper/${name}/load"
}

This function lets you load a library with only its name, instead of having to type the entire installation path.

load_lib bats-support
load_lib bats-assert

Testing

A library's test suite is located in its test subdirectory. Library dependencies are loaded from $TEST_DEPS_DIR, which defaults to the directory containing the library.

For example, testing the bats-assert library requires the bats-support to be present in the same directory by default.

$ tree -L 1
.
├── bats-assert
└── bats-support

2 directories, 0 files
$ bats bats-assert/test

This simplifies testing in most cases, e.g. testing in development and before running the project's test suite, but also allows easily selecting dependencies, e.g. testing compatibility with different versions.

bats-core/bats-docs