2
2
subunit: A streaming protocol for test results
3
Copyright (C) 2005 Robert Collins <robertc@robertcollins.net>
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.
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.
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
3
Copyright (C) 2005-2009 Robert Collins <robertc@robertcollins.net>
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.
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.
16
See the COPYING file for full details on the licensing of Subunit.
20
18
subunit reuses iso8601 by Michael Twomey, distributed under an MIT style
21
19
licence - see python/iso8601/LICENSE for details.
138
135
Subunit protocol description
139
136
============================
138
This description is being ported to an EBNF style. Currently its only partly in
139
that style, but should be fairly clear all the same. When in doubt, refer the
140
source (and ideally help fix up the description!). Generally the protocol is
141
line orientated and consists of either directives and their parameters, or
142
when outside a DETAILS region unexpected lines which are not interpreted by
143
the parser - they should be forwarded unaltered.
140
145
test|testing|test:|testing: test label
141
146
success|success:|successful|successful: test label
142
success|success:|successful|successful: test label [
147
success|success:|successful|successful: test label DETAILS
146
148
failure: test label
150
failure: test label [
149
failure: test label DETAILS
153
150
error: test label
151
error: test label DETAILS
156
152
skip[:] test label
153
skip[:] test label DETAILS
159
154
xfail[:] test label
160
xfail[:] test label [
155
xfail[:] test label DETAILS
166
160
time: YYYY-MM-DD HH:MM:SSZ
162
DETAILS ::= BRACKETED | MULTIPART
163
BRACKETED ::= '[' CR lines ']' CR
164
MULTIPART ::= '[ multipart' CR PART* ']' CR
165
PART ::= PART_TYPE CR NAME CR PART_BYTES CR
166
PART_TYPE ::= Content-Type: type/sub-type(;parameter=value,parameter=value)
167
PART_BYTES ::= (DIGITS CR LF BYTE{DIGITS})* '0' CR LF
167
169
unexpected output on stdout -> stdout.
168
170
exit w/0 or last test completing -> error
189
191
environments - such as those that organise tests into suites - the top-most
190
192
runner can report on the number of suites, and each suite surround its output
191
193
with a (push, pop) pair. Interpreters should interpret a pop as also advancing
192
the progress of the restored level by one step.
194
the progress of the restored level by one step. Encountering progress
195
directives between the start and end of a test pair indicates that a previous
196
test was interrupted and did not cleanly terminate: it should be implicitly
197
closed with an error (the same as when a stream ends with no closing test
198
directive for the most recently started test).
194
200
The time directive acts as a clock event - it sets the time for all future
195
201
events. The value should be a valid ISO8601 time.