diff options
Diffstat (limited to 'fluent-bit/tests/lib/shunit2/README.md')
| -rw-r--r-- | fluent-bit/tests/lib/shunit2/README.md | 636 |
1 files changed, 636 insertions, 0 deletions
diff --git a/fluent-bit/tests/lib/shunit2/README.md b/fluent-bit/tests/lib/shunit2/README.md new file mode 100644 index 00000000..dd6bba42 --- /dev/null +++ b/fluent-bit/tests/lib/shunit2/README.md @@ -0,0 +1,636 @@ +# shUnit2 + +shUnit2 is a [xUnit](http://en.wikipedia.org/wiki/XUnit) unit test framework for +Bourne based shell scripts, and it is designed to work in a similar manner to +[JUnit](http://www.junit.org), [PyUnit](http://pyunit.sourceforge.net), etc.. If +you have ever had the desire to write a unit test for a shell script, shUnit2 +can do the job. + +[](https://travis-ci.org/kward/shunit2) + +## Table of Contents + +* [Introduction](#introduction) + * [Credits / Contributors](#credits-contributors) + * [Feedback](#feedback) +* [Quickstart](#quickstart) +* [Function Reference](#function-reference) + * [General Info](#general-info) + * [Asserts](#asserts) + * [Failures](#failures) + * [Setup/Teardown](#setup-teardown) + * [Skipping](#skipping) + * [Suites](#suites) +* [Advanced Usage](#advanced-usage) + * [Some constants you can use](#some-constants-you-can-use) + * [Error Handling](#error-handling) + * [Including Line Numbers in Asserts (Macros)](#including-line-numbers-in-asserts-macros) + * [Test Skipping](#test-skipping) + * [Running specific tests from the command line](#cmd-line-args) +* [Appendix](#appendix) + * [Getting help](#getting-help) + * [Zsh](#zsh) + +--- + +## <a name="introduction"></a> Introduction + +shUnit2 was originally developed to provide a consistent testing solution for +[log4sh][log4sh], a shell based logging framework similar to +[log4j](http://logging.apache.org). 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 software + +**Tested Operating Systems** (varies over time) + +OS | Support | Verified +----------------------------------- | --------- | -------- +Ubuntu Linux (14.04.05 LTS) | Travis CI | continuous +macOS High Sierra (10.13.3) | Travis CI | continuous +FreeBSD | user | unknown +Solaris 8, 9, 10 (inc. OpenSolaris) | user | unknown +Cygwin | user | unknown + +**Tested Shells** + +* Bourne Shell (__sh__) +* BASH - GNU Bourne Again SHell (__bash__) +* DASH (__dash__) +* Korn Shell (__ksh__) +* pdksh - Public Domain Korn Shell (__pdksh__) +* zsh - Zsh (__zsh__) (since 2.1.2) _please see the Zsh shell errata for more information_ + +See the appropriate Release Notes for this release +(`doc/RELEASE_NOTES-X.X.X.txt`) for the list of actual versions tested. + +### <a name="credits-contributors"></a> Credits / Contributors + +A list of contributors to shUnit2 can be found in `doc/contributors.md`. 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 related software, check out https://github.com/kward. + +### <a name="feedback"></a> Feedback + +Feedback is most certainly welcome for this document. Send your questions, +comments, and criticisms via the +[shunit2-users](https://groups.google.com/a/forestent.com/forum/#!forum/shunit2-users/new) +forum (created 2018-12-09), or file an issue via +https://github.com/kward/shunit2/issues. + +--- + +## <a name="quickstart"></a> Quickstart + +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._ + +```sh +#! /bin/sh +# file: examples/equality_test.sh + +testEquality() { + assertEquals 1 1 +} + +# Load shUnit2. +. ./shunit2 +``` + +Running the unit test should give results similar to the following. + +```console +$ cd examples +$ ./equality_test.sh +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: + +* When shUnit2 is sourced, it will walk through any functions defined whose name + starts with the string `test`, and add those to an internal list of tests to + execute. Once a list of test functions to be run has been determined, shunit2 + will go to work. +* Before any tests are executed, shUnit2 again looks for a function, this time + one named `oneTimeSetUp()`. If it exists, it will be run. This function is + normally used to setup the environment for all tests to be run. Things like + creating directories for output or setting environment variables are good to + place here. Just so you know, you can also declare a corresponding function + named `oneTimeTearDown()` function that does the same thing, but once all the + tests have been completed. It is good for removing temporary directories, etc. +* shUnit2 is now ready to run tests. Before doing so though, it again looks for + another function that might be declared, one named `setUp()`. If the function + exists, it will be run before each test. It is good for resetting the + environment so that each test starts with a clean slate. **At this stage, the + first test is finally run.** The success of the test is recorded for a report + that will be generated later. After the test is run, shUnit2 looks for a final + function that might be declared, one named `tearDown()`. If it exists, it will + be run after each test. It is a good place for cleaning up after each test, + maybe doing things like removing files that were created, or removing + directories. This set of steps, `setUp() > test() > tearDown()`, is repeated + for all of the available tests. +* Once all the work is done, shUnit2 will generate the nice report you saw + above. A summary of all the successes and failures will be given so that you + know how well your code is doing. + +We should now try adding a test that fails. Change your unit test to look like +this. + +```sh +#! /bin/sh +# file: examples/party_test.sh + +testEquality() { + assertEquals 1 1 +} + +testPartyLikeItIs1999() { + year=`date '+%Y'` + assertEquals "It's not 1999 :-(" '1999' "${year}" +} + +# Load shUnit2. +. ./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][log4sh] or +[shFlags][shflags]. Both provide excellent examples of more advanced usage. +shUnit2 was after all written to meet the unit testing need that +[log4sh][log4sh] had. + +--- + +## <a name="function-reference"></a> Function Reference + +### <a name="general-info"></a> 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. + +### <a name="asserts"></a> 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] unexpected 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`. + +`assertContains [message] container content` + +Asserts that _container_ contains _content_. The _container_ and _content_ +values can be either strings or integer values as both will be treated as +strings. The _message_ is optional, and must be quoted. + +`assertNotContains [message] container content` + +Asserts that _container_ does not contain _content_. The _container_ and +_content_ values can be either strings or integer values as both will be treaded +as strings. The _message_ is optional, and must be quoted. + +`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 ]'` + +<i>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.</i> + +`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`._ + +### <a name="failures"></a> 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._ + +`failFound [message] content` + +Fails the test immediately, reporting that the _content_ was found. The +_message_ is optional, and must be quoted. + +_Note: no actual search of content is done._ + +`failNotFound [message] content` + +Fails the test immediately, reporting that the _content_ was not found. The +_message_ is optional, and must be quoted. + +_Note: no actual search of content is done._ + +### <a name="setup-teardown"></a> 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. + +### <a name="skipping"></a> 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. + +### <a name="suites"></a> 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. + +--- + +## <a name="advanced-usage"></a> Advanced Usage + +### <a name="some-constants-you-can-use"></a> Some constants you can use + +There are several constants provided by shUnit2 as variables that might be of +use to you. + +*Predefined* + +| Constant | Value | +| --------------- | ----- | +| 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. | +| SHUNIT\_VERSION | The version of shUnit2 you are running. | + +*User defined* + +| Constant | Value | +| ----------------- | ----- | +| SHUNIT\_CMD\_EXPR | Override which `expr` command is used. By default `expr` is used, except on BSD systems where `gexpr` is used. | +| SHUNIT\_COLOR | Enable colorized output. Options are 'auto', 'always', or 'none', with 'auto' being the default. | +| SHUNIT\_PARENT | The filename of the shell script containing the tests. This is needed specifically for Zsh support. | +| SHUNIT\_TEST\_PREFIX | Define this variable to add a prefix in front of each test name that is output in the test report. | + +### <a name="error-handling"></a> 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. + +### <a name="including-line-numbers-in-asserts-macros"></a> 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_ + +```sh +#! /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. +. ./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.<br/> + <br/> + Normal `assertEquals` call.<br/> + `assertEquals 'some message' 'x' ''`<br/> + <br/> + Macro `_ASSERT_EQUALS_` call. Note the extra quoting around the _message_ and + the _null_ value.<br/> + `_ASSERT_EQUALS_ '"some message"' 'x' '""'` + +1. 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__. + +### <a name="test-skipping"></a> 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_ +```sh +# file: 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_ +```sh +#! /bin/sh +# file: 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. +. ./shunit2 +``` + +Running the above test under the __bash__ shell will result in the following +output. + +```console +$ /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. + +```console +$ /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()`, +`endSkipping()`, and `isSkipping()`. Once skipping is enabled, it will remain +enabled until the end of the current test function call, after which skipping is +disabled. + +### <a name="cmd-line-args"></a> Running specific tests from the command line. + +When running a test script, you may override the default set of tests, or the suite-specified set of tests, by providing additional arguments on the command line. Each additional argument after the `--` marker is assumed to be the name of a test function to be run in the order specified. e.g. + +```console +test-script.sh -- testOne testTwo otherFunction +``` + +or + +```console +shunit2 test-script.sh testOne testTwo otherFunction +``` + +In either case, three functions will be run as tests, `testOne`, `testTwo`, and `otherFunction`. Note that the function `otherFunction` would not normally be run by `shunit2` as part of the implicit collection of tests as it's function name does not match the test function name pattern `test*`. + +If a specified test function does not exist, `shunit2` will still attempt to run that function and thereby cause a failure which `shunit2` will catch and mark as a failed test. All other tests will run normally. + +The specification of tests does not affect how `shunit2` looks for and executes the setup and tear down functions, which will still run as expected. + +--- + +## <a name="appendix"></a> Appendix + +### <a name="getting-help"></a> Getting Help + +For help, please send requests to either the shunit2-users@forestent.com mailing +list (archives available on the web at +https://groups.google.com/a/forestent.com/forum/#!forum/shunit2-users) or +directly to Kate Ward <kate dot ward at forestent dot com>. + +### <a name="zsh"></a> 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. + + ```sh + setopt shwordsplit + ``` + +2. When invoking __zsh__ from either the command-line or as a script with `#!`, + add the `-y` parameter. + + ```sh + #! /bin/zsh -y + ``` + +3. When invoking __zsh__ from the command-line, add `-o shwordsplit --` as + parameters before the script name. + + ```console + $ zsh -o shwordsplit -- some_script + ``` + +[log4sh]: https://github.com/kward/log4sh +[shflags]: https://github.com/kward/shflags |