samba-mirror/lib/subunit/shell/README

#
#  subunit shell bindings.
#  Copyright (C) 2006  Robert Collins <robertc@robertcollins.net>
#
#  Licensed under either the Apache License, Version 2.0 or the BSD 3-clause
#  license at the users choice. A copy of both licenses are available in the
#  project source as Apache-2.0 and BSD. You may not use this file except in
#  compliance with one of these two licences.
#  
#  Unless required by applicable law or agreed to in writing, software
#  distributed under these licenses is distributed on an "AS IS" BASIS, WITHOUT
#  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
#  license you chose for the specific language governing permissions and
#  limitations under that license.
#

This tree contains shell bindings to the subunit protocol. They are written
entirely in shell, and unit tested in shell. See the tests/ directory for the
test scripts. You can use `make check` to run the tests. There is a trivial
python test_shell.py which uses the pyunit gui to expose the test results in a
compact form.

The shell bindings consist of four functions which you can use to output test
metadata trivially. See share/subunit.sh for the functions and comments.

However, this is not a full test environment, its support code for reporting to
subunit. You can look at ShUnit (http://shunit.sourceforge.net) for 'proper'
shell based xUnit functionality. There is a patch for ShUnit 1.3
(subunit-ui.patch) in the subunit source tree. I hope to have that integrated
upstream in the near future. I will delete the copy of the patch in the subunit
tree a release or two later.

If you are a test environment maintainer - either homegrown, or ShUnit or some
such, you will need to see how the subunit calls should be used. Here is what
a manually written test using the bindings might look like:


subunit_start_test "test name"
# determine if test passes or fails
result=$(something)
if [ $result == 0 ]; then
  subunit_pass_test "test name"
else
  subunit_fail_test "test name" <<END
Something went wrong running something:
exited with result: '$func_status'
END
fi

Which when run with a subunit test runner will generate something like:
test name ... ok

on success, and:

test name ... FAIL

======================================================================
FAIL: test name
----------------------------------------------------------------------
RemoteError:
Something went wrong running something:
exited with result: '1'