++ed by:
Author image Jeffrey Ryan Thalhammer
and 1 contributors


TAP::Formatter::TeamCity - Emit test results as TeamCity service messages


   # 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'} }


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.


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.


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:

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.


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 :)


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.




Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>


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.