.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.48)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "TAP::Formatter::JUnit 3"
.TH TAP::Formatter::JUnit 3 2026-09-24 "perl v5.44.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
TAP::Formatter::JUnit \- Harness output delegate for JUnit output
.SH SYNOPSIS
.IX Header "SYNOPSIS"
On the command line, with \fIprove\fR:
.PP
.Vb 1
\&  $ prove \-\-formatter TAP::Formatter::JUnit ...
.Ve
.PP
Or, in your own scripts:
.PP
.Vb 1
\&  use TAP::Harness;
\&
\&  # What TAP output did we save from a previous run, with
\&  # PERL_TEST_HARNESS_DUMP_TAP=tap/
\&  my @tests = glob("tap/*.t");
\&
\&  # Convert the TAP to JUnit
\&  my $harness = TAP::Harness\->new( {
\&      formatter_class => \*(AqTAP::Formatter::JUnit\*(Aq,
\&      merge => 1,
\&  } );
\&  $harness\->runtests(@tests);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBThis code is currently in alpha state and is subject to change.\fR
.PP
\&\f(CW\*(C`TAP::Formatter::JUnit\*(C'\fR provides JUnit output formatting for \f(CW\*(C`TAP::Harness\*(C'\fR.
.PP
By default (e.g. when run with \fIprove\fR), the \fIentire\fR test suite is gathered
together into a single JUnit XML document, which is then displayed on \f(CW\*(C`STDOUT\*(C'\fR.
You can, however, have individual JUnit XML files dumped for each individual
test, by setting \f(CW\*(C`PERL_TEST_HARNESS_DUMP_TAP\*(C'\fR to a directory that you would
like the JUnit XML dumped to.  Note, that this will \fBalso\fR cause
\&\f(CW\*(C`TAP::Harness\*(C'\fR to dump the original TAP output into that directory as well (but
IMHO that\*(Aqs ok as you\*(Aqve now got the data in two parseable formats).
.PP
Timing information is included in the JUnit XML, \fIif\fR you specified \f(CW\*(C`\-\-timer\*(C'\fR
when you ran \fIprove\fR.
.PP
In standard use, a "passing TODO" is treated as failure conditions (and is
reported as such in the generated JUnit).  If you wish to treat these as a
"pass" and not a "fail" condition, setting \f(CW\*(C`ALLOW_PASSING_TODOS\*(C'\fR in your
environment will turn these into pass conditions.
.PP
The JUnit output generated is partial to being grokked by Hudson
(<http://hudson.dev.java.net/>).  That\*(Aqs the build tool I\*(Aqm using at the
moment and needed to be able to generate JUnit output for.
.SH ATTRIBUTES
.IX Header "ATTRIBUTES"
.IP testsuites 4
.IX Item "testsuites"
List\-ref of test suites that have been executed.
.IP xml 4
.IX Item "xml"
An \f(CW\*(C`XML::Generator\*(C'\fR instance, to be used to generate XML output.
.SH METHODS
.IX Header "METHODS"
.ie n .IP "open_test($test, $parser)" 4
.el .IP "open_test($test, \f(CW$parser\fR)" 4
.IX Item "open_test($test, $parser)"
Over\-ridden \f(CWopen_test()\fR method.
.Sp
Creates a \f(CW\*(C`TAP::Formatter::JUnit::Session\*(C'\fR session, instead of a console
formatter session.
.IP \fBsummary()\fR 4
.IX Item "summary()"
Prints the summary report (in JUnit) after all tests are run.
.IP add_testsuite($suite) 4
.IX Item "add_testsuite($suite)"
Adds the given XML test \f(CW$suite\fR to the list of test suites that we\*(Aqve
executed and need to summarize.
.SH AUTHOR
.IX Header "AUTHOR"
Graham TerMarsch <cpan@howlingfrog.com>
.PP
Many thanks to Andy Armstrong and all those involved for the \fBfabulous\fR set of
tests in \f(CW\*(C`Test::Harness\*(C'\fR; they became the basis for the unit tests here.
.PP
Other thanks go out to those that have provided feedback, comments, or patches:
.PP
.Vb 7
\&  Mark Aufflick
\&  Joe McMahon
\&  Michael Nachbaur
\&  Marc Abramowitz
\&  Colin Robertson
\&  Phillip Kimmey
\&  Dave Lambley
.Ve
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2008\-2010, Graham TerMarsch.  All Rights Reserved.
.PP
This is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP TAP::Formatter::Console 4
.IX Item "TAP::Formatter::Console"
.PD 0
.IP TAP::Formatter::JUnit::Session 4
.IX Item "TAP::Formatter::JUnit::Session"
.IP "Hudson home page <http://hudson.dev.java.net/>" 4
.IX Item "Hudson home page <http://hudson.dev.java.net/>"
.IP "JUnitXSchema.xsd <http://jra1mw.cvs.cern.ch:8180/cgi-bin/jra1mw.cgi/org.glite.testing.unit/config/JUnitXSchema.xsd?view=markup&content-type=text%2Fvnd.viewcvs-markup&revision=HEAD>" 4
.IX Item "JUnitXSchema.xsd <http://jra1mw.cvs.cern.ch:8180/cgi-bin/jra1mw.cgi/org.glite.testing.unit/config/JUnitXSchema.xsd?view=markup&content-type=text%2Fvnd.viewcvs-markup&revision=HEAD>"
.IP "JUnit parsing in Bamboo <http://confluence.atlassian.com/display/BAMBOO/JUnit+parsing+in+Bamboo>." 4
.IX Item "JUnit parsing in Bamboo <http://confluence.atlassian.com/display/BAMBOO/JUnit+parsing+in+Bamboo>."
.PD