README.md

A simple testing framework for bash scripts

Write and run tests for your Bash scripts.

Why bashunit

A testing framework for Bash 3.0+. It ships 93 assertions plus spies, mocks, data providers, snapshots and more.

Quick start

Install the latest version into your project:

curl -s https://bashunit.com/install.sh | bash

Write a test in tests/example_test.sh:

#!/usr/bin/env bash

function test_bashunit_is_working() {
  assert_same "bashunit is working" "bashunit is working"
}

Run it:

./lib/bashunit tests/

Assertions at a glance

The table shows one example from each assertion family. See all assertions and signatures, or run bashunit doc locally:

Family	Example
Equality & truth	assert_equals "foo" "$actual"
Strings	assert_string_starts_with "Hello" "$greeting"
Exit codes	assert_exit_code "1" (checks $? of the previous command)
Numeric	assert_greater_than "1" "$count"
Arrays	assert_array_length 3 "${my_array[@]}"
Files & dirs	assert_file_permissions 644 "$file"
JSON (needs jq)	assert_json_contains ".name" "bashunit" "$json"
Dates	assert_date_before "2026-01-01" "$date"
Duration	assert_duration_less_than "echo hello" 500
Snapshots	assert_match_snapshot "$(my_cmd)"
Test doubles	assert_have_been_called_times 2 my_fn

Documentation

Installation instructions, feature references, and examples are at bashunit.com.

Shell tab-completion for bash and zsh is available under completions/. See the installation docs.

The AI agent guide covers machine-readable results and API mistakes that let generated tests pass without checking the intended behavior. Plain-text docs are available at llms.txt and llms-full.txt, with an agent skill at bashunit-skill.md.

Contribute

Issues, ideas and pull requests are welcome. See the contribution guide to set up your environment.