Bundling Tests with Modules | Perl Testing: A Developers Notebook

When releasing modules, you should always include a test suite so that the people installing your code can have confidence that it works on their systems. Tools such as the CPAN shell will refuse to install a distribution if any of its tests fail, unless the user forces a manual installation. If you upload the module to the CPAN, a group of dedicated individuals will report the results of running your test suite on myriad platforms. The CPAN Testers site at http://testers.cpan.org/ reports their results.

This lab explains how to set up a basic distribution, including the directory structure and minimal test suite.

How do I do that?

Module distributions are archives that, when extracted, produce a standard directory tree. Every distribution should contain at least a lib/ directory for the reusable module files, a Build.PL or Makefile.PL to aid in testing and installing the code, and a t/ directory that contains the tests for the module and any additional data needed for testing.

If you haven't already created a directory structure for the distribution, the simplest way to start is by using the module-starter command from the Module::Starter distribution. module-starter creates the directories you need and even includes sample tests for your module.

Go ahead and install Module::Starter . Once installed, you should also have the module-starter program in your path . Create a fictitious distribution for calculating taxes that includes two modules, Taxes::Autocomplete and Taxes::Loophole :

Note: Perl's documentation suggests using h2xs to create new modules. Module::Starter is just a modern alternative .

 $  module-starter --mb --distro=Taxes \         --module=Taxes::Autocomplete,Taxes::Loophole         --author='John Q. Taxpayer' \         --email='john@bigpockets.com' --verbose  Created Taxes     Created Taxes/lib/Taxes     Created Taxes/lib/Taxes/Autocomplete.pm     Created Taxes/lib/Taxes/Loophole.pm     Created Taxes/t     Created Taxes/t/pod-coverage.t     Created Taxes/t/pod.t     Created Taxes/t/00-load.t     Created Taxes/Build.PL     Created Taxes/MANIFEST     Created starter directories and files

module-starter creates a complete distribution in the directory Taxes/ . Further inspection of the Taxes/t/ directory reveals three test files:

 $  ls -1 Taxes/t/  00-load.t     pod-coverage.t     pod.t

Any test files you add to Taxes/t/ will run during the testing part of the module installation.

What just happened ?

The module-starter command creates a skeleton directory structure for new modules. This structure includes the three test files in the previous output. These files perform basic tests to make sure your module maintains a certain level of quality (or "kwalitee" ”see Validating Kwalitee ," later in this chapter).

t/pod-coverage.t and t/pod.t test POD documentation validity and coverage, respectively. t/00-load.t contains the "basic usage" test, which may be the most common type of test within different Perl module distributions. This test simply checks whether the modules in the distribution load properly. Note that module-starter has lovingly filled in all of the module names for you:

 use Test::More tests => 2;     BEGIN     {         use_ok( 'Taxes::Autocomplete' );         use_ok( 'Taxes::Loophole' );     }     diag( "Testing Taxes::Autocomplete $Taxes::Autocomplete::VERSION,            Perl 5.008004, /usr/bin/perl" );

You might see the same sort of tests in a test file with a different name , such as 00_basic.t or just load.t , or it may be one of several tests in another file.

What about?

I have 8,000 test files in my t/ directory! Can I use subdirectories to organize them better?

Sure thing. If you use Module::Build , specify a test_files key whose value is a space-delimited string containing just the patterns of test files. Module::Build automatically expands the patterns.

 use Module::Build;     my $build = Module::Build->new(         ...           test_files => 't/*.t t/*/*.t',         ...     );     $builder->create_build_script(  );

Alternatively, set the recursive_test_files flag to use every .t file found within the t/ directory and all of its subdirectories:

 use Module::Build;     my $build = Module::Build->new(         ...  recursive_test_files => 1,  ...     );     $builder->create_build_script(  );

If you use ExtUtils::MakeMaker and Makefile.PL instead, do the equivalent by providing a test key to the hash given to WriteMakefile( ) :

 use ExtUtils::MakeMaker;     WriteMakeFile(         ...         test => { TESTS => join ' ', map { glob } qw( t/*.t t/*/*.t ) },         ...     );

The value of the test hash pair must be a hash reference with the key TESTS . The value is a space-delimited string of all test files to run. In the previous example, join and glob create such a a string based on the two patterns t/*.t and t/*/*.t . This is necessary because WriteMakeFile( ) will not automatically expand the patterns when used with ActiveState Perl on Windows.