1package App::Yath::Options::Runner;
2use strict;
3use warnings;
4
5our $VERSION = '1.000082';
6
7use Test2::Util qw/IS_WIN32/;
8use Test2::Harness::Util qw/clean_path/;
9use File::Spec;
10
11use App::Yath::Options;
12
13my $DEFAULT_COVER_ARGS = '-silent,1,+ignore,^t/,+ignore,^t2/,+ignore,^xt,+ignore,^test.pl';
14
15option_group {prefix => 'runner', category => "Runner Options"} => sub {
16    option use_fork => (
17        alt         => ['fork'],
18        description => "(default: on, except on windows) Normally tests are run by forking, which allows for features like preloading. This will turn off the behavior globally (which is not compatible with preloading). This is slower, it is better to tag misbehaving tests with the '# HARNESS-NO-PRELOAD' comment in their header to disable forking only for those tests.",
19        env_vars => [qw/!T2_NO_FORK T2_HARNESS_FORK !T2_HARNESS_NO_FORK YATH_FORK !YATH_NO_FORK/],
20        default     => sub {
21            return 0 if IS_WIN32;
22            return 1;
23        },
24    );
25
26    option abort_on_bail => (
27        type => 'b',
28        default => 1,
29        description => "Abort all testing if a bail-out is encountered (default: on)",
30    );
31
32    option use_timeout => (
33        alt         => ['timeout'],
34        description => "(default: on) Enable/disable timeouts",
35        default     => 1,
36    );
37
38    option job_count => (
39        type           => 's',
40        short          => 'j',
41        alt            => ['jobs'],
42        description    => 'Set the number of concurrent jobs to run (Default: 1)',
43        env_vars       => [qw/YATH_JOB_COUNT T2_HARNESS_JOB_COUNT HARNESS_JOB_COUNT/],
44        clear_env_vars => 1,
45        default        => 1,
46    );
47
48    option dump_depmap => (
49        type => 'b',
50        description => "When using staged preload, dump the depmap for each stage as json files",
51        default => 0,
52    );
53
54    option includes => (
55        name        => 'include',
56        short       => 'I',
57        type        => 'm',
58        description => "Add a directory to your include paths",
59    );
60
61    option resources => (
62        name => 'resource',
63        short => 'R',
64        type => 'm',
65        description => "Use a resource module to assign resource assignments to individual tests",
66        long_examples  => [' Port', ' +Test2::Harness::Runner::Resource::Port'],
67        short_examples => [' Port'],
68
69        normalize => sub {
70            my $val = shift;
71
72            $val = "Test2::Harness::Runner::Resource::$val"
73            unless $val =~ s/^\+//;
74
75            return $val;
76        },
77    );
78
79    option tlib => (
80        description => "(Default: off) Include 't/lib' in your module path",
81        default     => 0,
82        action => sub {
83            my ($prefix, $field, $raw, $norm, $slot, $settings, $handler) = @_;
84            push @{$settings->runner->includes} => File::Spec->catdir('t', 'lib');
85        },
86    );
87
88    option lib => (
89        short => 'l',
90        description => "(Default: include if it exists) Include 'lib' in your module path",
91        default     => 1,
92        action => sub {
93            my ($prefix, $field, $raw, $norm, $slot, $settings, $handler) = @_;
94            push @{$settings->runner->includes} => 'lib';
95            $settings->runner->lib(0);
96            $settings->runner->blib(0);
97        },
98    );
99
100    option blib => (
101        short => 'b',
102        description => "(Default: include if it exists) Include 'blib/lib' and 'blib/arch' in your module path",
103        default     => 1,
104        action => sub {
105            my ($prefix, $field, $raw, $norm, $slot, $settings, $handler) = @_;
106
107            push @{$settings->runner->includes} => (
108                File::Spec->catdir('blib', 'lib'),
109                File::Spec->catdir('blib', 'arch'),
110            );
111
112            $settings->runner->lib(0);
113            $settings->runner->blib(0);
114        },
115    );
116
117    option unsafe_inc => (
118        description => "perl is removing '.' from \@INC as a security concern. This option keeps things from breaking for now.",
119        env_vars    => [qw/PERL_USE_UNSAFE_INC/],
120        default     => 0,
121    );
122
123    option preloads => (
124        type        => 'm',
125        alt         => ['preload'],
126        short       => 'P',
127        description => 'Preload a module before running tests',
128    );
129
130    option preload_threshold => (
131        short => 'W',
132        alt => ['Pt'],
133        type => 's',
134        default => 0,
135        description => "Only do preload if at least N tests are going to be run. In some cases a full preload takes longer than simply running the tests, this lets you specify a minimum number of test jobs that will be run for preload to happen. This has no effect for a persistent runner. The default is 0, and it means always preload."
136    );
137
138    option nytprof => (
139        type => 'b',
140        description => "Use Devel::NYTProf on tests. This will set addpid=1 for you. This works with or without fork.",
141        long_examples => [''],
142    );
143
144    post \&cover_post_process;
145    option cover => (
146        type        => 'd',
147        description => "Use Devel::Cover to calculate test coverage. This disables forking. If no args are specified the following are used: $DEFAULT_COVER_ARGS",
148        long_examples => ['', '=-silent,1,+ignore,^t/,+ignore,^t2/,+ignore,^xt,+ignore,^test.pl'],
149        action      => sub {
150            my ($prefix, $field, $raw, $norm, $slot, $settings) = @_;
151
152            return $$slot = $DEFAULT_COVER_ARGS if $norm eq '1';
153            return $$slot = $norm;
154        },
155    );
156
157    option switch => (
158        field        => 'switches',
159        short        => 'S',
160        type         => 'm',
161        description  => 'Pass the specified switch to perl for each test. This is not compatible with preload.',
162    );
163
164    option event_timeout => (
165        alt => ['et'],
166
167        type => 's',
168        default => 60,
169
170        long_examples  => [' SECONDS'],
171        short_examples => [' SECONDS'],
172        description    => 'Kill test if no output is received within timeout period. (Default: 60 seconds). Add the "# HARNESS-NO-TIMEOUT" comment to the top of a test file to disable timeouts on a per-test basis. This prevents a hung test from running forever.',
173    );
174
175    option post_exit_timeout => (
176        alt => ['pet'],
177
178        type => 's',
179        default => 15,
180
181        long_examples  => [' SECONDS'],
182        short_examples => [' SECONDS'],
183        description    => 'Stop waiting post-exit after the timeout period. (Default: 15 seconds) Some tests fork and allow the parent to exit before writing all their output. If Test2::Harness detects an incomplete plan after the test exits it will monitor for more events until the timeout period. Add the "# HARNESS-NO-TIMEOUT" comment to the top of a test file to disable timeouts on a per-test basis.'
184    );
185};
186
187sub cover_post_process {
188    my %params   = @_;
189    my $settings = $params{settings};
190
191    if ($ENV{T2_DEVEL_COVER} && !$settings->runner->cover) {
192        $settings->runner->field(cover => $ENV{T2_DEVEL_COVER} eq '1' ? $ENV{T2_DEVEL_COVER} : $DEFAULT_COVER_ARGS);
193    }
194
195    return unless $settings->runner->cover;
196
197    # For nested things
198    $ENV{T2_NO_FORK} = 1;
199    $ENV{T2_DEVEL_COVER} = $settings->runner->cover;
200    $settings->runner->field(use_fork => 0);
201
202    return unless $settings->check_prefix('run');
203    push @{$settings->run->load_import->{'@'}} => 'Devel::Cover';
204    $settings->run->load_import->{'Devel::Cover'} = [split(/,/, $settings->runner->cover)];
205}
206
2071;
208
209__END__
210
211
212=pod
213
214=encoding UTF-8
215
216=head1 NAME
217
218App::Yath::Options::Runner - Runner options for Yath.
219
220=head1 DESCRIPTION
221
222This is where command line options for the runner are defined.
223
224=head1 PROVIDED OPTIONS
225
226=head2 COMMAND OPTIONS
227
228=head3 Runner Options
229
230=over 4
231
232=item --abort-on-bail
233
234=item --no-abort-on-bail
235
236Abort all testing if a bail-out is encountered (default: on)
237
238
239=item --blib
240
241=item -b
242
243=item --no-blib
244
245(Default: include if it exists) Include 'blib/lib' and 'blib/arch' in your module path
246
247
248=item --cover
249
250=item --cover=-silent,1,+ignore,^t/,+ignore,^t2/,+ignore,^xt,+ignore,^test.pl
251
252=item --no-cover
253
254Use Devel::Cover to calculate test coverage. This disables forking. If no args are specified the following are used: -silent,1,+ignore,^t/,+ignore,^t2/,+ignore,^xt,+ignore,^test.pl
255
256
257=item --dump-depmap
258
259=item --no-dump-depmap
260
261When using staged preload, dump the depmap for each stage as json files
262
263
264=item --event-timeout SECONDS
265
266=item --et SECONDS
267
268=item --no-event-timeout
269
270Kill test if no output is received within timeout period. (Default: 60 seconds). Add the "# HARNESS-NO-TIMEOUT" comment to the top of a test file to disable timeouts on a per-test basis. This prevents a hung test from running forever.
271
272
273=item --include ARG
274
275=item --include=ARG
276
277=item -I ARG
278
279=item -I=ARG
280
281=item --no-include
282
283Add a directory to your include paths
284
285Can be specified multiple times
286
287
288=item --job-count ARG
289
290=item --job-count=ARG
291
292=item --jobs ARG
293
294=item --jobs=ARG
295
296=item -j ARG
297
298=item -j=ARG
299
300=item --no-job-count
301
302Set the number of concurrent jobs to run (Default: 1)
303
304Can also be set with the following environment variables: C<YATH_JOB_COUNT>, C<T2_HARNESS_JOB_COUNT>, C<HARNESS_JOB_COUNT>
305
306
307=item --lib
308
309=item -l
310
311=item --no-lib
312
313(Default: include if it exists) Include 'lib' in your module path
314
315
316=item --nytprof
317
318=item --no-nytprof
319
320Use Devel::NYTProf on tests. This will set addpid=1 for you. This works with or without fork.
321
322
323=item --post-exit-timeout SECONDS
324
325=item --pet SECONDS
326
327=item --no-post-exit-timeout
328
329Stop waiting post-exit after the timeout period. (Default: 15 seconds) Some tests fork and allow the parent to exit before writing all their output. If Test2::Harness detects an incomplete plan after the test exits it will monitor for more events until the timeout period. Add the "# HARNESS-NO-TIMEOUT" comment to the top of a test file to disable timeouts on a per-test basis.
330
331
332=item --preload-threshold ARG
333
334=item --preload-threshold=ARG
335
336=item --Pt ARG
337
338=item --Pt=ARG
339
340=item -W ARG
341
342=item -W=ARG
343
344=item --no-preload-threshold
345
346Only do preload if at least N tests are going to be run. In some cases a full preload takes longer than simply running the tests, this lets you specify a minimum number of test jobs that will be run for preload to happen. This has no effect for a persistent runner. The default is 0, and it means always preload.
347
348
349=item --preloads ARG
350
351=item --preloads=ARG
352
353=item --preload ARG
354
355=item --preload=ARG
356
357=item -P ARG
358
359=item -P=ARG
360
361=item --no-preloads
362
363Preload a module before running tests
364
365Can be specified multiple times
366
367
368=item --resource Port
369
370=item --resource +Test2::Harness::Runner::Resource::Port
371
372=item -R Port
373
374=item --no-resource
375
376Use a resource module to assign resource assignments to individual tests
377
378Can be specified multiple times
379
380
381=item --switch ARG
382
383=item --switch=ARG
384
385=item -S ARG
386
387=item -S=ARG
388
389=item --no-switch
390
391Pass the specified switch to perl for each test. This is not compatible with preload.
392
393Can be specified multiple times
394
395
396=item --tlib
397
398=item --no-tlib
399
400(Default: off) Include 't/lib' in your module path
401
402
403=item --unsafe-inc
404
405=item --no-unsafe-inc
406
407perl is removing '.' from @INC as a security concern. This option keeps things from breaking for now.
408
409Can also be set with the following environment variables: C<PERL_USE_UNSAFE_INC>
410
411
412=item --use-fork
413
414=item --fork
415
416=item --no-use-fork
417
418(default: on, except on windows) Normally tests are run by forking, which allows for features like preloading. This will turn off the behavior globally (which is not compatible with preloading). This is slower, it is better to tag misbehaving tests with the '# HARNESS-NO-PRELOAD' comment in their header to disable forking only for those tests.
419
420Can also be set with the following environment variables: C<!T2_NO_FORK>, C<T2_HARNESS_FORK>, C<!T2_HARNESS_NO_FORK>, C<YATH_FORK>, C<!YATH_NO_FORK>
421
422
423=item --use-timeout
424
425=item --timeout
426
427=item --no-use-timeout
428
429(default: on) Enable/disable timeouts
430
431
432=back
433
434=head1 SOURCE
435
436The source code repository for Test2-Harness can be found at
437F<http://github.com/Test-More/Test2-Harness/>.
438
439=head1 MAINTAINERS
440
441=over 4
442
443=item Chad Granum E<lt>exodist@cpan.orgE<gt>
444
445=back
446
447=head1 AUTHORS
448
449=over 4
450
451=item Chad Granum E<lt>exodist@cpan.orgE<gt>
452
453=back
454
455=head1 COPYRIGHT
456
457Copyright 2020 Chad Granum E<lt>exodist7@gmail.comE<gt>.
458
459This program is free software; you can redistribute it and/or
460modify it under the same terms as Perl itself.
461
462See F<http://dev.perl.org/licenses/>
463
464=cut
465