testing.md

Documentation for the functions in testing.sh. A general overview is given in the project documentation.

Module documentation

The module maintains a range of global variables to keep track of a test session in between function calls:

• $test_counter and $test_error_count are initialized to 0 by initialize_test_session() and incremented for every test respectively every failed test by check_test_results(), which uses them inside its test result messages as well
• the expected results of a test are kept in $expected_return and $expected_stdout. They are set via configure_test() and compared to the actual test outcome in check_test_results()
• $test_session_name stores the session name; it's used in the introduction and conclusion messages

Function documentation

If the pipes are not documented, the default is:

• stdin: ignored
• stdout: empty

Parameters enclosed in brackets [ ] are optional.

initialize_test_session()

Sets up the internals for a test session.

Param.	$1	name of the session
Status	0
Globals	$test_counter $test_error_count $test_session_name

configure_test()

Sets up the expected test result values

Param.	$1	expected return status
	[$2]	expected stdout, default to n empty string if omitted
Status	0
Globals	$expected_return $expected_stdout

test()

Checks that the specified command exists, executes it using capture() and calls check_test_results() with the captured status return and stdout output.

Param.	$1 ...	command to test ($1 is the command)
Pipes	stdout	test results messages from check_test_results()
Status	0
Globals	see check_test_results()

check_test_results()

Checks if $2 corresponds to $expected_status and $3 to $expect_stdout and writes a message on stdout. Increments $test_counter and, if the check failed, $test_error_count.

Param.	$1	command, as a properly quoted string
	$2	command return status
	$3	command stdout
Pipes	stdout	test result message
Status	0
Globals	$expected_return $expected_stdout $test_counter $test_error_count

conclude_test_session()

Prints a summary and returns a session success status

Pipes	stdout	test session summary
Status	0	no test errors found, success
	1	at least one of the tests failed
Globals	$test_counter $test_error_count $test_session_name