fe41d9a76f1326739444fb8a982375f2949dad33
[third_party/subunit] / README
1
2   subunit: A streaming protocol for test results
3   Copyright (C) 2005-2009 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   See the COPYING file for full details on the licensing of Subunit.
17
18   subunit reuses iso8601 by Michael Twomey, distributed under an MIT style
19   licence - see python/iso8601/LICENSE for details.
20
21
22 Subunit
23 -------
24
25 Subunit is a streaming protocol for test results. The protocol is human
26 readable and easily generated and parsed. By design all the components of 
27 the protocol conceptually fit into the xUnit TestCase->TestResult interaction.
28
29 Subunit comes with command line filters to process a subunit stream and
30 language bindings for python, C, C++ and shell. Bindings are easy to write
31 for other languages.
32
33 A number of useful things can be done easily with subunit:
34  * Test aggregation: Tests run separately can be combined and then
35    reported/displayed together. For instance, tests from different languages
36    can be shown as a seamless whole.
37  * Test archiving: A test run may be recorded and replayed later.
38  * Test isolation: Tests that may crash or otherwise interact badly with each
39    other can be run seperately and then aggregated, rather than interfering
40    with each other.
41  * Grid testing: subunit can act as the necessary serialisation and
42    deserialiation to get test runs on distributed machines to be reported in
43    real time.
44
45 Subunit supplies the following filters:
46  * tap2subunit - convert perl's TestAnythingProtocol to subunit.
47  * subunit2pyunit - convert a subunit stream to pyunit test results.
48  * subunit2gtk - show a subunit stream in GTK.
49  * subunit2junitxml - convert a subunit stream to JUnit's XML format.
50  * subunit-diff - compare two subunit streams.
51  * subunit-filter - filter out tests from a subunit stream.
52  * subunit-ls - list info about tests present in a subunit stream.
53  * subunit-stats - generate a summary of a subunit stream.
54  * subunit-tags - add or remove tags from a stream.
55
56 Integration with other tools
57 ----------------------------
58
59 Subunit's language bindings act as integration with various test runners like
60 'check', 'cppunit', Python's 'unittest'. Beyond that a small amount of glue
61 (typically a few lines) will allow Subunit to be used in more sophisticated
62 ways.
63
64 Python
65 ======
66
67 Subunit has excellent Python support: most of the filters and tools are written
68 in python and there are facilities for using Subunit to increase test isolation
69 seamlessly within a test suite.
70
71 One simple way to run an existing python test suite and have it output subunit
72 is the module ``subunit.run``::
73
74   $ python -m subunit.run mypackage.tests.test_suite
75  
76 For more information on the Python support Subunit offers , please see
77 ``pydoc subunit``, or the source in ``python/subunit/__init__.py``
78
79 C
80 =
81
82 Subunit has C bindings to emit the protocol, and comes with a patch for 'check'
83 which has been nominally accepted by the 'check' developers. See 'c/README' for
84 more details.
85
86 C++
87 ===
88
89 C++ uses the C bindings and includes a patch for cppunit. See 'c++/README' for
90 details.
91
92 shell
93 =====
94
95 Similar to C, the shell bindings consist of simple functions to output protocol
96 elements, and a patch for adding subunit output to the 'ShUnit' shell test
97 runner. See 'shell/README' for details.
98
99 Filter recipes
100 --------------
101
102 To ignore some failing tests whose root cause is already known::
103
104   subunit-filter --without 'AttributeError.*flavor'
105
106
107 The protocol
108 ------------
109
110 Sample subunit wire contents
111 ----------------------------
112
113 The following::
114   test: test foo works
115   success: test foo works.
116   test: tar a file.
117   failure: tar a file. [
118   ..
119    ]..  space is eaten.
120   foo.c:34 WARNING foo is not defined.
121   ]
122   a writeln to stdout
123
124 When run through subunit2pyunit::
125   .F
126   a writeln to stdout
127
128   ========================
129   FAILURE: tar a file.
130   -------------------
131   ..
132   ]..  space is eaten.
133   foo.c:34 WARNING foo is not defined.
134
135
136 Subunit protocol description
137 ============================
138
139 This description is being ported to an EBNF style. Currently its only partly in
140 that style, but should be fairly clear all the same. When in doubt, refer the
141 source (and ideally help fix up the description!). Generally the protocol is
142 line orientated and consists of either directives and their parameters, or
143 when outside a DETAILS region unexpected lines which are not interpreted by
144 the parser - they should be forwarded unaltered.
145
146 test|testing|test:|testing: test label
147 success|success:|successful|successful: test label
148 success|success:|successful|successful: test label DETAILS
149 failure: test label
150 failure: test label DETAILS
151 error: test label
152 error: test label DETAILS
153 skip[:] test label
154 skip[:] test label DETAILS
155 xfail[:] test label
156 xfail[:] test label DETAILS
157 progress: [+|-]X
158 progress: push
159 progress: pop
160 tags: [-]TAG ...
161 time: YYYY-MM-DD HH:MM:SSZ
162
163 DETAILS ::= BRACKETED | MULTIPART
164 BRACKETED ::= '[' CR lines ']' CR
165 MULTIPART ::= '[ multiparent' CR PART* ']' CR
166 PART ::= PART_TYPE CR PART_LENGTH CR PART_BYTES CR
167 PART_TYPE ::= Content-Type: type/sub-type(;parameter=label)
168 PART_LENGTH ::= DIGITS
169
170 unexpected output on stdout -> stdout.
171 exit w/0 or last test completing -> error
172
173 Tags given outside a test are applied to all following tests
174 Tags given after a test: line and before the result line for the same test
175 apply only to that test, and inherit the current global tags.
176 A '-' before a tag is used to remove tags - e.g. to prevent a global tag
177 applying to a single test, or to cancel a global tag.
178
179 The progress directive is used to provide progress information about a stream
180 so that stream consumer can provide completion estimates, progress bars and so
181 on. Stream generators that know how many tests will be present in the stream
182 should output "progress: COUNT". Stream filters that add tests should output
183 "progress: +COUNT", and those that remove tests should output
184 "progress: -COUNT". An absolute count should reset the progress indicators in
185 use - it indicates that two separate streams from different generators have
186 been trivially concatenated together, and there is no knowledge of how many
187 more complete streams are incoming. Smart concatenation could scan each stream
188 for their count and sum them, or alternatively translate absolute counts into
189 relative counts inline. It is recommended that outputters avoid absolute counts
190 unless necessary. The push and pop directives are used to provide local regions
191 for progress reporting. This fits with hierarchically operating test
192 environments - such as those that organise tests into suites - the top-most
193 runner can report on the number of suites, and each suite surround its output
194 with a (push, pop) pair. Interpreters should interpret a pop as also advancing
195 the progress of the restored level by one step. Encountering progress
196 directives between the start and end of a test pair indicates that a previous
197 test was interrupted and did not cleanly terminate: it should be implicitly
198 closed with an error (the same as when a stream ends with no closing test
199 directive for the most recently started test).
200
201 The time directive acts as a clock event - it sets the time for all future
202 events. The value should be a valid ISO8601 time.
203
204 The skip result is used to indicate a test that was found by the runner but not
205 fully executed due to some policy or dependency issue. This is represented in
206 python using the addSkip interface that testtools
207 (https://edge.launchpad.net/testtools) defines. When communicating with a non
208 skip aware test result, the test is reported as an error.
209 The xfail result is used to indicate a test that was expected to fail failing
210 in the expected manner. As this is a normal condition for such tests it is
211 represented as a successful test in Python.
212 In future, skip and xfail results will be represented semantically in Python,
213 but some discussion is underway on the right way to do this.