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:
#!/bin/sh
test_description='Show basic features of Sharness'
. ./sharness.sh
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
'
test_expect_failure 'We expect this to fail' '
test 1 = 2
'
test_doneRunning 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)
1..4
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
Every test is run in a temporary trash directory, so you are free to create as
many files as you want, even files in the home directory, because $HOME is set
to that temporary trash directory. At the end of the test, that directory is
removed (unless there's a failure).
Sharness was derived from the Git project - see README.git for the original documentation.
First, clone the Git repository:
$ git clone https://github.com/felipec/sharness.git
Then choose an installation method that works best for you:
If you like to add Sharness to the sources of a project you want to
use it for, simply copy the files sharness.sh and example/Makefile to a
folder named test inside that project, and source sharness.sh in your test
files.
Another way is to use Sharnessify.
Alternatively, you can also add Sharness as a Git submodule to your project.
In per-project installation, Sharness will optionally load extensions from
sharness.d/*.sh if a sharness.d directory is found in the same directory
as sharness.sh. This allows per-project extensions and enhancements to
be added to the test library without requiring modification of sharness.sh.
$ cd sharness
$ make install
This will install Sharness to $HOME/share/sharness, and its documentation and
examples to $HOME/share/doc/sharness.
$ 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.
The only essential file to Sharness is sharness.sh, which is the core shell
library providing test functionality. It's meant to be sourced from test
scripts, but not executed.
The following files are optional:
example/Makefile- test driver. The default target runs the complete testsuite.lib-sharness/functions.sh- extra functions. These are functions that are nice to have, but not necessary.tools/aggregate-results.sh- tool to show results. Aggregates all the results intest-results. It's meant to be called inside theMakefileafter all the tests finish.
Sharness loads the extra functions automatically if you are using bash or zsh,
but otherwise you need to set SHARNESS_SRCDIR to the directory where
sharness.sh is.
To see an explanation of all the functions, see the separate API documentation.
To learn how to write and run actual test scripts based on sharness.sh, please
read README.git until I come up with more documentation myself.
The *.t test scripts have the following options (again, read
README.git for details) :
--debug,-d: helps debugging--immediate,-i: stop execution after the first failing test--long-tests,-l: run tests marked with prereq EXPENSIVE--interactive-tests: run tests marked with prereq INTERACTIVE--help,-h: show test description--verbose,-v: show additional debug output--quiet,-q: show less output--chain-lint/--no-chain-lint: check &&-chains in scripts--no-color: don't color the output--tee: also write output to a file--verbose-log: write output to a file, but not on stdout--root=<dir>: create trash directories in<dir>instead of current directory.
See how Sharness is used in real-world projects:
- azuki
- cb2util
- dabba
- genimage
- git-integration
- git-multimail
- git-related
- git-spindle
- git-svn-fast-import
- go-ipfs
- go-multihash
- inotify-tools
- ipfs-update
- pass
- RAUC
- rdd.py
- Sharness itself
- tomdoc.sh
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.
Contributions are welcome, see file CONTRIBUTING for details.
Sharness was created in April 2011 and maintained until June 2016 by Mathias Lafeldt. The library is derived from the Git project's test-lib.sh. It was maintained by Christian Couder from June 2016 to August 2019, thanks to sponsorship from Protocol Labs. It is currently maintained by Felipe Contreras.
See Github's "contributors" page for a list of developers.
A complete list of authors should include Git contributors to test-lib.sh too.