torokmark/assert.sh

:exclamation: Assertion lib for shell script users

assert.sh

Assert.sh is intended to give the assertion mechanism to shell scripts with well-known assert functions like assert_eq, assert_array_eq, or assert_empty. Inspired by Assert class of JUnit

Install & Usage

> $ git clone https://github.com/torokmark/assert.sh.git; cd assert.sh
> $ source assert.sh
> $ assert_eq "hello" "world"
> $ echo "$?"
# => 1

I. Clone the repository

git clone https://github.com/torokmark/assert.sh.git

Or copy the assert.sh where your project is located.

II. Edit the script where you would like to use asserts and paste the next line on the top:

source './assert.sh'

III. Now assert functions are available for use.

assert_eq "hello" "world"

0 return status is considered true and anything else is considered false.

List of assert functions

• assert_eq takes two strings and checks whether they are the same based on the character strings.
• assert_not_eq is the opposite of assert_eq.
• assert_true takes a parameter and returns 0 confirming the parameter is true.
• assert_false takes a parameter and decides whether it is false.
• assert_array_eq takes two arrays and compare them by items.
• assert_array_not_eq takes two arrays and return 0 if the items are not the same on the same index.
• assert_empty takes a string and returns 0 if it is empty
• assert_not_empty is the opposite of assert_empty.
• assert_contain checks whether the first argument contains the second one.
• assert_not_contain check whether the first argument does not contain the second one.
• assert_gt checks whether the first param is greater than the second.
• assert_ge checks whether the first param is greator than or equal to the second one.
• assert_lt checks whether the first param is less than the second one.
• assert_le checks whether the first param is less than or equal to the second one.

How to write tests

Example:

source "./assert.sh"

local expected actual
expected="Hello"
actual="World!"
assert_eq "$expected" "$actual" "not equivalent!"
# => x Hello == World :: not equivalent! 

source "./assert.sh"

local expected actual
expected="Hello"
actual="Hello"
assert_eq "$expected" "$actual"
if [ "$?" == 0 ]; then
  log_success "assert_eq returns 0 if two words are equal"
else
  log_failure "assert_eq should return 0"
fi

If the return status ($?) of assert_eq is equal to 0, which is considered true according to the convention. If the assert function returns 1, the expected and actual values are differred.

assert.sh's Issues

assert_true don't stdout msg

root@xiaorui:~# assert_true false "cause error"
root@xiaorui:~# echo $?
1

Possible function name collision and unexpected behavior due to this...

Example of an undefined behavior:

my_funcs.sh

#!/usr/bin/env bash

log_success() {
    echo "another log_success() function from $BASH_SOURCE file that behaves differently"
}

test.sh

#!/usr/bin/env bash

source assert.sh # this file contains `log_success` function

source my_funcs.sh # this file also contains `log_success` function

# Example from README
expected="Hello"
actual="Hello"
assert_eq "$expected" "$actual"
if [ "$?" == 0 ]; then
  log_success "assert_eq returns 0 if two words are equal"
else
  log_failure "assert_eq should return 0"
fi

Output:

$ ./test.sh 
another log_success() function from my_funcs.sh file that behaves differently

To fix this the tester will be forced to rename all files where log_success function is used.

In advanced and much complex languages this is solved by using namespace mechanism. Since bash does not have something simillar we can craft namespaces simply by appending postfixes. I offer something like this to make the name as unique as possible:

log_success__torokmark () {
...
}

It is still comfortable when using any editor with an autocomplete engine.

Same story with tput codes inside variables with kinda generic names...

assert.sh/assert.sh

Lines 23 to 27 in a845148

	RED=$(tput setaf 1)
	GREEN=$(tput setaf 2)
	MAGENTA=$(tput setaf 5)
	NORMAL=$(tput sgr0)
	BOLD=$(tput bold)

Message parameter on assert_not_empty

Hello,

assert_not_empty uses third parameter as message but second one seems not used (https://github.com/torokmark/assert.sh/blob/master/assert.sh#L188)

This prevent assert_not_empty function to be written as follow
assert_not_empty "my string" "This is the message"

And must be written with a second empty parameter, exactly like assert_not_eq
assert_not_empty "my string" "" "This is the message"

array_contains support