cpan/Module-Build/t/README.pod

   1 =head1 A GUIDE TO WRITING TESTS FOR MODULE::BUILD
   2
   3 This document provides tips on writing new tests for Module::Build.  Please
   4 note that many existing tests were written prior to these guidelines and
   5 have many different styles.  Please don't copy/paste old tests by rote without
   6 considering better ways to test. See C<sample.t> for a starter test file.
   7
   8 =head1 TEST FILE PREAMBLE
   9
  10 Every Module::Build test should begin with the same preamble to ensure that the
  11 test library is set properly and that the correct version of Module::Build is
  12 being tested.
  13
  14   use strict;
  15   use lib 't/lib';
  16   use MBTest tests => 2; # or 'no_plan'
  17
  18   blib_load('Module::Build');
  19
  20 The C<MBTest> module is in C<t/lib/> and subclasses Test::More.  When loaded
  21 it cleans up several environment variables that could cause problems,
  22 tweaks C<@INC> and exports several helper functions.  See that module for
  23 details.
  24
  25 =head1 CREATING A TEST DISTRIBUTION
  26
  27 The C<DistGen> module in C<t/lib/> should be used to create sample
  28 distributions for testing.  It provides numerous helpful methods to
  29 create a skeleton distribution, add files, change files, and so on.
  30 Run C<perldoc> on C<t/lib/DistGen.pm> to see the documentation.
  31
  32   # CREATE A TEST DISTRIBUTION
  33
  34   use DistGen;
  35
  36   # create dist object in a temp directory
  37   my $dist = DistGen->new;
  38
  39   # enter the test distribution directory before further testing
  40   $dist->chdir_in;
  41
  42   # generate the skeleton files
  43   $dist->regen;
  44
  45
  46 =head1 GETTING A MODULE::BUILD OBJECT
  47
  48 From inside the test distribution, you can get the Module::Build object
  49 configured in Build.PL using the C<new_from_context> method on the
  50 dist object.  This is just like Module::Build's C<new_from_context> except
  51 it passes C<< quiet => 1 >> to avoid sending output to the terminal.
  52 Use the Module::Build object to test the programmatic API.
  53
  54   my $mb = $dist->new_from_context( quiet => 1 );
  55   isa_ok( $mb, "Module::Build" );
  56   is( $mb->dist_name, "Simple", "dist_name is 'Simple'" );
  57
  58 =head1 TESTING THE COMMAND LINE API
  59
  60 The command line API is tested by running subprocesses, not via a Module::Build
  61 object.  The C<DistGen> object has helper methods for running C<Build.PL> and
  62 C<Build> and passing arguments on the command line.
  63
  64   $dist->run_build_pl( '--quiet' );
  65   $dist->run_build( 'test' );
  66
  67 =head1 TYPICAL TESTING CYCLE
  68
  69 The typical testing cycle is to generate or modify a test distribution, either
  70 through the C<DistGen> object or directly in the filesystem, then regenerate
  71 the distribution and test it (or run command line tests and observe the
  72 result.)
  73
  74   # Modify the distribution
  75
  76   $dist->change_build_pl(
  77     {
  78       module_name   => $dist->name,
  79       license       => 'artistic',
  80     }
  81   );
  82   $dist->regen;
  83
  84   # Get a new build object and test it
  85
  86   $mb = $dist->new_from_context;
  87   is( $mb->license, "artistic", "saw 'artistic' license" );
  88
  89
  90 =head1 COPYRIGHT
  91
  92 This documentation is Copyright (C) 2009 by David Golden.  You can redistribute
  93 it and/or modify it under the same terms as Perl 5.10.0.
  94