This project is stored on code.google.com as http://code.google.com/p/shunit2/. +All releases as of 2.1.4 and full source are available there. Documentation is +included as part of the source and each release. Source code is stored in +Subversion and can be accessed using the following information.
+Browse the code in a web browser:
+Check out the code locally
++$ svn checkout http://shunit2.googlecode.com/svn/trunk/ shflags-read-only ++
DEPRECATED
+This project is stored on SourceForge as http://sf.net/projects/shunit2. The +source code is stored in Subversion and can be accessed using the following +information.
+Check out the code locally
++$ svn co https://shunit2.svn.sourceforge.net/svnroot/shunit2/trunk/source/2.1 shunit2 ++
Browse the code in a web browser:
+ +For these steps, it is assumed we are working with release 2.0.0.
+Steps:
+This should be pretty self explanatory. Use one of the release notes from a +previous release as an example.
+The versions of the various platforms and shells are included when the +master unit test script is run, or when bin/gen_test_results.sh is +used. To determine the versions of the installed shells by hand, use the +lib/versions script.
+Alternatively, do the following:
+| Shell | +OS | +Notes | +
|---|---|---|
| bash | ++ | $ bash --version | +
| dash | +Linux | +$ dpkg -l |grep dash | +
| ksh | ++ | $ ksh --version +-or- +$ echo 'echo $KSH_VERSION' |ksh | +
| Cygwin | +see pdksh | +|
| Solaris | +$ strings /usr/bin/ksh |grep 'Version' | +|
| pdksh | ++ | $ strings /bin/pdksh |grep 'PD KSH' | +
| Cygwin | +look in the downloaded Cygwin directory | +|
| sh | +Solaris | +not possible | +
| zsh | ++ | $ zsh --version | +
Edit src/shell/shunit2 and change the version number in the comment, as well +as in the SHUNIT_VERSION variable.
+Make sure that any remaining changes get put into the CHANGES-X.X.txt file.
+Finish writing the RELEASE_NOTES-X.X.X.txt. If necessary, run it +through the fmt command to make it pretty (hopefully it is already).
++$ fmt -w 80 RELEASE_NOTES-2.0.0.txt >RELEASE_NOTES-2.0.0.txt.new +$ mv RELEASE_NOTES-2.0.0.txt.new RELEASE_NOTES-2.0.0.txt ++
We want to have an up-to-date version of the documentation in the release, so +we'd better build it.
+
+$ pwd
+.../shunit2/source/2.1
+$ cd doc
+$ RST2HTML_OPTS='--stylesheet-path=rst2html.css'
+$ rst2html ${RST2HTML_OPTS} shunit2.txt >shunit2.html
+$ rst2html ${RST2HTML_OPTS} README.txt >README.html
+
+This step is pretty self-explanatory
++$ pwd +.../shunit2/source/2.0 +$ svn ci -m "finalizing release" ++
+$ pwd +.../shunit2/source +$ ls +2.0 2.1 +$ svn cp -m "Release 2.0.0" 2.0 https://shunit2.googlecode.com/svn/tags/source/2.0.0 ++
+$ pwd +.../shunit2/builds +$ svn export https://shunit2.googlecode.com/svn/tags/source/2.0.0 shunit2-2.0.0 ++
+$ tar cfz ../releases/shunit2-2.0.0.tgz shunit2-2.0.0 ++
+$ cd ../releases +$ gpg --default-key kate.ward@forestent.com --detach-sign shunit2-2.0.0.tgz ++
Again, pretty self-explanatory. Make sure to copy the GPG signature file. Once +that is done, make sure to tag the website so we can go back in time if needed.
++$ pwd +.../shunit2 +$ ls +source website +$ svn cp -m "Release 2.0.0" \ +website https://shunit2.googlecode.com/svn/tags/website/20060916 ++
Now, update the website. It too is held in Subversion, so ssh into the web +server and use svn up to grab the latest version.
+shUnit2 is a xUnit unit test framework for Bourne based shell scripts, and it +is designed to work in a similar manner to JUnit, PyUnit, etc.. If you have +ever had the desire to write a unit test for a shell script, shUnit2 can do the +job.
+Table of Contents
+shUnit2 was originally developed to provide a consistent testing solution for +log4sh, a shell based logging framework similar to log4j. During the +development of that product, a repeated problem of having things work just fine +under one shell (/bin/bash on Linux to be specific), and then not working +under another shell (/bin/sh on Solaris) kept coming up. Although several +simple tests were run, they were not adequate and did not catch some corner +cases. The decision was finally made to write a proper unit test framework after +multiple brown-bag releases were made. Research was done to look for an +existing product that met the testing requirements, but no adequate product was +found.
+Tested Operating Systems (varies over time)
+Tested Shells
+See the appropriate Release Notes for this release +(doc/RELEASE_NOTES-X.X.X.txt) for the list of actual versions tested.
+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 is most certainly welcome for this document. Send your additions, +comments and criticisms to the shunit2-users@google.com mailing list.
+This section will give a very quick start to running unit tests with shUnit2. +More information is located in later sections.
+Here is a quick sample script to show how easy it is to write a unit test in +shell. Note: the script as it stands expects that you are running it from the +``examples`` directory.
+
+#! /bin/sh
+# file: examples/equality_test.sh
+
+testEquality()
+{
+ assertEquals 1 1
+}
+
+# load shunit2
+. ../src/shell/shunit2
+
+Running the unit test should give results similar to the following.
++testEquality + +Ran 1 test. + +OK ++
W00t! You've just run your first successful unit test. So, what just happened? +Quite a bit really, and it all happened simply by sourcing the shunit2 +library. The basic functionality for the script above goes like this:
+We should now try adding a test that fails. Change your unit test to look like +this.
+
+#! /bin/sh
+# file: examples/party_test.sh
+
+testEquality()
+{
+ assertEquals 1 1
+}
+
+testPartyLikeItIs1999()
+{
+ year=`date '+%Y'`
+ assertEquals "It's not 1999 :-(" \
+ '1999' "${year}"
+}
+
+# load shunit2
+. ../src/shell/shunit2
+
+So, what did you get? I guess it told you that this isn't 1999. Bummer, eh? +Hopefully, you noticed a couple of things that were different about the second +test. First, we added an optional message that the user will see if the assert +fails. Second, we did comparisons of strings instead of integers as in the first +test. It doesn't matter whether you are testing for equality of strings or +integers. Both work equally well with shUnit2.
+Hopefully, this is enough to get you started with unit testing. If you want a +ton more examples, take a look at the tests provided with log4sh or shFlags. +Both provide excellent examples of more advanced usage. shUnit2 was after all +written to help with the unit testing problems that log4sh had.
+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 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.
+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``.
+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.
+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.
+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.
+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.
+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.
+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.
+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.
+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.
+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.
+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.
+This section covers several advanced usage topics.
+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. | +
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.
+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:
+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' '""' ++
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.
+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.
+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>.
+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.
+In the unit-test script, add the following shell code snippet before sourcing +the shunit2 library.
++setopt shwordsplit ++
When invoking zsh from either the command-line or as a script with +#!, add the -y parameter.
++#! /bin/zsh -y ++
When invoking zsh from the command-line, add -o shwordsplit -- as +parameters before the script name.
++$ zsh -o shwordsplit -- some_script ++