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