                          JUnit text format REFERENCE
                          ===========================


This is the reference of the text format that your test package
can output to produce a test report.

For an introduction to test packages, see HOWTO-testpackage.txt.


Basic syntax
============

  ###junit testsuite

Start a new series of tests
XML equivalent: <testsuite>

  ###junit endsuite

End up current series of tests
XML equivalent: (none)

  ###junit testcase

Start new test case
XML equivalent: <testcase>

  ###junit success

End up current test case as successful
XML equivalent: (none)

  ###junit skipped

End up current test case as skipped
XML equivalent: <skipped>

  ###junit failure

End up current test case as failed
XML equivalent: <failure>

  ###junit error

End up current test case as aborted because of an internal error
XML equivalent: <error>


Example
=======

Here is how the output of your test package could look like:

  Calculator test suite
  Written by Hans Mustermann, <hmustermann@suse.com>
  Version 0.11, last modified 2015-04-05
	
  ###junit testsuite time="2015-04-16T17:30:37.655" text="Testing the calculator functions"
	
  ###junit testcase time="2015-04-16T17:30:37.655" text="verify addition"
  Additions. Let's try 5 + 3...
  Works! Got 8.
  ###junit success time="2015-04-16T17:30:37.655"
	
  ###junit testcase time="2015-04-16T17:30:37.655" text="verify division"
  Array operations. Let's try A[-1] = 5...
  Ouch! Got Segmentation failure, expected Out of bounds.
  ###junit failure time="2015-04-16T17:30:37.656" type="Segmentation failure"
	
  ###junit endsuite time="2015-04-16T17:30:37.656"
	
  Goodbye!


Attributes
==========

You can use XML attributes in this text output, for example time="...".

Since JUnit normally refers to Java testing, the semantics of a few fields
is abused. For example, text="...", which we use for an arbitrary description,
maps to JUnit name="..." attribute, which normally refers to a Java class name.

Still, the result is guaranteed to validate against JUnit.xsd schema.

Note that embedded quotes are legal. For example,

  ###junit testsuite text="Tests for "Calculator" program"

with embedded quotes around "Calculator" is allowed.
It is not needed (nor possible) to escape the embedded quotes.

To accomodate for future extensions, unrecognized attributes are
simply ignored.


testsuite keyword
=================

Your test package should output "###junit testsuite" first,
to introduce a new series of test cases.
Use it as many times as you have different test suites.

  time="..."

Date and time of beginning of test suite run.
Format: ISO 8601 with milliseconds
        (http://en.wikipedia.org/wiki/ISO_8601)
Default value: "1970-01-01T00:00:00.000"
XML equivalent: timestamp="..."

  id="..."

Identifier for the test suite. It is ignored by Jenkins.
Format: XML schema xs:token
        (http://www.w3schools.com/schema/schema_dtypes_string.asp)
Default value: "(unknown)"
XML equivalent: package="..."

  text="..."

Any text describing the test suite.
Format: XML schema xs:token
        (http://www.w3schools.com/schema/schema_dtypes_string.asp)
Default value: "(unknown)"
XML equivalent: name="..."

  host="..."

Name of host where the suite is run.
Format: XML schema xs:token
        (http://www.w3schools.com/schema/schema_dtypes_string.asp)
Default value: "localhost"
XML equivalent: hostname="..."



endsuite keyword
================

After a series of related test cases, your test package
should output "###junit endsuite".

  time="..."

Date and time of end of test suite run.
Format: ISO 8601 with milliseconds
        (http://en.wikipedia.org/wiki/ISO_8601)
Default value: "1970-01-01T00:00:00.000"
XML equivalent: (none)


The following JUnit XML attributes and tags are generated automatically:

  id=""

Serial number of this test suite, starting at 0.

  time=""

Test suite duration in seconds.

  tests=""

Number of test cases in the suite.

  failures=""

Number of failed test cases in the suite.

  errors=""

Number of test cases in the suite that have aborted due to internal errors.

  <system-err>

Dump of stderr output.


testcase keyword
================

When it starts a new test case as part of a test suite,
your test package should output "###junit testcase".

  time="..."

Date and time of beginning of test case.
Format: ISO 8601 with milliseconds
        (http://en.wikipedia.org/wiki/ISO_8601) with milliseconds
Default value: "1970-01-01T00:00:00.000"

  id="..."

Identifier for the test case. Jenkins works best with an identifier
in dotted syntax. In Java world, that would be something of the
form "package.class.method".
Format: XML schema xs:token
        (http://www.w3schools.com/schema/schema_dtypes_string.asp)
Default value: "(unknown)"
XML equivalent: classname="..."

  text="..."

Any text describing the test case.
Format: XML schema xs:token
        (http://www.w3schools.com/schema/schema_dtypes_string.asp)
Default value: "(unknown)"
XML equivalent: name="..."


success keyword
===============

When the current test case succeeds (that is, the tested software behaved
as expected), your test package should output "###junit success".

  time="..."

Date and time of the end of the test case run.
Format: ISO 8601 with milliseconds
        (http://en.wikipedia.org/wiki/ISO_8601)
Default value: "1970-01-01T00:00:00.000"
XML equivalent: (none)

The following JUnit XML attributes is generated automatically:

  time=""

Test case duration in seconds.


skipped keyword
===============

When the current test case was not run (that is, it was skipped),
your test package should output "###junit skipped".

  time="..."

Date and time of the end of the test case run.
Format: ISO 8601 with milliseconds
        (http://en.wikipedia.org/wiki/ISO_8601)
Default value: "1970-01-01T00:00:00.000"
XML equivalent: (none)

The following JUnit XML attributes and tags are generated automatically:

  time=""

Test case duration in seconds.

  <skipped>

An empty tag.


failure keyword
===============

When the current test case failed (that is, the tested software did not
behave as expected), your test package should output "###junit failure"
and provide some diagnostic.

  time="..."

Date and time of the end of the test case run.
Format: ISO 8601 with milliseconds
        (http://en.wikipedia.org/wiki/ISO_8601)
Default value: "1970-01-01T00:00:00.000"
XML equivalent: (none)

  type="..."

Type of failure. It could be the name of an exception.
Format: XML schema xs:string
        (http://www.w3schools.com/schema/schema_dtypes_string.asp)
Default value: "randomError"
XML equivalent: type="..."

  text=""

Failure message.
Format: XML schema xs:string
        (http://www.w3schools.com/schema/schema_dtypes_string.asp)
Default value: "(unknown)"
XML equivalent: message="..."

The following JUnit XML attributes and tags are generated automatically:

  time=""

Test case duration in seconds.

  <failure>

A dump of stderr.


error keyword
=============

When the test case itself was not able to complete because of an
internal error, your test package should output "###junit error"
and provide some diagnostic.

  time="..."

Date and time of the end of the test case run.
Format: ISO 8601 with milliseconds
        (http://en.wikipedia.org/wiki/ISO_8601)
Default value: "1970-01-01T00:00:00.000"
XML equivalent: (none)

  type="..."

Type of error. It could be the name of an exception.
Format: XML schema xs:string
        (http://www.w3schools.com/schema/schema_dtypes_string.asp)
Default value: "randomError"
XML equivalent: type=".."

  text=""

Error message.
Format: XML schema xs:string
        (http://www.w3schools.com/schema/schema_dtypes_string.asp)
Default value: "(unknown)"
XML equivalent: message="..."

The following JUnit XML attributes and tags are generated automatically:

  time=""

Test case duration in seconds.

  <error>

A dump of stderr.

