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 #  This program is free software; you can redistribute it and/or modify
   6 #  it under the terms of the GNU General Public License as published by
   7 #  the Free Software Foundation; either version 2 of the License, or
   8 #  (at your option) any later version.
   9 #
  10 #  This program is distributed in the hope that it will be useful,
  11 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 #  GNU General Public License for more details.
  14 #
  15 #  You should have received a copy of the GNU General Public License
  16 #  along with this program; if not, write to the Free Software
  17 #  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18 #
  19
  20 This subtree contains an implementation of the subunit child protocol.
  21 Currently I have no plans to write a test runner in C, so I have not written
  22 an implementation of the parent protocol. [but will happily accept patches].
  23 This implementation is build using SCons and tested via 'check'.
  24 See the tests/ directory for the test programs.
  25 You can use `make check` or `scons check` to run the tests. I plan to write a
  26 'check' runner which uses these bindings to provide subunit output, at which
  27 point creating a trivial python test_c.py script which uses the pyunit gui to
  28 will be added to me todo list.
  29
  30 The C protocol consists of four functions which you can use to output test
  31 metadata trivially. See lib/subunit_child.[ch] for details.
  32
  33 However, this is not a test runner - subunit provides no support for [for
  34 instance] managing assertions, cleaning up on errors etc. You can look at
  35 'check' (http://check.sourceforge.net/) or
  36 'gunit' (http://kooditakomo.cs.tut.fi/projects/gunit/) for C unit test
  37 frameworks. I plan to write ui layers for both of these that use the subunit
  38 bindings for reporting. There is a patch for 'check' (check-subunit-patch-0.9.3)
  39 in this source tree. Its also available as request ID #1470750 in the sourceforge
  40 request tracker http://sourceforge.net/tracker/index.php.
  41
  42 If you are a test environment maintainer - either homegrown, or 'check' or
  43 'gunit' or some oether, you will to know how the subunit calls should be used.
  44 Here is what a manually written test using the bindings might look like:
  45
  46
  47 void
  48 a_test(void) {
  49   int result;
  50   subunit_test_start("test name");
  51   # determine if test passes or fails
  52   result = SOME_VALUE;
  53   if (!result) {
  54     subunit_test_pass("test name");
  55   } else {
  56     subunit_test_failf("test name",
  57       "Something went wrong running something:\n"
  58       "exited with result: '%s'", result);
  59   }
  60 }
  61
  62 Which when run with a subunit test runner will generate something like:
  63 test name ... ok
  64
  65 on success, and:
  66
  67 test name ... FAIL
  68
  69 ======================================================================
  70 FAIL: test name
  71 ----------------------------------------------------------------------
  72 RemoteError:
  73 Something went wrong running something:
  74 exited with result: '1'