Shell TAP Producer

Little shell library for testing anything. More or less a Shell knockoff of Perl's Test::More, usable with Prove.

Just copy shmore.subr somewhere and source it.

Tested with bash, dash, ksh, sh, and zsh on OpenBSD and macOS. It should work elsewhere as well.

Examples are in ./examples, and have a look at wtrtdtmlb's tests for IRL usage.

Example

This test script

#!/bin/sh

# Source shmore.
. ./shmore.subr

# Note how many tests will be run.  This isn't strictly necessary but gives us
# a warning if we inadvertently add or remove a test.  It also makes prove a
# bit less boring to watch.
tap_plan 3

# Simplest test is to make sure a previous command worked.
/bin/echo "It worked" >/dev/null
tap_ok $? "Echo succeeded"

# More useful is comparing what we got and what we want.
GOT=$(echo "It worked")
WANT="It worked"
tap_is "$GOT" "$WANT" "Echo echoed properly"

# If we have perl, we can also test against a regex
if which perl >/dev/null 2>&1; then
        tap_like "$(date)" '20\d{2}$' "Still in the 21st century"
else
        # Or we can use tap_skip to note we skipped a test
        tap_skip "Missing perl" 1
fi

produces the following output

1..3
ok 1 - Echo succeeded
ok 2 - Echo echoed properly
ok 3 - Still in the 21st century

which looks like this IRL

$ prove examples/quickstart.t
examples/quickstart.t .. ok
All tests successful.
Files=1, Tests=3,  0 wallclock secs ( 0.01 usr  0.00 sys +  0.01 cusr  0.01 csys =  0.03 CPU)
Result: PASS

or like this if we get verbose

$ prove -v examples/quickstart.t
examples/quickstart.t ..
1..3
ok 1 - Echo succeeded
ok 2 - Echo echoed properly
ok 3 - Still in the 21st century
ok
All tests successful.
Files=1, Tests=3,  0 wallclock secs ( 0.01 usr  0.00 sys +  0.01 cusr  0.02 csys =  0.04 CPU)
Result: PASS

There are more examples in examples. To run them all at once, try prove -v examples/ in this directory.

API

Shmore's API consists of a handful of functions plus two variables.

Functions

Optional arguments are in italics. Each function links to better documentation.

Name	Description	$1	$2	$3	$4	$5	$6
tap_ok	Notes whether a test succeded or failed; the most basic function	0 for succes	Test Name	Test File	Test Line
tap_pass	tap_ok 0 "$@"	Test Name	Test File	Test Line
tap_fail	tap_ok 1 "$@"	Test Name	Test File	Test Line
tap_is	[ "$1" == "$2" ]	The Got	The Expected	Test Name	Test File	Test Line
tap_isnt	[ "$1" != "$2" ]	The Got	The Not Expected	Test Name	Test File	Test Line
tap_cmp_ok	[ "$1" "$2" "$3" ]	The Got	A test(1) operator	The Want	Test Name	Test File	Test Line
tap_like	Uses Perl to test if a regex is matched	The Got	A Regex	Test Name	Test File	Test Line
tap_unlike	Uses Perl to test if a regex is not matched	The Got	A Regex	Test Name	Test File	Test Line
tap_subtest	Run a subtest	Subtest test name	Subtest function name	Test File	Test Line
tap_skip	Equivalent to a number of tap_ok 0's which note tests were skipped	A Reason	How many tests will be skipped
tap_todo_skip	Equivalent to a number of tap_ok 1s which also note the tests are TODO	A Reason	How many TODO tests will be skipped
tap_diag	Print a diagnostic message to stderr	The Message; arguments will be joined with "$*"
tap_note	Print a diagsontic message not seen when using a test harness	The Message; arguments will be joined with "$*"
tap_plan	Note and print the number of tests to run	The number of tests expected to run
tap_done_testing	Emit a plan if tap_plan wasn't called or check if the correct number of tests were run if so
tap_reset	Reset Shmore's internal state
tap_BAIL_OUT	Stops all testing	A Reason; arguments will be joined with "$*"

Many functions take an optional file and line number. This is usually done with $0 and $LINENO, e.g.

tap_ok $? "A thing worked" "$0" $LINENO

Variables

In addition, two variables are provided

Name	Description
TAP_TODO	When set, notes that tests are expected to fail
TAP_NOTRAP	When set before sourcing shmore.subr, prevents tap_done_testing from being set as the EXIT trap.

Code Changes

Change the files in src and then re-run make to re-assemble shmore.subr. This is only really suppored on OpenBSD, but will probably work on other OS's using BSD Make. Alternatively, edit shmore.subr directly.

Test with make test or prove -It.

Testing

Tests are in t and testable examples in examples.

Shells which don't support LINENO (Like Debian's sh) will cause large numbers of test failures, but these are more or less false-positivish.