=head1 A GUIDE TO WRITING TESTS FOR MODULE::BUILD

This document provides tips on writing new tests for Module::Build.  Please
note that many existing tests were written prior to these guidelines and
have many different styles.  Please don't copy/paste old tests by rote without
considering better ways to test. See C<sample.t> for a starter test file.

=head1 TEST FILE PREAMBLE

Every Module::Build test should begin with the same preamble to ensure
that the test library is set properly if tested as part of the Perl core
and that the correct version of Module::Build is being tested.

  use strict;
  use lib $ENV{PERL_CORE} ? '../lib/Module/Build/t/lib' : 't/lib';
  use MBTest tests => 2; # or 'no_plan'

  blib_load('Module::Build');

The C<MBTest> module is in C<t/lib/> and subclasses Test::More.  When loaded
it cleans up several environment variables that could cause problems,
tweaks C<@INC> and exports several helper functions.  See that module for
details.

=head1 CREATING A TEST DISTRIBUTION

The C<DistGen> module in C<t/lib/> should be used to create sample
distributions for testing.  It provides numerous helpful methods to
create a skeleton distribution, add files, change files, and so on.
Run C<perldoc> on C<t/lib/DistGen.pm> to see the documentation.

  # CREATE A TEST DISTRIBUTION

  use DistGen;

  # create dist object in a temp directory
  my $dist = DistGen->new;

  # enter the test distribution directory before further testing
  $dist->chdir_in;

  # generate the skeleton files
  $dist->regen;


=head1 GETTING A MODULE::BUILD OBJECT

From inside the test distribution, you can get the Module::Build object
configured in Build.PL using the C<new_from_context> method on the
dist object.  This is just like Module::Build's C<new_from_context> except
it passes C<< quiet => 1 >> to avoid sending output to the terminal.
Use the Module::Build object to test the programmatic API.

  my $mb = $dist->new_from_context( quiet => 1 );
  isa_ok( $mb, "Module::Build" );
  is( $mb->dist_name, "Simple", "dist_name is 'Simple'" );

=head1 TESTING THE COMMAND LINE API

The command line API is tested by running subprocesses, not via a Module::Build
object.  The C<DistGen> object has helper methods for running C<Build.PL> and
C<Build> and passing arguments on the command line.

  $dist->run_build_pl( '--quiet' );
  $dist->run_build( 'test' );

=head1 TYPICAL TESTING CYCLE

The typical testing cycle is to generate or modify a test distribution, either
through the C<DistGen> object or directly in the filesystem, then regenerate
the distribution and test it (or run command line tests and observe the
result.)

  # Modify the distribution

  $dist->change_build_pl(
    {
      module_name   => $dist->name,
      license       => 'artistic',
    }
  );
  $dist->regen;

  # Get a new build object and test it

  $mb = $dist->new_from_context;
  is( $mb->license, "artistic", "saw 'artistic' license" );


=head1 COPYRIGHT

This documentation is Copyright (C) 2009 by David Golden.  You can redistribute
it and/or modify it under the same terms as Perl 5.10.0.

