Credits / Contributors

A list of contributors to shUnit2 can be found in the source archive in doc/contributors.txt. Many thanks go out to all those who have contributed to make this a better tool.

shUnit2 is the original product of many hours of work by Kate Ward, the primary author of the code. For other products by her, look up log4sh or shFlags, or visit her website at http://forestent.com/.

Feedback

Feedback is most certainly welcome for this document. Send your additions, comments and criticisms to the shunit2-users@google.com mailing list.

General Info

Any string values passed should be properly quoted -- they should must be surrounded by single-quote (') or double-quote (") characters -- so that the shell will properly parse them.

Asserts

assertEquals [message] expected actual

Asserts that expected and actual are equal to one another. The expected and actual values can be either strings or integer values as both will be treated as strings. The message is optional, and must be quoted.

assertNotEquals [message] expected actual

Asserts that unexpected and actual are not equal to one another. The unexpected and actual values can be either strings or integer values as both will be treaded as strings. The message is optional, and must be quoted.

assertSame [message] expected actual

This function is functionally equivalent to assertEquals.

assertNotSame [message] unexpected actual

This function is functionally equivalent to assertNotEquals.

assertNull [message] value

Asserts that value is null, or in shell terms, a zero-length string. The value must be a string as an integer value does not translate into a zero-length string. The message is optional, and must be quoted.

assertNotNull [message] value

Asserts that value is not null, or in shell terms, a non-empty string. The value may be a string or an integer as the later will be parsed as a non-empty string value. The message is optional, and must be quoted.

assertTrue [message] condition

Asserts that a given shell test condition is true. The condition can be as simple as a shell true value (the value 0 -- equivalent to ${SHUNIT_TRUE}), or a more sophisticated shell conditional expression. The message is optional, and must be quoted.

A sophisticated shell conditional expression is equivalent to what the if or while shell built-ins would use (more specifically, what the test command would use). Testing for example whether some value is greater than another value can be done this way.

assertTrue "[ 34 -gt 23 ]"

Testing for the ability to read a file can also be done. This particular test will fail.

assertTrue 'test failed' "[ -r /some/non-existant/file' ]"

As the expressions are standard shell test expressions, it is possible to string multiple expressions together with -a and -o in the standard fashion. This test will succeed as the entire expression evaluates to true.

assertTrue 'test failed' '[ 1 -eq 1 -a 2 -eq 2 ]'

One word of warning: be very careful with your quoting as shell is not the most forgiving of bad quoting, and things will fail in strange ways.

assertFalse [message] condition

Asserts that a given shell test condition is false. The condition can be as simple as a shell false value (the value 1 -- equivalent to ${SHUNIT_FALSE}), or a more sophisticated shell conditional expression. The message is optional, and must be quoted.

For examples of more sophisticated expressions, see ``assertTrue``.

Failures

Just to clarify, failures do not test the various arguments against one another. Failures simply fail, optionally with a message, and that is all they do. If you need to test arguments against one another, use asserts.

If all failures do is fail, why might one use them? There are times when you may have some very complicated logic that you need to test, and the simple asserts provided are simply not adequate. You can do your own validation of the code, use an assertTrue ${SHUNIT_TRUE} if your own tests succeeded, and use a failure to record a failure.

fail [message]

Fails the test immediately. The message is optional, and must be quoted.

failNotEquals [message] unexpected actual

Fails the test immediately, reporting that the unexpected and actual values are not equal to one another. The message is optional, and must be quoted.

Note: no actual comparison of unexpected and actual is done.

failSame [message] expected actual

Fails the test immediately, reporting that the expected and actual values are the same. The message is optional, and must be quoted.

Note: no actual comparison of expected and actual is done.

failNotSame [message] expected actual

Fails the test immediately, reporting that the expected and actual values are not the same. The message is optional, and must be quoted.

Note: no actual comparison of expected and actual is done.

Setup/Teardown

oneTimeSetUp

This function can be be optionally overridden by the user in their test suite.

If this function exists, it will be called once before any tests are run. It is useful to prepare a common environment for all tests.

oneTimeTearDown

This function can be be optionally overridden by the user in their test suite.

If this function exists, it will be called once after all tests are completed. It is useful to clean up the environment after all tests.

setUp

This function can be be optionally overridden by the user in their test suite.

If this function exists, it will be called before each test is run. It is useful to reset the environment before each test.

tearDown

This function can be be optionally overridden by the user in their test suite.

If this function exists, it will be called after each test completes. It is useful to clean up the environment after each test.

Skipping

startSkipping

This function forces the remaining assert and fail functions to be "skipped", i.e. they will have no effect. Each function skipped will be recorded so that the total of asserts and fails will not be altered.

endSkipping

This function returns calls to the assert and fail functions to their default behavior, i.e. they will be called.

isSkipping

This function returns the current state of skipping. It can be compared against ${SHUNIT_TRUE} or ${SHUNIT_FALSE} if desired.

Suites

The default behavior of shUnit2 is that all tests will be found dynamically. If you have a specific set of tests you want to run, or you don't want to use the standard naming scheme of prefixing your tests with test, these functions are for you. Most users will never use them though.

suite

This function can be optionally overridden by the user in their test suite.

If this function exists, it will be called when shunit2 is sourced. If it does not exist, shUnit2 will search the parent script for all functions beginning with the word test, and they will be added dynamically to the test suite.

suite_addTest name

This function adds a function named name to the list of tests scheduled for execution as part of this test suite. This function should only be called from within the suite() function.

Some constants you can use

There are several constants provided by shUnit2 as variables that might be of use to you.

Predefined

SHUNIT_VERSION	The version of shUnit2 you are running.
SHUNIT_TRUE	Standard shell true value (the integer value 0).
SHUNIT_FALSE	Standard shell false value (the integer value 1).
SHUNIT_ERROR	The integer value 2.
SHUNIT_TMPDIR	Path to temporary directory that will be automatically cleaned up upon exit of shUnit2.

User defined

SHUNIT_PARENT

The filename of the shell script containing the tests. This is needed specifically for Zsh support.

Error handling

The constants values SHUNIT_TRUE, SHUNIT_FALSE, and SHUNIT_ERROR are returned from nearly every function to indicate the success or failure of the function. Additionally the variable flags_error is filled with a detailed error message if any function returns with a SHUNIT_ERROR value.

Including Line Numbers in Asserts (Macros)

If you include lots of assert statements in an individual test function, it can become difficult to determine exactly which assert was thrown unless your messages are unique. To help somewhat, line numbers can be included in the assert messages. To enable this, a special shell "macro" must be used rather than the standard assert calls. Shell doesn't actually have macros; the name is used here as the operation is similar to a standard macro.

For example, to include line numbers for a assertEquals() function call, replace the assertEquals() with ${_ASSERT_EQUALS_}.

Example -- Asserts with and without line numbers

#! /bin/sh
# file: examples/lineno_test.sh

testLineNo()
{
  # this assert will have line numbers included (e.g. "ASSERT:[123] ...")
  echo "ae: ${_ASSERT_EQUALS_}"
  ${_ASSERT_EQUALS_} 'not equal' 1 2

  # this assert will not have line numbers included (e.g. "ASSERT: ...")
  assertEquals 'not equal' 1 2
}

# load shunit2
. ../src/shell/shunit2

Notes:

1. Due to how shell parses command-line arguments, all strings used with macros should be quoted twice. Namely, single-quotes must be converted to single-double-quotes, and vice-versa. If the string being passed is absolutely for sure not empty, the extra quoting is not necessary.

   Normal assertEquals call.

   assertEquals 'some message' 'x' ''
   

   Macro _ASSERT_EQUALS_ call. Note the extra quoting around the message and the null value.

   _ASSERT_EQUALS_ '"some message"' 'x' '""'
   

2. Line numbers are not supported in all shells. If a shell does not support them, no errors will be thrown. Supported shells include: bash (>=3.0), ksh, pdksh, and zsh.

Test Skipping

There are times where the test code you have written is just not applicable to the system you are running on. This section describes how to skip these tests but maintain the total test count.

Probably the easiest example would be shell code that is meant to run under the bash shell, but the unit test is running under the Bourne shell. There are things that just won't work. The following test code demonstrates two sample functions, one that will be run under any shell, and the another that will run only under the bash shell.

Example -- math include

# available as examples/math.inc

add_generic()
{
  num_a=$1
  num_b=$2

  expr $1 + $2
}

add_bash()
{
  num_a=$1
  num_b=$2

  echo $(($1 + $2))
}

And here is a corresponding unit test that correctly skips the add_bash() function when the unit test is not running under the bash shell.

Example -- math unit test

#! /bin/sh
# available as examples/math_test.sh

testAdding()
{
  result=`add_generic 1 2`
  assertEquals \
      "the result of '${result}' was wrong" \
      3 "${result}"

  # disable non-generic tests
  [ -z "${BASH_VERSION:-}" ] && startSkipping

  result=`add_bash 1 2`
  assertEquals \
      "the result of '${result}' was wrong" \
      3 "${result}"
}

oneTimeSetUp()
{
  # load include to test
  . ./math.inc
}

# load and run shUnit2
. ../src/shell/shunit2

Running the above test under the bash shell will result in the following output.

$ /bin/bash math_test.sh
testAdding

Ran 1 test.

OK

But, running the test under any other Unix shell will result in the following output.

$ /bin/ksh math_test.sh
testAdding

Ran 1 test.

OK (skipped=1)

As you can see, the total number of tests has not changed, but the report indicates that some tests were skipped.

Skipping can be controlled with the following functions: startSkipping(), stopSkipping(), and isSkipping(). Once skipping is enabled, it will remain enabled until the end of the current test function call, after which skipping is disabled.

Getting help

For help, please send requests to either the shunit2-users@googlegroups.com mailing list (archives available on the web at http://groups.google.com/group/shunit2-users) or directly to Kate Ward <kate dot ward at forestent dot com>.

Zsh

For compatibility with Zsh, there is one requirement that must be met -- the shwordsplit option must be set. There are three ways to accomplish this.

1. In the unit-test script, add the following shell code snippet before sourcing the shunit2 library.

   setopt shwordsplit
   

2. When invoking zsh from either the command-line or as a script with #!, add the -y parameter.

   #! /bin/zsh -y
   

3. When invoking zsh from the command-line, add -o shwordsplit -- as parameters before the script name.

   $ zsh -o shwordsplit -- some_script