NAME

       Test::Manifest - interact with a t/test_manifest file

SYNOPSIS

               # in Makefile.PL
               eval "use Test::Manifest 2.00";

               # in Build.PL
               my $class = do {
                       if( eval "Test::Manifest 2.00" ) {
                               Test::Manifest->get_module_build_subclass;
                               }
                       else {
                               'Module::Build';
                               }
                       };

               my $build = $class->new( ... )

               # in the file t/test_manifest, list the tests you want
               # to run in the order you want to run them

DESCRIPTION

       "Test::Harness" assumes that you want to run all of the .t files in the t/ directory in
       ASCII-betical order during "make test" or "./Build test" unless you say otherwise.  This
       leads to some interesting naming schemes for test files to get them in the desired order.
       These interesting names ossify when they get into source control, and get even more
       interesting as more tests show up.

       "Test::Manifest" overrides the default test file order. Instead of running all of the
       t/*.t files in ASCII-betical order, it looks in the t/test_manifest file to find out which
       tests you want to run and the order in which you want to run them.  It constructs the
       right value for the build system to do the right thing.

       In t/test_manifest, simply list the tests that you want to run.  Their order in the file
       is the order in which they run.  You can comment lines with a "#", just like in Perl, and
       "Test::Manifest" will strip leading and trailing whitespace from each line.  It also
       checks that the specified file is actually in the t/ directory.  If the file does not
       exist, it does not put its name in the list of test files to run and it will issue a
       warning.

       Optionally, you can add a number after the test name in test_manifest to define sets of
       tests. See "get_t_files" for more information.

   ExtUtils::Makemaker
       To override the test order behaviour in "Makemaker", "Test::Manifest" inserts itself in
       the "test_via_harness" step by providing its own test runner. In "Makefile.PL", all you
       have to do is load "Test::Manifest" before you call "WriteMakefile". To make it optional,
       load it in an eval:

               eval "use Test::Manifest";

   Module::Build
       Overiding parts of "Module::Build" is tricker if you want to use the subclassing mechanism
       and still make "Test::Manifest" optional. If you can load "Test::Manifest" (version 2.00
       or later), "Test::Manifest" can create the subclass for you.

               my $class = do {
                       if( eval 'Test::Manifest 2.00; 1' ) {
                               Test::Manifest->get_module_build_subclass;
                               }
                       else {
                               'Module::Build' # if Test::Manifest isn't there
                               }
                       };

               $class->new( ... );
               $class->create_build_file;

       This is a bit of a problem when you already have your own subclass.  "Test::Manifest"
       overrides "find_test_files", so you can get just that code to add to your own subclass
       code string:

               my $code = eval 'Test::Manifest 2.00; 1'
                               ?
                       Test::Manifest->get_module_build_code_string
                               :
                       '';

               my $class = Module::Build->subclass(
                       ...,
                       code => "$code\n...your subclass code string...",
                       );

   Class methods
       get_module_build_subclass
           For "Module::Build" only.

           Returns a "Module::Build" subclass that overrides "find_test_files". If you want to
           have your own "Module::Build" subclass and still use "Test::Manifest", you can get
           just the code string with "get_module_build_code_string".

       get_module_build_code_string
           For "Module::Build" only.

           Returns the overridden "find_test_files" as Perl code in a string suitable for the
           "code" key in "Module::Build-"subclass()>. You can add this to other bits you are
           overriding or extending.

           See "Module::Build::Base::find_test_files" to see the base implementation.

   Functions
       run_t_manifest( TEST_VERBOSE, INST_LIB, INST_ARCHLIB, TEST_LEVEL )
           For "Makemaker" only. You don't have to mess with this at the user level.

           Run all of the files in t/test_manifest through "Test::Harness:runtests" in the order
           they appear in the file. This is inserted automatically

                   eval "use Test::Manifest";

       get_t_files( [LEVEL] )
           In scalar context it returns a single string that you can use directly in
           "WriteMakefile()". In list context it returns a list of the files it found in
           t/test_manifest.

           If a t/test_manifest file does not exist, "get_t_files()" returns nothing.

           "get_t_files()" warns you if it can't find t/test_manifest, or if entries start with
           t/. It skips blank lines, and strips Perl style comments from the file.

           Each line in t/test_manifest can have three parts: the test name, the test level (a
           floating point number), and a comment. By default, the test level is 1.

                   test_name.t 2  #Run this only for level 2 testing

           Without an argument, "get_t_files()" returns all the test files it finds. With an
           argument that is true (so you can't use 0 as a level) and is a number, it skips tests
           with a level greater than that argument. You can then define sets of tests and choose
           a set to run. For instance, you might create a set for end users, but also add on a
           set for deeper testing for developers.

           Experimentally, you can include a command to grab test names from another file. The
           command starts with a ";" to distinguish it from a true filename. The filename
           (currently) is relative to the current working directory, unlike the filenames, which
           are relative to "t/". The filenames in the included are still relative to "t/".

                   ;include t/file_with_other_test_names.txt

           Also experimentally, you can stop "Test::Manifest" from reading filenames with the
           ";skip" directive. "Test::Manifest" will skip the filenames up to the ";unskip"
           directive (or end of file):

                   run_this1
                   ;skip
                   skip_this
                   ;unskip
                   run_this2

           To select sets of tests, specify the level in the environment variable "TEST_LEVEL":

                   make test # run all tests no matter the level
                   make test TEST_LEVEL=2  # run all tests level 2 and below

           Eventually this will end up as an option to Build.PL:

                   ./Build test --testlevel=2  # Not yet supported

       make_test_manifest()
           Creates the test_manifest file in the t directory by reading the contents of the t/
           directory.

           TO DO: specify tests in argument lists.

           TO DO: specify files to skip.

       manifest_name()
           Returns the name of the test manifest file, relative to t/.

SOURCE AVAILABILITY

       This source is in Github:

               http://github.com/briandfoy/test-manifest/

CREDITS

       Matt Vanderpol suggested and supplied a patch for the ";include" feature.

AUTHOR

       brian d foy, "<bdfoy@cpan.org>"

COPYRIGHT AND LICENSE

       Copyright (c) 2002-2014 brian d foy. All rights reserved.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.