Remove stale import from shell/SConsscript.
[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. There is a patch for ShUnit 1.3 
32 (subunit-ui.patch) in the subunit source tree. I hope to have that integrated 
33 upstream in the near future. I will delete the copy of the patch in the subunit
34 tree a release or two later.
35
36 If you are a test environment maintainer - either homegrown, or ShUnit or some
37 such, you will need to see how the subunit calls should be used. Here is what
38 a manually written test using the bindings might look like:
39
40
41 subunit_start_test "test name"
42 # determine if test passes or fails
43 result=$(something)
44 if [ $result == 0 ]; then
45   subunit_pass_test "test name"
46 else
47   subunit_fail_test "test name" <<END
48 Something went wrong running something:
49 exited with result: '$func_status'
50 END
51 fi
52
53 Which when run with a subunit test runner will generate something like:
54 test name ... ok
55
56 on success, and:
57
58 test name ... FAIL
59
60 ======================================================================
61 FAIL: test name
62 ----------------------------------------------------------------------
63 RemoteError:
64 Something went wrong running something:
65 exited with result: '1'