A bash library to ease script development.
The library is divided in module files to be loaded using the source
command.
Public functions and variables are all prefixed with a namespace in order to
avoid collisions with your own script.
The testthat
library is a test library for testing bash functions and programs.
When inside a test script, you have first to define context:
tt_context "My context"
The text of the context will be printed on the screen.
Then you call tt_test_that
for each test function you have written:
tt_test_that "myFct is working correctly" test_myFct
Inside your test_myFct
function, you call assertions:
function test_myFct {
tt_expect_num_eq 1 2 || return 1
}
Do not forget to append || return 1
to the assertion call, otherwise no
error will be reported in case of failure.
The testthat
library (testthat.sh
file) comes along a script (testthat
)
designed to help you write tests for a command line program, written in any
language, or to test bash functions.
In particular, the framework provides functions for testing CSV files that you use as inputs or outputs of your program.
The testthat
script can be run on individual test scripts or folders
containing test scripts. You can even specify a mix of them on the command
line:
testthat myfirst_script.sh myfolderA mysecond_script.sh myfolderB
Running individual scripts is done by listing the script paths on the command line:
testthat myfirst_script.sh mysecond_script.sh my/other/script.sh
The scripts will be run in the specified order.
If you put your test scripts inside a single folder (called here test
) you
call testthat
on that folder:
testthat test
Only the scripts named test-*.sh
will be run by testthat
.
The scripts will be run in alphabetical order.
The default exact regular expression used by testthat
is:
[Tt][Ee][Ss][Tt][-._].*\.sh
.
Thus you have a little flexibility in naming your test files by default.
If this is not sufficient, you can still redefine this pattern by using the
-f
command line argument.
The pattern format must be a POSIX extended regular expression as required by
the =~
comparison operator provided by the [[
bash command.
A test scripts is composed of functions in which assertions (i.e.: the tests) are written. The functions are called individually with some description message that will be printed in case of failure.
Here is a full example:
function test_someStuff {
tt_expect_num_eq 1 2 || return 1
}
tt_context "Running some test for an example"
tt_test_that "Some stuff is running correctly." test_someStuff
The tt_context
call define a title for the tests that will follow. It will be
printed in the output.
The tt_test_that
function calls the test function test_someStuff
and in
case of failure will display the message specified.
Inside the test_someStuff
function you have to call assertions in order to
test code.
In this example we use the assertion tt_expect_num_eq
(all assertions start
with tt_expect_
as a prefix), which tests the equality of two numeric
numbers.
In our case the two numbers 1
and 2
will lead to a failure of the test.
But, please, note that in order to activate the failure it is compulsory to
append || return 1
to the assertion call, otherwise no failure will be
reported.
Each assertion will either lead to the printing of a dot (.
) character in
case of success or another character in case of failure.
At the end of tests, each character printed to indicate a failure will again be
printed along with the message provided to the tt_test_that
call and the call
stack.
For a full list of assertions, see the chapter about Assertions.
Assertions start all with the prefix tt_expect_
and their call need to be
followed by || return 1
in order to report a failure.
Some assertions take a custom message to be displayed in case of failure.
tt_expect_success
tests the success of a command.
Argument | Description |
---|---|
* | Command. |
Example:
tt_expect_success my_command arg1 arg2 || return 1
tt_expect_success_in_n_tries
tests that a command succeeds before n tries.
Argument | Description |
---|---|
1 | Number of tries. |
* | Command. |
Example:
tt_expect_success_in_n_tries 3 my_command arg1 || return 1
tt_expect_failure
tests the failure of a command.
Argument | Description |
---|---|
* | Command. |
Example:
tt_expect_failure my_command arg1 arg2 || return 1
tt_expect_status
tests that a command fails and return a precise status value.
Argument | Description |
---|---|
1 | Expected status number. |
* | Command. |
Example:
tt_expect_status 4 my_command arg1 arg2 || return 1
tt_expect_exit
tests the failure of a command by running the command inside
a subshell. Thus you can test a call to a function that call the exit
command.
Argument | Description |
---|---|
* | Command. |
Example:
tt_expect_exit my_command arg1 arg2 || return 1
tt_expect_exit_status
tests that a command fails and return a precise status
value by running the command inside a subshell. Thus you can test a call to a
function that call the exit
command.
Argument | Description |
---|---|
1 | Expected status number. |
* | Command. |
Example:
tt_expect_exit_status 0 my_command arg1 arg2 || return 1
tt_expect_empty_output
tests if a command output nothing on stdout.
Argument | Description |
---|---|
* | Command. |
Example:
tt_expect_empty_output my_command arg1 arg2 || return 1
tt_expect_non_empty_output
tests if a command output something on stdout.
Argument | Description |
---|---|
* | Command. |
Example:
tt_expect_non_empty_output my_command arg1 arg2 || return 1
tt_expect_output_eq
tests if the output of a command is equals to a value.
The output is stripped from carriage returns before comparison.
Argument | Description |
---|---|
1 | Expected output as a string. |
* | Command. |
Example:
tt_expect_output_eq "Expected Output" my_command arg1 arg2 || return 1
tt_expect_output_ne
tests if the output of a command is equals to a value.
The output is stripped from carriage returns before comparison.
Argument | Description |
---|---|
1 | Expected output as a string. |
* | Command. |
Example:
tt_expect_output_ne "Expected Output" my_command arg1 arg2 || return 1
tt_expect_output_esc_eq
tests if the output of a command is equals to a
value. Carriage returns are preserved.
Argument | Description |
---|---|
1 | Expected output as a string for echo command with trailing newline disabled and backslash escapes enabled. |
* | Command. |
Example:
tt_expect_output_esc_eq "Expected Output" my_command arg1 arg2 || return 1
tt_expect_output_esc_ne
tests if the output of a command is different from a
value. Carriage returns are preserved.
Argument | Description |
---|---|
1 | Expected output as a string for echo command with trailing newline disabled and backslash escapes enabled. |
* | Command. |
Example:
tt_expect_output_esc_ne "Expected Output" my_command arg1 arg2 || return 1
tt_expect_output_nlines_eq
tests if a command output exactly n lines of text
on stdout.
Argument | Description |
---|---|
1 | Expected number of lines. |
* | Command. |
Example:
tt_expect_output_nlines_eq 3 my_command arg1 arg2 || return 1
tt_expect_output_nlines_ge
tests if a command output n lines or more of text
on stdout.
Argument | Description |
---|---|
1 | Expected minimum number of lines. |
* | Command. |
Example:
tt_expect_output_nlines_ge 3 my_command arg1 arg2 || return 1
tt_expect_output_re
tests if the output of a command matches a regular
expression. The output is stripped from carriage returns before comparison.
Argument | Description |
---|---|
1 | Regular expression. |
* | Command. |
Example:
tt_expect_output_re "A.*B" my_command arg1 arg2 || return 1
tt_expect_str_null
tests if a string is empty.
Argument | Description |
---|---|
1 | String. |
2 | Message (optional). |
Example:
tt_expect_str_null $s "My Msg." || return 1
tt_expect_str_not_null
tests if a string is not empty.
Argument | Description |
---|---|
1 | String. |
2 | Message (optional). |
Example:
tt_expect_str_not_null $s "My Msg." || return 1
tt_expect_str_eq
tests if two strings are equal.
Argument | Description |
---|---|
1 | First string. |
2 | Second string. |
3 | Message (optional). |
Example:
tt_expect_str_eq $s "abc" "My Msg." || return 1
tt_expect_str_ne
tests if two strings are different.
Argument | Description |
---|---|
1 | First string. |
2 | Second string. |
3 | Message (optional). |
Example:
tt_expect_str_ne $s "abc" "My Msg." || return 1
tt_expect_str_re
tests if a string matches an ERE.
Argument | Description |
---|---|
1 | String. |
2 | Pattern as an ERE. |
3 | Message (optional). |
Example:
tt_expect_str_re $s "^[a-zA-Z]+-[0-9]+$" "My Msg" || return 1
tt_expect_num_eq
tests the equality of two integers.
Argument | Description |
---|---|
1 | First integer. |
2 | Second integer. |
3 | Message (optional). |
Example:
tt_expect_num_eq $n 2 "My Msg." || return 1
tt_expect_num_ne
tests that two integers are different.
Argument | Description |
---|---|
1 | First integer. |
2 | Second integer. |
3 | Message (optional). |
Example:
tt_expect_num_ne $$n 2 "My Msg." || return 1
tt_expect_num_le
tests that an integer is lower or equal than another.
Argument | Description |
---|---|
1 | First integer. |
2 | Second integer. |
3 | Message (optional). |
Example:
tt_expect_num_le $$n 5 "My Msg" || return 1
tt_expect_num_gt
tests that an integer is strictly greater than another.
Argument | Description |
---|---|
1 | First integer. |
2 | Second integer. |
3 | Message (optional). |
Example:
tt_expect_num_gt $$n 5 "My Msg" || return 1
tt_expect_def_env_var
tests if an environment variable is defined and not
empty.
Argument | Description |
---|---|
1 | Name of the environement variable. |
2 | Message (optional). |
Example:
tt_expect_def_env_var MY_VAR "My Msg" || return 1
tt_expect_file
tests if file exists.
Argument | Description |
---|---|
1 | File. |
2 | Message (optional). |
Example:
tt_expect_folder "myFile" "My Msg" || return 1
tt_expect_folder
tests if folder exists.
Argument | Description |
---|---|
1 | Folder. |
2 | Message (optional). |
Example:
tt_expect_folder "myFolder" "My Msg" || return 1
tt_expect_symlink
tests if a symbolic link exists and points to a certain
location.
Argument | Description |
---|---|
1 | Symbolic link path. |
2 | The path to which the link points. |
3 | Message (optional). |
Example:
tt_expect_symlink "/my/sym/link" "/the/file/to/which/it/points"
tt_expect_no_path
tests if nothing exists (no file, no folder) at the
specified path.
Argument | Description |
---|---|
1 | Path. |
2 | Message (optional). |
Example:
tt_expect_no_path "myFolder" "My Msg" || return 1
tt_expect_same_folders
tests if two folders have the same content, using
diff
command.
Argument | Description |
---|---|
1 | First folder. |
2 | Second folder. |
Example:
tt_expect_same_folders "folderA" "folderB" || return 1
tt_expect_files_in_folder
tests if files matching a pattern exist inside a
folder.
Argument | Description |
---|---|
1 | Folder. |
2 | Files pattern as an ERE. |
3 | Message (optional). |
Example:
tt_expect_files_in_folder "myFolder" "^.*\.txt$" "My Msg" || return 1
tt_expect_other_files_in_folder
tests if a folder contains files not matching
a pattern.
Argument | Description |
---|---|
1 | Folder. |
2 | Files pattern as an ERE. |
3 | Message (optional). |
Example:
tt_expect_other_files_in_folder "myFolder" "^.*\.txt$" "My Msg" || return 1
tt_expect_no_other_files_in_folder
tests if a folder contains files matching
a pattern, and no other files.
Argument | Description |
---|---|
1 | Folder. |
2 | Files pattern as an ERE. |
3 | Message (optional). |
Example:
tt_expect_no_other_files_in_folder "myFolder" "^.*\.txt$" "My Msg" || return 1
tt_expect_files_in_tree
tests if files matching a pattern exist inside a tree
structure.
Argument | Description |
---|---|
1 | Folder in which to search recursively. |
2 | Files pattern as an ERE. |
3 | Message (optional). |
Example:
tt_expect_files_in_tree "myFolder" "^.*\.txt$" "My Msg" || return 1
tt_expect_other_files_in_tree
tests if files not matching a pattern exist
inside a tree structure, and no other files.
Argument | Description |
---|---|
1 | Folder in which to search recursively. |
2 | Files pattern as an ERE. |
3 | Message (optional). |
Example:
tt_expect_other_files_in_tree "myFolder" "^.*\.txt$" "My Msg" || return 1
tt_expect_no_other_files_in_tree
tests if files matching a pattern exist
inside a tree structure, and no other files.
Argument | Description |
---|---|
1 | Folder in which to search recursively. |
2 | Files pattern as an ERE. |
3 | Message (optional). |
Example:
tt_expect_no_other_files_in_tree "myFolder" "^.*\.txt$" "My Msg" || return 1
tt_expect_folder_is_writable
tests files can be created or modified inside a
folder.
Argument | Description |
---|---|
1 | Path to the folder. |
2 | Message (optional). |
Example:
tt_expect_folder_is_writable "myFolder" "My Msg" || return 1
tt_expect_same_files
tests if two files are identical.
Argument | Description |
---|---|
1 | First file |
2 | Second file |
Example:
tt_expect_same_files "myFile1" "myFile2" || return 1
tt_expect_empty_file
tests if a file exists and is empty.
Argument | Description |
---|---|
1 | File |
2 | Message (optional). |
Example:
tt_expect_empty_file "myFile" || return 1
tt_expect_non_empty_file
tests if a file exists and is not empty.
Argument | Description |
---|---|
1 | File |
2 | Message (optional). |
Example:
tt_expect_non_empty_file "myFile" || return 1
tt_expect_no_duplicated_row
tests if a file contains no duplicated rows.
Argument | Description |
---|---|
1 | File |
Example:
tt_expect_no_duplicated_row "myFile" || return 1
tt_expect_same_number_of_rows
tests if two files contain the same number of
lines.
Argument | Description |
---|---|
1 | First file |
2 | Second file |
Example:
tt_expect_same_number_of_rows "myFile1" "myFile2" || return 1
tt_expect_csv_has_columns
tests if a CSV file contains a set of columns.
Second argument is the separator character used in the CSV.
Argument | Description |
---|---|
1 | File |
2 | CSV separator character. |
3 | Expected column names separated by spaces. |
Example:
tt_expect_csv_has_columns "myfile.csv" "," "col1 col2 col3" || return 1
tt_expect_csv_not_has_columns
tests if a CSV file does not contain a set of
columns.
Argument | Description |
---|---|
1 | File |
2 | CSV separator character. |
3 | Column names separated by spaces. |
Example:
tt_expect_csv_not_has_columns "myfile.csv" "," "col1 col2 col3" || return 1
tt_expect_csv_identical_col_values
tests if two CSV files contain the same
column with the same values.
Argument | Description |
---|---|
1 | Column name. |
2 | First file. |
3 | Second file. |
4 | CSV separator character. |
Example:
tt_expect_csv_identical_col_values "myCol" "myFile1" "myFile2" ";" || return 1
tt_expect_csv_float_col_equals
tests if all the values of a CSV file column
are close to a float value.
Argument | Description |
---|---|
1 | File. |
2 | CSV separator. |
3 | Column name. |
4 | Float value. |
5 | Tolerance. |
Example:
tt_expect_csv_float_col_equals "myFile" "," "myCol" 10.01 0.01 || return 1
tt_expect_csv_same_col_names
tests if two CSV files contain the same column
names.
Argument | Description |
---|---|
1 | First file. |
2 | Second file. |
3 | CSV separator. |
4 | The number of columns on which to make the comparison. If unset all columns will be used (optional). |
5 | If set to 1, then double quotes will be removed from column names before comparison (optional). |
Example:
tt_expect_csv_same_col_names "myFile1" "myFile2" ";" 8 1 || return 1
Term | Description |
---|---|
ERE | Extended Regular Expression. |