shtap.sh File Reference

Unit testing framework for BASH based on the Test Anything Protocol. More...

Go to the source code of this file.

Functions
function	diag (in msg)
	Print diagnostic message. More...
function	fail ()
	Fail in any case and print reason. More...
function	is (in result, in expected, in name)
	Test whether a given result is equal to the expected result. More...
function	isnt (in result, in expected, in name)
	Test whether a given result is not equal the expected result. More...
function	like (in result, in pattern, in name)
	Test whether a given result matches an expected pattern. More...
function	ok (in expression, in name)
	Evaluate test expression and fail if it does not evaluate to 0 or check return value of function. More...
function	okx (in command)
	Execute command and check return value. More...
function	pass ()
	Pass in any case and print reason. More...
function	plan_no_plan ()
	Choose not to plan number of tests in advance. More...
function	plan_skip_all ()
	Plan to skip all tests. More...
function	plan_tests ()
	Plan a certain number of tests and stick to it. More...
function	SHTAP_BAIL_OUT (in reason)
	Bail out. More...
function	skip (in condition, in reason, in n)
	Skip tests under a certain condition. More...
function	unlike (in result, in pattern, in name)
	Test whether a given result does not match an expected pattern. More...

Variables
string	SHTAP_VERSION = "1.02-basis"

Detailed Description

Unit testing framework for BASH based on the Test Anything Protocol.

Author

Patrick LeBoutillier <patl at cpan.org>

Note

This file is a copy of the tap-functions file which is part of the JTap project (http://svn.solucorp.qc.ca/repos/solucorp/JTap/trunk/). The original implementation has been modified by Andreas Schuh as part of the BASIS project at SBIA.

Plan:

plan_no_plan
plan_skip_all [REASON]
plan_tests NB_TESTS

Test:

ok RESULT [NAME]
okx COMMAND
is RESULT EXPECTED [NAME]
isnt RESULT EXPECTED [NAME]
like RESULT PATTERN [NAME]
unlike RESULT PATTERN [NAME]
pass [NAME]
fail [NAME]

Skip:

skip [CONDITION] [REASON] [NB_TESTS=1]

skip $feature_not_present "feature not present" 2 ||
{
    is $a "a"
    is $b "b"
}

Specify TODO mode by setting the TODO variable:

TODO="not implemented yet"
ok $result "some not implemented test"
unset TODO

Other:

diag MSG

Example:

#! /usr/bin/env bash

source shtap.sh

plan_tests 7

# test identity
{
    me=${USER}
    is ${USER} ${me} "I am myself"
    like ${HOME} ${me} "My home is mine"
    like "`id`" ${me} "My id matches myself"
}

# test ls
{
    ls ${HOME} 1>&2
    ok $? "ls ${HOME}"
    # same thing using okx shortcut
    okx ls ${HOME}
}

# test only for root
{
    [[ "`id -u`" != "0" ]]
    i_am_not_root=$?
    skip ${i_am_not_root} "Must be root" ||
    {
        okx ls /root
    }
}

# test TODO
{
    TODO="figure out how to become root..."
    okx [ "$HOME" == "/root" ]
    unset TODO
}

Definition in file shtap.sh.

Function Documentation

diag()

function diag

(

in

msg

)

Print diagnostic message.

Parameters

[in]

msg

Diagnostic message.

Returns

Always 1.

fail()

function fail

(

)

Fail in any case and print reason.

Returns

Nothing.

is()

function is	(	in	result,
		in	expected,
		in	name
	)

Test whether a given result is equal to the expected result.

Parameters

[in]	result	Actual result.
[in]	expected	Expected result.
[in]	name	Optional name of test.

Returns

Whether the results are equal.

Return values

0	On equality.
1	Otherwise.

isnt()

function isnt	(	in	result,
		in	expected,
		in	name
	)

Test whether a given result is not equal the expected result.

Parameters

[in]	result	Actual result.
[in]	expected	Expected result.
[in]	name	Optional name of test.

Returns

Whether the results were not equal.

Return values

0	Otherwise.
1	On equality.

like()

function like	(	in	result,
		in	pattern,
		in	name
	)

Test whether a given result matches an expected pattern.

Parameters

[in]	result	Actual result.
[in]	pattern	Expected pattern.
[in]	name	Optional name of test.

Returns

Whether the result matched the pattern.

Return values

0	On match.
1	Otherwise.

ok()

function ok	(	in	expression,
		in	name
	)

Evaluate test expression and fail if it does not evaluate to 0 or check return value of function.

This is the workhorse method that actually prints the tests result.

Parameters

[in]	expression	Test expression or return value.
[in]	name	Name of test.

Returns

Nothing.

okx()

function okx

(

in

command

)

Execute command and check return value.

Parameters

[in]

command

Command to run.

Returns

Nothing.

pass()

function pass

(

)

Pass in any case and print reason.

Returns

Nothing.

plan_no_plan()

function plan_no_plan

(

)

Choose not to plan number of tests in advance.

Returns

Nothing.

plan_skip_all()

function plan_skip_all

(

)

Plan to skip all tests.

Returns

Nothing.

plan_tests()

function plan_tests

(

)

Plan a certain number of tests and stick to it.

Returns

Nothing.

SHTAP_BAIL_OUT()

function SHTAP_BAIL_OUT

(

in

reason

)

Bail out.

Parameters

[in]

reason

Reason for bailing out.

Returns

Nothing. Instead, exits the process with error code 255.

skip()

function skip	(	in	condition,
		in	reason,
		in	n
	)

Skip tests under a certain condition.

Parameters

[in]	condition	The condition for skipping the tests. If 0, the tests are skipped, otherwise not.
[in]	reason	An explanation for why skipping the tests.
[in]	n	The number of tests which will be skipped.

Returns

Whether the tests were skipped.

Return values

0	If tests are to be skipped.
1	Otherwise.

unlike()

function unlike	(	in	result,
		in	pattern,
		in	name
	)

Test whether a given result does not match an expected pattern.

Parameters

[in]	result	Actual result.
[in]	pattern	Expected pattern.
[in]	name	Optional name of test.

Returns

Whether the result did not match the pattern.

Return values

0	Otherwise.
1	On match.

Variable Documentation

SHTAP_VERSION

string SHTAP_VERSION = "1.02-basis"

Definition at line 118 of file shtap.sh.