Why bashunit

A lightweight, fast testing framework for Bash 3.0+, focused on developer experience. 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

One representative example per family — the full catalogue and every signature is at bashunit.com/assertions, 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

Full documentation, covering installation options, every feature and examples, lives at bashunit.com.

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

Using an AI coding agent? bashunit.com/ai-agents covers machine-readable results and the API traps that make generated bash tests pass for the wrong reason. The docs are also published as plain text at llms.txt and llms-full.txt, with a drop-in skill at bashunit-skill.md.

Contribute

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