1Test::Manifest(3)     User Contributed Perl Documentation    Test::Manifest(3)
2
3
4

NAME

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

SYNOPSIS

9               # in Makefile.PL
10               eval "use Test::Manifest 2.00";
11
12               # 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
22               my $build = $class->new( ... )
23
24               # in the file t/test_manifest, list the tests you want
25               # to run in the order you want to run them
26

DESCRIPTION

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
35       "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
41       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
49       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
52   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
59               eval "use Test::Manifest";
60
61   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
67               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
76               $class->new( ... );
77               $class->create_build_file;
78
79       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
83               my $code = eval 'use Test::Manifest 2.00; 1'
84                               ?
85                       Test::Manifest->get_module_build_code_string
86                               :
87                       '';
88
89               my $class = Module::Build->subclass(
90                       ...,
91                       code => "$code\n...your subclass code string...",
92                       );
93
94   Class methods
95       get_module_build_subclass
96           For "Module::Build" only.
97
98           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
103       get_module_build_code_string
104           For "Module::Build" only.
105
106           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
110           See "Module::Build::Base::find_test_files" to see the base
111           implementation.
112
113   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
118           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
122                   eval "use Test::Manifest";
123
124       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
129           If a t/test_manifest file does not exist, "get_t_files()" returns
130           nothing.
131
132           "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
136           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
140                   test_name.t 2  #Run this only for level 2 testing
141
142           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
149           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
155                   ;include t/file_with_other_test_names.txt
156
157           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
161                   run_this1
162                   ;skip
163                   skip_this
164                   ;unskip
165                   run_this2
166
167           To select sets of tests, specify the level in the environment
168           variable "TEST_LEVEL":
169
170                   make test # run all tests no matter the level
171                   make test TEST_LEVEL=2  # run all tests level 2 and below
172
173           Eventually this will end up as an option to Build.PL:
174
175                   ./Build test --testlevel=2  # Not yet supported
176
177       make_test_manifest()
178           Creates the test_manifest file in the t directory by reading the
179           contents of the t/ directory.
180
181           TO DO: specify tests in argument lists.
182
183           TO DO: specify files to skip.
184
185       manifest_name()
186           Returns the name of the test manifest file, relative to t/.
187

SOURCE AVAILABILITY

189       This source is in Github:
190
191               http://github.com/briandfoy/test-manifest/
192

CREDITS

194       Matt Vanderpol suggested and supplied a patch for the ";include"
195       feature.
196
197       Olivier Mengué supplied a documentation patch.
198

AUTHOR

200       brian d foy, "<bdfoy@cpan.org>"
201
203       Copyright © 2002-2021, brian d foy <bdfoy@cpan.org>. All rights
204       reserved.
205
206       This program is free software; you can redistribute it and/or modify it
207       under the terms of the Artistic License 2.0.
208
209
210
211perl v5.32.1                      2021-01-27                 Test::Manifest(3)
Impressum