lib/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 Subunit
  22 -------
  23
  24 Subunit is a streaming protocol for test results. The protocol is human
  25 readable and easily generated and parsed. By design all the components of
  26 the protocol conceptually fit into the xUnit TestCase->TestResult interaction.
  27
  28 Subunit comes with command line filters to process a subunit stream and
  29 language bindings for python, C, C++ and shell. Bindings are easy to write
  30 for other languages.
  31
  32 A number of useful things can be done easily with subunit:
  33  * Test aggregation: Tests run separately can be combined and then
  34    reported/displayed together. For instance, tests from different languages
  35    can be shown as a seamless whole.
  36  * Test archiving: A test run may be recorded and replayed later.
  37  * Test isolation: Tests that may crash or otherwise interact badly with each
  38    other can be run separately and then aggregated, rather than interfering
  39    with each other.
  40  * Grid testing: subunit can act as the necessary serialisation and
  41    deserialiation to get test runs on distributed machines to be reported in
  42    real time.
  43
  44 Subunit supplies the following filters:
  45  * tap2subunit - convert perl's TestAnythingProtocol to subunit.
  46  * subunit2csv - convert a subunit stream to csv.
  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 The C library is includable and usable directly from C++. A TestListener for
  90 CPPUnit is included in the Subunit distribution. See 'c++/README' for 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 uxsuccess[:] test LABEL
 158 uxsuccess[:] test LABEL DETAILS
 159 progress: [+|-]X
 160 progress: push
 161 progress: pop
 162 tags: [-]TAG ...
 163 time: YYYY-MM-DD HH:MM:SSZ
 164
 165 LABEL: UTF8*
 166 DETAILS ::= BRACKETED | MULTIPART
 167 BRACKETED ::= '[' CR UTF8-lines ']' CR
 168 MULTIPART ::= '[ multipart' CR PART* ']' CR
 169 PART ::= PART_TYPE CR NAME CR PART_BYTES CR
 170 PART_TYPE ::= Content-Type: type/sub-type(;parameter=value,parameter=value)
 171 PART_BYTES ::= (DIGITS CR LF BYTE{DIGITS})* '0' CR LF
 172
 173 unexpected output on stdout -> stdout.
 174 exit w/0 or last test completing -> error
 175
 176 Tags given outside a test are applied to all following tests
 177 Tags given after a test: line and before the result line for the same test
 178 apply only to that test, and inherit the current global tags.
 179 A '-' before a tag is used to remove tags - e.g. to prevent a global tag
 180 applying to a single test, or to cancel a global tag.
 181
 182 The progress directive is used to provide progress information about a stream
 183 so that stream consumer can provide completion estimates, progress bars and so
 184 on. Stream generators that know how many tests will be present in the stream
 185 should output "progress: COUNT". Stream filters that add tests should output
 186 "progress: +COUNT", and those that remove tests should output
 187 "progress: -COUNT". An absolute count should reset the progress indicators in
 188 use - it indicates that two separate streams from different generators have
 189 been trivially concatenated together, and there is no knowledge of how many
 190 more complete streams are incoming. Smart concatenation could scan each stream
 191 for their count and sum them, or alternatively translate absolute counts into
 192 relative counts inline. It is recommended that outputters avoid absolute counts
 193 unless necessary. The push and pop directives are used to provide local regions
 194 for progress reporting. This fits with hierarchically operating test
 195 environments - such as those that organise tests into suites - the top-most
 196 runner can report on the number of suites, and each suite surround its output
 197 with a (push, pop) pair. Interpreters should interpret a pop as also advancing
 198 the progress of the restored level by one step. Encountering progress
 199 directives between the start and end of a test pair indicates that a previous
 200 test was interrupted and did not cleanly terminate: it should be implicitly
 201 closed with an error (the same as when a stream ends with no closing test
 202 directive for the most recently started test).
 203
 204 The time directive acts as a clock event - it sets the time for all future
 205 events. The value should be a valid ISO8601 time.
 206
 207 The skip, xfail and uxsuccess outcomes are not supported by all testing
 208 environments. In Python the testttools (https://launchpad.net/testtools)
 209 library is used to translate these automatically if an older Python version
 210 that does not support them is in use. See the testtools documentation for the
 211 translation policy.
 212
 213 skip is used to indicate a test was discovered but not executed. xfail is used
 214 to indicate a test that errored in some expected fashion (also know as "TODO"
 215 tests in some frameworks). uxsuccess is used to indicate and unexpected success
 216 where a test though to be failing actually passes. It is complementary to
 217 xfail.
 218
 219 Hacking on subunit
 220 ------------------
 221
 222 Releases
 223 ========
 224
 225 * Update versions in configure.ac and python/subunit/__init__.py.
 226 * Make PyPI and regular tarball releases. Upload the regular one to LP, the
 227   PyPI one to PyPI.
 228 * Push a tagged commit.
 229