Module::Install::TestTarget(3pm)

1Module::Install::TestTaUrsgeert(C3o)ntributed Perl DocumMeondtualtei:o:nInstall::TestTarget(3)
2
3
4

NAME

6       Module::Install::TestTarget - Assembles Custom Test Targets For `make`
7

SYNOPSIS

9       inside Makefile.PL:
10
11         use inc::Module::Install;
12         tests 't/*t';
13
14         # override the default `make test`
15         default_test_target
16             includes           => ["$ENV{HOME}/perl5/lib"],
17             load_modules       => [qw/Foo Bar/],
18             run_on_prepare     => [qw/before.pl/],
19             run_on_finalize    => [qw/after.pl/],
20             insert_on_prepare  => ['print "start -> ", scalar localtime, "\n"'],
21             insert_on_finalize => ['print "end   -> ", scalar localtime, "\n"'],
22             tests              => ['t/baz/*t'],
23             env                => { PERL_ONLY => 1 },
24         ;
25
26         # create a new test target (allows `make foo`)
27         test_target foo => (
28             includes           => ["$ENV{HOME}/perl5/lib"],
29             load_modules       => [qw/Foo Bar/],
30             run_on_prepare     => [qw/before.pl/],
31             run_on_finalize    => [qw/after.pl/],
32             insert_on_prepare  => ['print "start -> ", scalar localtime, "\n"'],
33             insert_on_finalize => ['print "end   -> ", scalar localtime, "\n"'],
34             tests              => ['t/baz/*t'],
35             env                => { PERL_ONLY => 1 },
36             alias              => 'testall', # make testall is run the make foo
37         );
38
39         # above target 'foo' will turn into something like:
40         perl "-MExtUtils::Command::MM" "-I/home/xaicron/perl5/lib" "-MFoo" "-MBar" "-e" "do { local \$@; do 'before.pl'; die \$@ if $@ }; sub { print \"start -> \", scalar localtime, \"\n\" }->(); test_harness(0, 'inc'); do { local \$@; do 'after.pl'; die \$@ if \$@ }; sub { print \"end -> \", scalar localtime, \"\n\" }->();" t/baz/*t
41

DESCRIPTION

43       Module::Install::TestTarget creates "make test" variations with code
44       snippets.  This helps module developers to test their distributions
45       with various conditions.
46

EXAMPLES

48   TEST A MODULE WITH XS/PP BACKENDS
49       Suppose your XS module can load a PurePerl backend by setting the
50       PERL_ONLY environment variable. You can force your tests to use this
51       environment flag using this construct:
52
53           test_target test_pp => (
54               env => { PERL_ONLY => 1 },
55           );
56
57   TEST AN APP USING DATABASES
58       Suppose you want to instantiate a mysqld instance using Test::mysqld,
59       but you don't want to start/stop mysqld for every test script. You can
60       start mysqld once using this module.
61
62       First create a script like this:
63
64           # t/start_mysqld.pl
65           use Test::mysqld;
66           my $mysqld = Test::mysqld->new( ... );
67
68       Then in your Makefile.PL, simply specify that you want to run this
69       script before executing any tests.
70
71           test_target test_db => (
72               run_on_prepare => [ 't/start_mysqld.pl' ]
73           );
74
75       Since the script is going to be executed in global scope, $mysqld will
76       stay active during the execution of your tests -- the mysqld instance
77       that came up will shutdown automatically after the tests are executed.
78
79       You can use this trick to run other daemons, such as memcached (maybe
80       via Test::Memcached)
81

FUNCTIONS

83   test_target($target, %args)
84       Defines a new test target with %args.
85
86       %args are:
87
88       "includes => \@include_paths"
89           Sets include paths.
90
91             test_target foo => (
92                 includes => ['/path/to/inc'],
93             );
94
95             # `make foo` will be something like this:
96             perl -I/path/to/inc  -MExtUtils::Command::MM -e "test_harness(0, 'inc')" t/*t
97
98       "load_modules => \@module_names"
99           Sets modules which are loaded before running test_harness().
100
101             test_target foo => (
102                 load_modules => ['Foo', 'Bar::Baz'],
103             );
104
105             # `make test` will be something like this:
106             perl -MFoo -MBar::Baz -MExtUtils::Command::MM -e "test_harness(0, 'inc')" t/*t
107
108       "run_on_prepare => \@scripts"
109           Sets scripts to run before running test_harness().
110
111             test_target foo => (
112                 run_on_prepare => ['tool/run_on_prepare.pl'],
113             );
114
115             # `make foo` will be something like this:
116             perl -MExtUtils::Command::MM -e "do { local \$@; do 'tool/run_on_prepare.pl; die \$@ if \$@ }; test_harness(0, 'inc')" t/*t
117
118       "run_on_finalize => \@scripts"
119           Sets scripts to run after running test_harness().
120
121             use inc::Module::Install;
122             tests 't/*t';
123             test_target foo => (
124                 run_on_finalize => ['tool/run_on_after.pl'],
125             );
126
127             # `make foo` will be something like this:
128             perl -MExtUtils::Command::MM -e "test_harness(0, 'inc'); do { local \$@; do 'tool/run_on_after.pl; die \$@ if \$@ };" t/*t
129
130       "insert_on_prepare => \@codes"
131           Sets perl codes to run before running test_harness().
132
133             use inc::Module::Install;
134             tests 't/*t';
135             test_target foo => (
136                 insert_on_prepare => ['print scalar localtime , "\n"', sub { system qw/cat README/ }],
137             );
138
139             # `make foo` will be something like this:
140             perl -MExtUtils::Command::MM "sub { print scalar localtme, "\n" }->(); sub { system 'cat', 'README' }->(); test_harness(0, 'inc')" t/*t
141
142           The perl codes runs run_on_prepare runs later.
143
144       "insert_on_finalize => \@codes"
145           Sets perl codes to run after running test_harness().
146
147             use inc::Module::Install;
148             tests 't/*t';
149             test_target foo => (
150                 insert_on_finalize => ['print scalar localtime , "\n"', sub { system qw/cat README/ }],
151             );
152
153             # `make foo` will be something like this:
154             perl -MExtUtils::Command::MM "test_harness(0, 'inc'); sub { print scalar localtme, "\n" }->(); sub { system 'cat', 'README' }->();" t/*t
155
156           The perl codes runs run_on_finalize runs later.
157
158       "alias => $name"
159           Sets an alias of the test.
160
161             test_target test_pp => (
162                 run_on_prepare => 'tool/force-pp.pl',
163                 alias          => 'testall',
164             );
165
166             # `make test_pp` and `make testall` will be something like this:
167             perl -MExtUtils::Command::MM -e "do { local \$@; do 'tool/force-pp.pl'; die \$@; if \$@ }; test_harness(0, 'inc')" t/*t
168
169       "alias_for_author => $name"
170           The same as "alias", but only enabled if it is in author's
171           environment.
172
173       "env => \%env"
174           Sets environment variables.
175
176             test_target foo => (
177                 env => {
178                     FOO => 'bar',
179                 },
180             );
181
182             # `make foo` will be something like this:
183             perl -MExtUtils::Command::MM -e "\$ENV{q{FOO}} = q{bar}; test_harness(0, 'inc')" t/*t
184
185       "tests => \@test_files"
186           Sets test files to run.
187
188             test_target foo => (
189                 tests  => ['t/foo.t', 't/bar.t'],
190                 env    => { USE_FOO => 1 },
191             );
192
193             # `make foo` will be something like this:
194             perl -MExtUtils::Command::MM -e "$ENV{USE_FOO} = 1 test_harness(0, 'inc')" t/foo.t t/bar.t
195
196   default_test_target(%args)
197       Override the default `make test` with %args.
198
199       Same argument as test_target(), but `target` and `alias` are not
200       allowed.
201

AUTHOR

203       Yuji Shimada <xaicron {at} cpan.org>
204
205       Goro Fuji (gfx) <gfuji at cpan.org>
206
207       Maki Daisuke (lestrrat)
208

LICENSE

213       This library is free software; you can redistribute it and/or modify it
214       under the same terms as Perl itself.
215
216
217
218perl v5.38.0                      2023-07-20    Module::Install::TestTarget(3)