Best

A testing framework designed for Bash, and built with Bash.

Minimum Bash version: 3.2.0
Supported platforms:

• GNU Linux
• MacOS

Command Line

bin/best.sh [options] [test...]

Options:

Option	Value	Description
--jobs / -j	[number]	Specify the number of tests to run in parallel. Defaults to the current number of logical cores.
--suite	[string]	Loads a specific test suite. If this is absent, all suites in $PWD/test will be loaded.
--snapshot:generate		Forces all snapshots to be regenerated.
--snapshot:show		Prints the difference between test output and output snapshots.
--snapshot:skip		Skips snapshot testing.
--verbose		Prints STDOUT and STDERR of failed tests.
--strict		Treat skipped tests as though they were failed tests.
--failed		Only show failed tests.
--VERBOSE		Prints STDOUT and STDERR of all tests.
--debug		Prints debug information. This only prints information about best itself.
--porcelain		Changes the printing mode to something machine-friendly.
--color		Enable color output.
--no-color		Disable color output.

Subcommands:

Subcommand	Description
--list	Prints a list of tests in the loaded suites.
--version	Prints the version and exits.
--repl	Enters a minimal REPL similar to the IPC API.

Environment Variables:

Variable	Description	Default
$BEST_BASH	A path to the version of Bash to execute tests with.
$TEST_ENV_TMPDIR	The value of $TMPDIR inside the testing environment.	Inherited
$TEST_ENV_PATH	The value of $PATH inside the testing environment.	Inherited
$TEST_ENV_HOME	The value of $HOME inside the testing environment.	Inherited
$TEST_ENV_TERM	The value of $TERM inside the testing environment.	xterm-color
$TEST_LIB_PREFIX	A variable that prepends a sequence to the test functions. This can be used to prevent function name conflicts with best and the scripts that it's testing.	None
$TEST_SHIM_PATH	The path to the shims loadable by use_shim.	None
$TEST_DIR	The directory where test suites are stored.	$PWD/test
$SNAPSHOT_DIR	The directory where snapshots are stored.	$PWD/test-data

Tests

Suites

Test suites are located inside $(PWD)/test as .sh files.

test:my_test() {
    description 'This is your first test.'

    assert_equal 1 1
    assert [ "a" = "b" ]
}

Functions

• assert [function...]
• assert_equal [a] [b]
• assert_not_equal [a] [b]
• assert_less [a] [b]
• assert_less_or_equal [a] [b]
• assert_greater [a] [b]
• assert_greater_or_equal [a] [b]
• assert_exit [code]
• expect [function...]
• expect_equal [a] [b]
• expect_not_equal [a] [b]
• expect_less [a] [b]
• expect_less_or_equal [a] [b]
• expect_greater [a] [b]
• expect_greater_or_equal [a] [b]
• fail [pattern] [...]
• skip [pattern] [...]
• array_contains [value] in [...]
• snapshot ["stdout"|"stderr"]
• description [message]
• use_shim [name]

Setup / Teardown

The functions named setup and teardown are used for test suite setup and teardown. The former will be called when the suite is loaded, and the latter will be called after all tests are run.

setup() {
    MY_VAR=3
}

teardown() {
    unset MY_VAR
}

test:check_setup() {
    assert_equal "$MY_VAR" 3
}