Shell library to test your Unix tools like Git does

This project is maintained by mlafeldt


Sharness is a portable shell library to write, run, and analyze automated tests for Unix programs. Since all tests output TAP, the Test Anything Protocol, they can be run with any TAP harness.

Each test is written as a shell script, for example:


test_description="Show basic features of Sharness"

. ./

test_expect_success "Success is reported like this" "
    echo hello world | grep hello

test_expect_success "Commands are chained this way" "
    test x = 'x' &&
    test 2 -gt 1 &&
    echo success

return_42() {
    echo "Will return soon"
    return 42

test_expect_success "You can test for a specific exit code" "
    test_expect_code 42 return_42

test_expect_failure "We expect this to fail" "
    test 1 = 2


Running the above test script returns the following (TAP) output:

$ ./simple.t
ok 1 - Success is reported like this
ok 2 - Commands are chained this way
ok 3 - You can test for a specific exit code
not ok 4 - We expect this to fail # TODO known breakage
# still have 1 known breakage(s)
# passed all remaining 3 test(s)

Alternatively, you can run the test through prove(1):

$ prove simple.t
simple.t .. ok
All tests successful.
Files=1, Tests=4,  0 wallclock secs ( 0.02 usr +  0.00 sys =  0.02 CPU)
Result: PASS

Sharness was derived from the Git project - see README.git for the original documentation.


First, clone the Git repository:

$ git clone git://

Then choose an installation method that works best for you:

Per-project installation

If you like to add Sharness to the sources of a project you want to use it for, simply copy the files,, and test/Makefile to a folder named test inside that project.

Alternatively, you can also add Sharness as a Git submodule to your project.

Per-user installation

$ cd sharness
$ make install

This will install Sharness to $HOME/share/sharness, and its documentation and examples to $HOME/share/doc/sharness.

System-wide installation

$ cd sharness
# make install prefix=/usr/local

This will install Sharness to /usr/local/share/sharness, and its documentation and examples to /usr/local/share/doc/sharness.

Of course, you can change the prefix parameter to install Sharness to any other location.

Installation via Chef

If you want to install Sharness with Opscode Chef, the Sharness cookbook is for you.


The following files are essential to using Sharness:

To learn how to write and run actual test scripts based on, please read README.git until I come up with more documentation myself.

Projects using Sharness

See how Sharness is used in real-world projects:

Furthermore, as Sharness was derived from Git, Git's test suite is worth examining as well, especially if you're interested in managing a big number of tests.


Here is a list of other shell testing libraries (sorted alphabetically):


Sharness is licensed under the terms of the GNU General Public License version 2 or higher. See file COPYING for full license text.