git.samba.org - third_party/subunit/blob - c/README

   1 #
   2 #  subunit C 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 This subtree contains an implementation of the subunit child protocol.
  17 Currently I have no plans to write a test runner in C, so I have not written
  18 an implementation of the parent protocol. [but will happily accept patches].
  19 This implementation is built using SCons and tested via 'check'.
  20 See the tests/ directory for the test programs.
  21 You can use `make check` or `scons check` to run the tests.
  22
  23 The C protocol consists of four functions which you can use to output test
  24 metadata trivially. See lib/subunit_child.[ch] for details.
  25
  26 However, this is not a test runner - subunit provides no support for [for
  27 instance] managing assertions, cleaning up on errors etc. You can look at
  28 'check' (http://check.sourceforge.net/) or
  29 'gunit' (https://garage.maemo.org/projects/gunit) for C unit test
  30 frameworks.
  31 There is a patch for 'check' (check-subunit-*.patch) in this source tree.
  32 Its also available as request ID #1470750 in the sourceforge request tracker
  33 http://sourceforge.net/tracker/index.php. The 'check' developers have indicated
  34 they will merge this during the current release cycle.
  35
  36 If you are a test environment maintainer - either homegrown, or 'check' or
  37 'gunit' or some other, you will to know how the subunit calls should be used.
  38 Here is what a manually written test using the bindings might look like:
  39
  40
  41 void
  42 a_test(void) {
  43   int result;
  44   subunit_test_start("test name");
  45   # determine if test passes or fails
  46   result = SOME_VALUE;
  47   if (!result) {
  48     subunit_test_pass("test name");
  49   } else {
  50     subunit_test_failf("test name",
  51       "Something went wrong running something:\n"
  52       "exited with result: '%s'", result);
  53   }
  54 }
  55
  56 Which when run with a subunit test runner will generate something like:
  57 test name ... ok
  58
  59 on success, and:
  60
  61 test name ... FAIL
  62
  63 ======================================================================
  64 FAIL: test name
  65 ----------------------------------------------------------------------
  66 RemoteError:
  67 Something went wrong running something:
  68 exited with result: '1'