1Test::Manifest(3) User Contributed Perl Documentation Test::Manifest(3)
2
6 Test::Manifest - interact with a t/test_manifest file
7
9 # in Makefile.PL
10 eval "use Test::Manifest 2.00";
11 # in Build.PL
13 my $class = do {
14 if( eval 'use Test::Manifest 2.00; 1' ) {
15 Test::Manifest->get_module_build_subclass;
16 }
17 else {
18 'Module::Build';
19 }
20 };
21 my $build = $class->new( ... )
23 # in the file t/test_manifest, list the tests you want
25 # to run in the order you want to run them
26
28 "Test::Harness" assumes that you want to run all of the .t files in the
29 t/ directory in ASCII-betical order during "make test" or "./Build
30 test" unless you say otherwise. This leads to some interesting naming
31 schemes for test files to get them in the desired order. These
32 interesting names ossify when they get into source control, and get
33 even more interesting as more tests show up.
34 "Test::Manifest" overrides the default test file order. Instead of
36 running all of the t/*.t files in ASCII-betical order, it looks in the
37 t/test_manifest file to find out which tests you want to run and the
38 order in which you want to run them. It constructs the right value for
39 the build system to do the right thing.
40 In t/test_manifest, simply list the tests that you want to run. Their
42 order in the file is the order in which they run. You can comment
43 lines with a "#", just like in Perl, and "Test::Manifest" will strip
44 leading and trailing whitespace from each line. It also checks that
45 the specified file is actually in the t/ directory. If the file does
46 not exist, it does not put its name in the list of test files to run
47 and it will issue a warning.
48 Optionally, you can add a number after the test name in test_manifest
50 to define sets of tests. See "get_t_files" for more information.
51 ExtUtils::MakeMaker
53 To override the test order behaviour in "MakeMaker", "Test::Manifest"
54 inserts itself in the "test_via_harness" step by providing its own test
55 runner. In "Makefile.PL", all you have to do is load "Test::Manifest"
56 before you call "WriteMakefile". To make it optional, load it in an
57 eval:
58 eval "use Test::Manifest";
60 Module::Build
62 Overiding parts of "Module::Build" is tricker if you want to use the
63 subclassing mechanism and still make "Test::Manifest" optional. If you
64 can load "Test::Manifest" (version 2.00 or later), "Test::Manifest" can
65 create the subclass for you.
66 my $class = do {
68 if( eval 'use Test::Manifest 2.00; 1' ) {
69 Test::Manifest->get_module_build_subclass;
70 }
71 else {
72 'Module::Build' # if Test::Manifest isn't there
73 }
74 };
75 $class->new( ... );
77 $class->create_build_file;
78 This is a bit of a problem when you already have your own subclass.
80 "Test::Manifest" overrides "find_test_files", so you can get just that
81 code to add to your own subclass code string:
82 my $code = eval 'use Test::Manifest 2.00; 1'
84 ?
85 Test::Manifest->get_module_build_code_string
86 :
87 '';
88 my $class = Module::Build->subclass(
90 ...,
91 code => "$code\n...your subclass code string...",
92 );
93 Class methods
95 get_module_build_subclass
96 For "Module::Build" only.
97 Returns a "Module::Build" subclass that overrides
99 "find_test_files". If you want to have your own "Module::Build"
100 subclass and still use "Test::Manifest", you can get just the code
101 string with "get_module_build_code_string".
102 get_module_build_code_string
104 For "Module::Build" only.
105 Returns the overridden "find_test_files" as Perl code in a string
107 suitable for the "code" key in "Module::Build-"subclass()>. You can
108 add this to other bits you are overriding or extending.
109 See "Module::Build::Base::find_test_files" to see the base
111 implementation.
112 Functions
114 run_t_manifest( TEST_VERBOSE, INST_LIB, INST_ARCHLIB, TEST_LEVEL )
115 For "MakeMaker" only. You don't have to mess with this at the user
116 level.
117 Run all of the files in t/test_manifest through
119 "Test::Harness:runtests" in the order they appear in the file. This
120 is inserted automatically
121 eval "use Test::Manifest";
123 get_t_files( [LEVEL] )
125 In scalar context it returns a single string that you can use
126 directly in WriteMakefile(). In list context it returns a list of
127 the files it found in t/test_manifest.
128 If a t/test_manifest file does not exist, get_t_files() returns
130 nothing.
131 get_t_files() warns you if it can't find t/test_manifest, or if
133 entries start with t/. It skips blank lines, and strips Perl style
134 comments from the file.
135 Each line in t/test_manifest can have three parts: the test name,
137 the test level (a floating point number), and a comment. By
138 default, the test level is 1.
139 test_name.t 2 #Run this only for level 2 testing
141 Without an argument, get_t_files() returns all the test files it
143 finds. With an argument that is true (so you can't use 0 as a
144 level) and is a number, it skips tests with a level greater than
145 that argument. You can then define sets of tests and choose a set
146 to run. For instance, you might create a set for end users, but
147 also add on a set for deeper testing for developers.
148 Experimentally, you can include a command to grab test names from
150 another file. The command starts with a ";" to distinguish it from
151 a true filename. The filename (currently) is relative to the
152 current working directory, unlike the filenames, which are relative
153 to "t/". The filenames in the included are still relative to "t/".
154 ;include t/file_with_other_test_names.txt
156 Also experimentally, you can stop "Test::Manifest" from reading
158 filenames with the ";skip" directive. "Test::Manifest" will skip
159 the filenames up to the ";unskip" directive (or end of file):
160 run_this1
162 ;skip
163 skip_this
164 ;unskip
165 run_this2
166 To select sets of tests, specify the level in the environment
168 variable "TEST_LEVEL":
169 make test # run all tests no matter the level
171 make test TEST_LEVEL=2 # run all tests level 2 and below
172 Eventually this will end up as an option to Build.PL:
174 ./Build test --testlevel=2 # Not yet supported
176 make_test_manifest()
178 Creates the test_manifest file in the t directory by reading the
179 contents of the t/ directory.
180 TO DO: specify tests in argument lists.
182 TO DO: specify files to skip.
184 manifest_name()
186 Returns the name of the test manifest file, relative to t/.
187
189 This source is in Github:
190 http://github.com/briandfoy/test-manifest/
192
194 Matt Vanderpol suggested and supplied a patch for the ";include"
195 feature.
196 Olivier Mengué supplied a documentation patch.
198
200 brian d foy, "<bdfoy@cpan.org>"
201
203 Copyright © 2002-2022, brian d foy <bdfoy@cpan.org>. All rights
204 reserved.
205 This program is free software; you can redistribute it and/or modify it
207 under the terms of the Artistic License 2.0.
208perl v5.36.0 2023-01-20 Test::Manifest(3)