lib/subunit/shell/README

   1 #
   2 #  subunit shell bindings.
   3 #  Copyright (C) 2006  Robert Collins <robertc@robertcollins.net>
   4 #
   5 #  Licensed under either the Apache License, Version 2.0 or the BSD 3-clause
   6 #  license at the users choice. A copy of both licenses are available in the
   7 #  project source as Apache-2.0 and BSD. You may not use this file except in
   8 #  compliance with one of these two licences.
   9 #
  10 #  Unless required by applicable law or agreed to in writing, software
  11 #  distributed under these licenses is distributed on an "AS IS" BASIS, WITHOUT
  12 #  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
  13 #  license you chose for the specific language governing permissions and
  14 #  limitations under that license.
  15 #
  16
  17 This tree contains shell bindings to the subunit protocol. They are written
  18 entirely in shell, and unit tested in shell. See the tests/ directory for the
  19 test scripts. You can use `make check` to run the tests. There is a trivial
  20 python test_shell.py which uses the pyunit gui to expose the test results in a
  21 compact form.
  22
  23 The shell bindings consist of four functions which you can use to output test
  24 metadata trivially. See share/subunit.sh for the functions and comments.
  25
  26 However, this is not a full test environment, its support code for reporting to
  27 subunit. You can look at ShUnit (http://shunit.sourceforge.net) for 'proper'
  28 shell based xUnit functionality. There is a patch for ShUnit 1.3
  29 (subunit-ui.patch) in the subunit source tree. I hope to have that integrated
  30 upstream in the near future. I will delete the copy of the patch in the subunit
  31 tree a release or two later.
  32
  33 If you are a test environment maintainer - either homegrown, or ShUnit or some
  34 such, you will need to see how the subunit calls should be used. Here is what
  35 a manually written test using the bindings might look like:
  36
  37
  38 subunit_start_test "test name"
  39 # determine if test passes or fails
  40 result=$(something)
  41 if [ $result == 0 ]; then
  42   subunit_pass_test "test name"
  43 else
  44   subunit_fail_test "test name" <<END
  45 Something went wrong running something:
  46 exited with result: '$func_status'
  47 END
  48 fi
  49
  50 Which when run with a subunit test runner will generate something like:
  51 test name ... ok
  52
  53 on success, and:
  54
  55 test name ... FAIL
  56
  57 ======================================================================
  58 FAIL: test name
  59 ----------------------------------------------------------------------
  60 RemoteError:
  61 Something went wrong running something:
  62 exited with result: '1'