Purpose: Provides a framework to execute one or more unit tests or performance tests for Bash script functions, reporting success, failure, and timing.
Unit Test Scripts: No unit test scripts exist for litest. That's because litest itself is a unit testing framework. Perhaps one day, litest will test itself.
Requires Modules: None. NOTE: litest duplicates some functionality found in other Bashful modules. This duplication was done intentionally for stability, to ensure that defects in other modules wouldn't cause defects within litest itself.
Required By Modules: None
The following usage demonstrates how a litest-derived script may be executed. In this example, the script is named list.sh. Note that the instructions below are copied verbatim from the help text generated by litest.
Usage: list.sh
list.sh -h
list.sh [-c] [-i] [-s] [-t count] [-T] 'all' [group ...]
list.sh [-c] [-i] [-s] [-t count] [-T] [group 'all']
list.sh [-c] [-i] [-s] [-t count] [-T] [group [case ...]]
list.sh 'list' ['all']
list.sh 'list' [group ...]
list.sh [group] 'list'
Executes the specified test cases within the specified test group, optionally timing the duration required to execute the specified number of test iterations.
If no test groups are specified, or list is specified without test cases, the list of available test groups will be listed.
If list all is specified, all test cases for all test groups will be listed with descriptions.
If list is specified with one or more test groups, all test cases for the specified test groups will be listed with descriptions.
If a test group is specified without test cases, the list of available test cases for the specified test group will be listed.
If all is specified without test cases, all test cases within all test groups will be executed.
If all is specified with one or more test groups, all test cases within the specified test groups will be executed.
If a test group is specified with one or more test cases, the specified test cases will be executed.
If a test group is specified with all as the next argument, all test cases for the specified test group will be executed.
If a test group is specified with list as the next argument, all test cases for the specified test group will be listed with descriptions.
Litest may be called with the following optional flags:
-c: causes the screen to be cleared prior to test execution.
-e: executes set -e before executing test cases. This causes test cases to fail if any non-zero status code is generated by a command executed during a test case.
-h: shows usage information.
-i: allows remaining test cases to be executed even if some test cases fail. By default, Litest aborts the execution of remaining test cases if one fails.
-s: reports the results of each test case in a summarized format, suppressing the test description, executed test command, and superfluous whitespace. By default, only passing tests are summarized, and failing tests are reported in verbose mode.
-t: allows an iteration count to be specified, which causes test executions to be timed as they are executed the specified number of iterations. When tests are timed, their output is not checked for correctness. However, a non-zero exit status will cause tests to abort unless -i was specified.
-T: prevents Litest from setting and clearing Bash error traps when sourcing the scripts referenced in the global array TEST_SCRIPTS. Litest normally sets Bash error traps so that if set -e behavior is active, and any command within a sourced script generates a non-zero status, Litest will report an error message instead of just aborting silently. However, if sourced scripts perform their own Bash error trap logic, that logic might break due to the traps set and cleared by Litest. In such cases, specify -T to prevent Litest from altering Bash error traps.
-u: executes set -u before executing test cases. This causes errors to be thrown when undeclared variables are referenced.
-v reports the results of each test case in verbose format, in which the description and executed command for each test case is reported. By default, only failing tests are reported in verbose mode.
Each test group must correlate with a function created by the test author. The name of the function must consist of the format testSpec_GROUP, where GROUP must be replaced with the actual name of the test group. For example, if the test author created a test group named text, a function must exist named testSpec_text.
testSpec functions may be designated as hidden by naming the prefix of the function as testSpec__ (with two underscores) instead of testSpec_. Doing so will cause the test to be omitted from all lists of tests available to be run, and will also cause the test to be skipped when all tests are run.
The purpose of the testSpec functions are to accept a single parameter as input, which designates the test case to execute, and in response, set the following global variables to define the behavior of the test case:
TEST_DESC: A brief, human-readable description of the test case goals. E.g. Test basic 'echo' functionality
TEST_CMD: The shell command that comprises the test case to execute. E.g. echo 'hello'
TEST_EXP_OUTPUT: The output expected to be received as a result of executing TEST_CMD. The test will be considered a failure if the actual command output doesn't match the expected output. E.g. hello
TEST_EXP_STATUS: The status value expected to be returned upon execution of TEST_CMD. The test will be considered a failure if the actual command status doesn't match the expected status. E.g. 0
The testSpec function must also be capable of echoing the entire list of supported test cases for the test group, if all is received as the first parameter. For example, testSpec_text all might echo echo sort uniq in response.
testSpec functions that return a status code other than 0 will cause Litest to abort.
For simplicity, the test author may choose to use ascending integers instead of textual test case names. For reference on how to easily implement this, refer to the reference function testSpec__litest.
Note that a global array, TEST_SCRIPTS, is provided for test suite authors to specify scripts that should be sourced prior to test execution. This array should be populated with the full or relative path of scripts required by the test suite. If -e was specified, set -e is executed prior to sourcing the scripts. Similarly, if -u was specified, set -u is executed.
Refer to the test scripts located in the tests/ subdirectory for examples of how to create unit-testing scripts based on litest.