Basic shell subunit bindings working.
[third_party/subunit] / shell / README
1 #
2 #  subunit shell 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 tree contains shell bindings to the subunit protocol. They are written 
21 entirely in shell, and unit tested in shell. See the tests/ directory for the
22 test scripts. You can use `make check` to run the tests. There is a trivial
23 python test_shell.py which uses the pyunit gui to expose the test results in a
24 compact form.
25
26 The shell bindings consist of four functions which you can use to output test
27 metadata trivially. See share/subunit.sh for the functions and comments.
28
29 However, this is not a full test environment, its support code for reporting to
30 subunit. You can look at ShUnit (http://shunit.sourceforge.net) for 'proper' 
31 shell based xUnit functionality. I am currently integrating subunit into ShUnit
32 so you should be able to get both subunit an ShUnit easily.
33
34 If you are a test environment maintainer - either homegrown, or ShUnit or some
35 such, you will need to see how the subunit calls should be used. Here is what
36 a manually written test using the bindings might look like:
37
38
39 subunit_start_test "test name"
40 # determine if test passes or fails
41 result=$(something)
42 if [ $result == 0 ]; then
43   subunit_pass_test "test name"
44 else
45   subunit_fail_test "test name" <<END
46 Something went wrong running something:
47 exited with result: '$func_status'
48 END
49 fi
50
51 Which when run with a subunit test runner will generate something like:
52 test name ... ok
53
54 on success, and:
55
56 test name ... FAIL
57
58 ======================================================================
59 FAIL: test name
60 ----------------------------------------------------------------------
61 RemoteError:
62 Something went wrong running something:
63 exited with result: '1'