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