| Distributing your tests with your code is a good diagnostic practice that can help you to ensure that your code works when your users try to run it. At least it's good for diagnostics when you can convince your users to send you the appropriate test output. Rather than walk them through the steps of running the tests, redirecting their output to files, and sending you the results, consider automating the process of gathering failed test output and useful information. As usual, the CPAN has the solution in the form of Module::Build::TestReporter . How do I do that? Consider a Chef module that can slice, dice, fricassee, and boil ingredients . Create a new directory for it, with lib/ and t/ subdirectories. Save the following code as lib/Chef.pm : package Chef; use base 'Exporter'; use strict; use warnings; our $VERSION = '1.0'; our @EXPORT = qw( slice dice fricassee ); sub slice { my $ingredient = shift; print "Slicing $ingredient...\n"; } sub dice { my $ingredient = shift; print "Dicing $ingredient...\n"; } sub fricassee { my $ingredient = shift; print "Fricasseeing $ingredient...\n"; } sub boil { my $ingredient = shift; print "Boiling $ingredient...\n"; } 1;
Note: Yes, the missing export of boil ( ) is intentional .
Save a basic, "does it compile?" test file as t/use.t : #!perl use strict; use warnings; use Test::More tests => 1; my $module = 'Chef'; use_ok( $module ) or exit;
Save the following test of its exports as t/chef_exports.t : #!perl use strict; use warnings; use Test::More tests => 5; my $module = 'Chef'; use_ok( $module ) or exit; for my $export (qw( slice dice fricassee boil )) { can_ok( _ _PACKAGE_ _, $export ); }
Finally, save the following build file as Build.PL : use Module::Build::TestReporter; my $build = Module::Build::TestReporter->new( module_name => 'Chef', license => 'perl', report_file => 'chef_failures.txt', report_address => 'chef-failures@example.com', dist_version_from => 'lib/Chef.pm', ); $build->create_build_script( );
Now build the module as normal and run the tests: $ perl Build.PL Creating new 'Build' script for 'Chef' version '1.0' $ perl Build lib/Chef.pm -> blib/lib/Chef.pm $ perl Build test t/use.t...ok Tests failed! Please e-mail 'chef_failures.txt' to chef-failures@example.com.
What just happened ? Hang on, that's a lot different from normal. What's chef_failures.txt ? Open it with a text editor; it contains output from the failed tests as well as information about the currently running Perl binary: Test failures in 't/chef.t' (1/5): 5: - main->can('boil') Failed test (t/chef.t at line 13) main->can('boil') failed Summary of my perl5 (revision 5 version 8 subversion 6) configuration: <...>
Module::Build::TestReporter diverts the output of the test run and reports any failures to the file specified in Build.PL 's report_file parameter. It also prints a message about the failures and gives the address to which to send the results. What happens if the tests all succeed? Open lib/Chef.pm and change the export line: @EXPORT = qw( slice dice fricassee boil );
Then run the tests again: $ perl Build test All tests passed.
You're happy, the users are happy, and there's nothing left to do. This lowers the barrier for users to report test failures. You don't have to walk them through running the tests in verbose mode, trying to capture the output. All they have to do is to email you the report file.
Note: You can't guarantee that they will contact you, but you can make it easier .
What about... | Q: | What if I already have a Module::Build subclass? | | A: | Make your subclass inherit from Module::Build::TestReporter instead. See the module's documentation for other ideas, too! | | Q: | Can I have Module::Build::TestReporter email me directly? How about if it posted the results to a web page? That would make it even easier to retrieve failure reports from users. | | A: | It would, but can you guarantee that everyone running your tests has a working Internet connection or an SMTP server configured for Perl to use? If so, feel free to subclass Module::Build::TestReporter to report directly to you. | | Q: | My output looks different. Why? | | A: | This lab covered an early version of the module. It may change its messages slightly. The basic functions will remain the same, though. As with all of the other testing modules, see the documentation for current information. | | 