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:
Libraries:
bats-support
(formerlybats-core
) - supporting library for test helpersbats-assert
- common assertionsbats-file
- filesystem related assertions
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
).
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
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.
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'
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
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.
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
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.