NAME

Module::Build::TestReporter - help users report test failures

SYNOPSIS

  use Module::Build::TestReporter;
  my $build = Module::Build::TestReporter->new(
        # normal Module::Build code here
  );

  # or, in your own M::B subclass

  package My::Module::Build;

  use Class::Roles does => 'Module::Build::TestReporter';

  # your code as usual

DESCRIPTION

Shipping test suites with your code is a good thing, as it helps your users know that your code works as you expect on your systems and it allows you better debugging information if things break in environments where you haven't yet tested your code. However, it can be tedious and tricky to convince your users to send you the appropriate failure information.

Module::Build::TestReporter extends and enhances Module::Build to collect information on test failures and the Perl environment for users to send to you. Rather than walking them through running tests in verbose mode on the phone, in IRC, or via e-mail, use this module alongside your usual Module::Build build process and it will gather this information in case of failure.

USAGE

There are three ways to use this module. You can use it directly in place of Module::Build, if you don't subclass it to add your own customizations. You can inherit from it if you do subclass Module::Build to add your own behavior. Finally, you can use it as a role with Class::Roles. The correct approach depends on your desire and what you do with it.

Module::Build::TestReporter only overrides the behavior of Module::Build's ACTION_test. If you don't touch this process, you'll probably be fine no matter what your code does.

However you use it, there are two additional arguments passed to its new() (in your Build.PL file) that must be present for the module to do its work:

• report_file => 'filename.txt'

  report_file is the name of the file to which to write the failure report.

• report_address => 'you@example.com'

  report_address is the e-mail address to which to send failure reports.

At the end of the test run, the module writes any failures to the file specified in report_file. If you've specified a report_address, it also prints a message to inform the users to e-mail that file to the appropriate address. The report contains information on all of the failed test files, all of the failing tests (including their diagnostics), and the characteristics of the Perl environment (as found by calling perl -V).

Hopefully this will improve your debugging.

DISTRIBUTION

As Stig Brautaset pointed out, there's a bit of a bootstrapping problem. How can you rely on users having this module available if you use it to mark dependencies? The easiest approach is to bundle this module with the code that uses it; I tend to store mine in a build_lib directory. Then modify @INC in your Build.PL file.

Note that you should mark the dependencies for this module in your Build.PL file as if they were build dependencies of your module. I recommend:

        build_requires =>
        {
                'IO::String'    =>     '',
                'IPC::Open3'    =>     '',
                'Class::Roles'  =>     '',
                'SUPER'         => '1.02',
                'Test::Simple'  => '0.48',
                'Test::Harness' => '2.47',
        }

This module does go through some hoops to mark dependencies if you forget, but be careful.

AUTHOR

chromatic, <chromatic at wgz dot org>

BUGS

No known bugs. The SUPER() calls in role mode may be a little weird, but I feel a little paranoid as I've not had much feedback on either module coming into play here.

I have heard rumors that IPC::Open3 both works and does not work on non-Unix platforms. I don't have access to these platforms to test, so I appreciate any advice and test results.

COPYRIGHT

Copyright (c) 2005, chromatic. Some rights reserved.

This module is free software; you can use, redistribute, and modify it under the same terms as Perl 5.8.