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.