NAME
TAP::Formatter::TeamCity - Emit test results as TeamCity service
messages
SYNOPSIS
# When using prove(1):
prove -formatter TAP::Formatter::TeamCity my_test.t
# From within a Module::Build subclass:
sub tap_harness_args { return {formatter_class => 'TAP::Formatter::TeamCity'} }
DESCRIPTION
TAP::Formatter::TeamCity is a plugin for TAP::Harness that emits
TeamCity service messages to the console, rather than the usual output.
The TeamCity build server is able to process these messages in the build
log and present your test results in its web interface (along with some
nice statistics and graphs).
This is very much alpha code, and is subject to change.
SEE IT IN ACTION
If you're not familiar with continuous integration systems (in general)
or TeamCity (in particular), you're welcome to explore the TeamCity
build server we use for the Perl::Critic project. Just go to
<
http://perlcritic.com:8111> and click on the "Login as a Guest" link.
From there, you can browse the build history, review test results, and
examine the artifacts (such as test coverage reports and performance
profiles). All the information you see there was generated from
TAP-based tests using this module to communicate the results to the
TeamCity server.
SUGGESTED USAGE
The TeamCity service messages are generally not human-readable, so you
probably only want to use this Formatter when the tests are being run by
a TeamCity build agent and the TAP::Formatter::TeamCity module is
available. I suggest using an environment variable to activate the
Formatter. If you're using a recent version of Module::Build you might
do something like this in your Build.PL file:
# Regular build configuration here:
my $builder = Module::Build->new( ... )
# Specify this Formatter, if the environment variable is set:
$builder->tap_harness_args( {formatter_class => 'TAP::Formatter::TeamCity'} )
if $ENV{RUNNING_UNDER_TEAMCITY} && eval {require TAP::Formatter::TeamCity};
# Generate build script as ususal:
$builder->create_build_script();
And then set the "RUNNING_UNDER_TEAMCITY" environment variable to a true
value in your TeamCity build configuration.
TODO: Figure out if/how to do this with ExtUtils::MakeMaker.
LIMITATIONS
TeamCity comes from a jUnit culture, so it doesn't understand SKIP and
TODO tests in the same way that Perl testing harnesses do. Therefore,
this formatter simply instructs TeamCity to ignore tests that are marked
SKIP or TODO.
Also, I haven't yet figured out how to transmit test diagnostic
messages, so those probably won't appear in the TeamCity web interface.
But I'm working on it :)
SOME EXTRA CANDY
TeamCity, CruiseControl, and some other continuous integration systems
are oriented towards Java code. As such, they don't have native support
for Perl's customary build tools like Module::Build. But they do have
nice support for running Ant. This distribution contains an Ant build
script at build.xml which wraps Module::Build actions in Ant targets.
This makes it easier to configure TeamCity and CruiseControl to build
your Perl code. If you're using the EPIC plug-in with Eclipse, you can
also use this Ant script to build your code from within the IDE. Feel
free to copy the build.xml into your own projects.
SEE ALSO
TeamCity::BuildMessages
AUTHOR
Jeffrey Ryan Thalhammer <
[email protected]>
COPYRIGHT
Copyright (c) 2009 Imaginative Software Systems. All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. The full text of this license can
be found in the LICENSE file included with this module.
