NAME

t.sh — test utility

SYNOPSIS

DESCRIPTION

The shell script t.sh provides a mean of testing utilities and shell scripts. Each file defines one or many test cases using functions provided by t.sh.

The options are as follows:

-f filter

Only execute test cases with a description matching the basic regular expression filter. May be given multiple times.

-F filter

Inverse of option -f.

-t tag

Only execute test cases tagged with tag. May be given multiple times.

-T tag

Inverse of option -t.

-x

Exit after the first failing test case.

The following functions are available inside file:

assert_eq want got [message]

Assert that the two strings want and got are identical. Otherwise, the difference is displayed.

refute_eq want got [message]

Inverse of assert_eq.

assert_file file1 file2 [message]

Assert that the two files file1 and file2 are identical. Otherwise, the difference is displayed using diff(1).

refute_file file1 file2 [message]

Inverse of assert_file.

fail [-] [message]

Mark the current test case as failing. Option - indicates that data on stdin should be part of the displayed failure message.

testcase [-t tag] description

Declare a new test case. It can optionally be tagged with one or many tags. Both the description and tags can be used to filter out which test case to execute. The function exits 0 if the test case should be executed and non-zero otherwise. Filtering is therefore made functional by making each test case declaration part of a conditional statement, see EXAMPLES.

The following functions can optionally be defined and invoked by t.sh:

setup

Invoked before each testcase.

ENVIRONMENT

TSHCLEAN

Files and directories to remove upon exit.

TSHDIR

Directory where temporary files can be created during testing. All entries are removed between test cases.

EXAMPLES

Example test cases for the basename(1) utility. All test cases are defined in a separate shell script basename.sh with the contents as follows:

if testcase "no suffix"; then
	assert_eq "t.sh" "$(basename tests/t.sh)"
fi

if testcase "suffix present"; then
	assert_eq "t" "$(basename tests/t.sh .sh)"
fi

if testcase "suffix absent"; then
	assert_eq "t.sh" "$(basename tests/t.sh .c)"
fi

if testcase -t fatal "mandatory argument absent"; then
	assert_fatal basename
fi

Custom functions can be defined in a separate shell script and made available by making it the first file passed to t.sh. The test cases above make use of the shell script util.sh with the content as follows:

assert_fatal() {
	local _err=0 _tmp="${TSHDIR}/fatal"

	sh -c "exec ${*}" >"$_tmp" 2>&1 || _err="$?"
	if [ "$_err" -eq 0 ]; then
		fail - "unexpected exit code" <"$_tmp"
	fi
}

Execute all test cases:

Skip test cases tagged as fatal:

DIAGNOSTICS

The t.sh utility exits 0 on success, and >0 if an error occurs.

SEE ALSO

sh(1), test(1), re_format(7)

AUTHORS

Anton Lindqvist <anton@basename.se>