1App::Yath::Command::tesUts(e3r)Contributed Perl DocumentAaptpi:o:nYath::Command::test(3)
2
6 App::Yath::Command::test - Command to run tests
7
11 $ yath test [options] [--] [test files/dirs] [::] [arguments to test scripts]
12 Help
14 --show-opts
15 Exit after showing what yath thinks your options mean
16 -h
18 --help
19 Exit after showing this help message
20 -V
22 --version
23 Show version information
24 Harness Options
26 --id ID
27 --run_id ID
28 Set a specific run-id
29 (Default: a UUID)
31 --no-long
33 Do not run tests with the HARNESS-CAT-LONG header
34 --shm
36 --no-shm
37 Use shm for tempdir if possible (Default: off)
38 Do not use shm.
40 -C
42 --clear
43 Clear the work directory if it is not already empty
44 -D
46 --dummy
47 Dummy run, do not actually execute tests
48 -d path
50 --dir path
51 --workdir path
52 Set the work directory
53 (Default: new temp directory)
55 -j #
57 --jobs #
58 --job-count #
59 Set the number of concurrent jobs to run
60 (Default: 1)
62 -m Module
64 --load Module
65 --load-module Mod
66 Load a module in each test (after fork)
67 this option may be given multiple times
69 -M Module
71 --loadim Module
72 --load-import Mod
73 Load and import module in each test (after fork)
74 this option may be given multiple times
76 -P Module
78 --preload Module
79 Preload a module before running tests
80 this option may be given multiple times
82 -t path/
84 --tmpdir path/
85 Use a specific temp directory
86 (Default: use system temp dir)
88 -X foo
90 --exclude-pattern bar
91 Exclude files that match
92 May be specified multiple times
94 matched using `m/$PATTERN/`
96 -x t/bad.t
98 --exclude-file t/bad.t
99 Exclude a file from testing
100 May be specified multiple times
102 --et SECONDS
104 --event_timeout #
105 Kill test if no events received in timeout period
106 (Default: 60 seconds)
108 This is used to prevent the harness for waiting forever for a hung
110 test. Add the "# HARNESS-NO-TIMEOUT" comment to the top of a test
111 file to disable timeouts on a per-test basis.
112 --no-preload
114 cancel any preloads listed until now
115 This can be used to negate preloads specified in .yath.rc or
117 similar
118 --pet SECONDS
120 --post-exit-timeout #
121 Stop waiting post-exit after the timeout period
122 (Default: 15 seconds)
124 Some tests fork and allow the parent to exit before writing all
126 their output. If Test2::Harness detects an incomplete plan after
127 the test exists it will monitor for more events until the timeout
128 period. Add the "# HARNESS-NO-TIMEOUT" comment to the top of a test
129 file to disable timeouts on a per-test basis.
130 Job Options
132 --blib
133 --no-blib
134 (Default: on) Include 'blib/lib' and 'blib/arch'
135 Do not include 'blib/lib' and 'blib/arch'
137 --input-file file
139 Use the specified file as standard input to ALL tests
140 --lib
142 --no-lib
143 (Default: on) Include 'lib' in your module path
144 Do not include 'lib'
146 --no-mem-usage
148 Disable Test2::Plugin::MemUsage (Loaded by default)
149 --no-uuids
151 Disable Test2::Plugin::UUID (Loaded by default)
152 --retry-job-count=1
154 When re-running failed tests, use a different number of parallel
155 jobs. You might do this if your tests are not reliably parallel
156 safe
157 --retry=1
159 Run any jobs that failed a second time. NOTE: --retry=1 means
160 failing tests will be attempted twice!
161 --slack "#CHANNEL"
163 --slack "@USER"
164 Send results to a slack channel
165 Send results to a slack user
167 --slack-fail "#CHANNEL"
169 --slack-fail "@USER"
170 Send failing results to a slack channel
171 Send failing results to a slack user
173 --tlib
175 (Default: off) Include 't/lib' in your module path
176 -E VAR=value
178 --env-var VAR=val
179 Set an environment variable for each test
180 (but not the harness)
182 -i "string"
184 This input string will be used as standard input for ALL tests
185 See also --input-file
187 -I path/lib
189 --include lib/
190 Add a directory to your include paths
191 This can be used multiple times
193 --cover
195 use Devel::Cover to calculate test coverage
196 This is essentially the same as combining: '--no-fork', and
198 '-MDevel::Cover=-silent,1,+ignore,^t/,+ignore,^t2/,+ignore,^xt,+ignore,^test.pl'
199 Devel::Cover and preload/fork do not work well together.
200 --default-at-search xt
202 Specify the default file/dir search when 'AUTHOR_TESTING' is set.
203 Defaults to './xt'. The default AT search is only used if no files
204 were specified at the command line
205 --default-search t
207 Specify the default file/dir search. defaults to './t', './t2', and
208 'test.pl'. The default search is only used if no files were
209 specified at the command line
210 --email foo@example.com
212 Email the test results (and any log file) to the specified email
213 address(es)
214 --email-from foo@example.com
216 If any email is sent, this is who it will be from
217 --email-owner
219 Email the owner of broken tests files upon failure. Add `# HARNESS-
220 META-OWNER foo@example.com` to the top of a test file to give it an
221 owner
222 --fork
224 --no-fork
225 (Default: on) fork to start tests
226 Do not fork to start tests
228 Test2::Harness normally forks to start a test. Forking can break
230 some select tests, this option will allow such tests to pass. This
231 is not compatible with the "preload" option. This is also
232 significantly slower. You can also add the "# HARNESS-NO-PRELOAD"
233 comment to the top of the test file to enable this on a per-test
234 basis.
235 --no-batch-owner-notices
237 Usually owner failures are sent as a single batch at the end of
238 testing. Toggle this to send failures as they happen.
239 --notify-text "custom notification info"
241 Add a custom text snippet to email/slack notifications
242 --slack-log
244 --no-slack-log
245 Off by default, log file will be attached if available
246 Attach the event log to any slack notifications.
248 --slack-notify
250 --no-slack-notify
251 On by default if --slack-url is specified
252 Send slack notifications to the slack channels/users listed in test
254 meta-data when tests fail.
255 --slack-url "URL"
257 Specify an API endpoint for slack webhook integrations
258 This should be your slack webhook url.
260 --stream
262 --no-stream
263 --TAP
264 --tap
265 Use 'stream' instead of TAP (Default: use stream)
266 Do not use stream
268 Use TAP
270 The TAP format is lossy and clunky. Test2::Harness normally uses a
272 newer streaming format to receive test results. There are
273 old/legacy tests where this causes problems, in which case setting
274 --TAP or --no-stream can help.
275 --times
277 Monitor timing data for each test file
278 This tells perl to load Test2::Plugin::Times before starting each
280 test. Use -T to show the timing data
281 --unsafe-inc
283 --no-unsafe-inc
284 (Default: On) put '.' in @INC
285 Do not put '.' in @INC
287 perl is removing '.' from @INC as a security concern. This option
289 keeps things from breaking for now.
290 -A
292 --author-testing
293 --no-author-testing
294 This will set the AUTHOR_TESTING environment to true
295 Many cpan modules have tests that are only run if the
297 AUTHOR_TESTING environment variable is set. This will cause those
298 tests to run.
299 -k
301 --keep-dir
302 Do not delete the work directory when done
303 This is useful if you want to inspect the work directory after the
305 harness is done. The work directory path will be printed at the
306 end.
307 -S SW
309 -S SW=val
310 --switch SW=val
311 Pass the specified switch to perl for each test
312 This is not compatible with preload.
314 Logging Options
316 -B
317 --bz2
318 --bzip2-log
319 Use bzip2 compression when writing the log
320 This option implies -L
322 .bz2 prefix is added to log file name for you
324 -F file.jsonl
326 --log-file FILE
327 Specify the name of the log file
328 This option implies -L
330 (Default: event_log-RUN_ID.jsonl)
332 -G
334 --gz
335 --gzip-log
336 Use gzip compression when writing the log
337 This option implies -L
339 .gz prefix is added to log file name for you
341 -L
343 --log
344 Turn on logging
345 --lff format-string
347 --log-file-format format-string
348 Specify the format for automatically-generated log files.
349 Overridden by --log-file, if given
351 This option implies -L
353 (Default: $YATH_LOG_FILE_FORMAT, if that is set, or else
355 '%Y-%m-%d~%H:%M:%S~%!U~%!p.jsonl')
356 This is a string in which percent-escape sequences will be replaced
358 as per POSIX::strftime. The following special escape sequences are
359 also replaced: (%!U : the unique test run ID) (%!p : the process
360 ID) (%!S : the number of seconds since local midnight UTC
361 Display Options
363 --color
364 --no-color
365 Turn color on (Default: on)
366 Turn color off
368 --show-job-info
370 --no-show-job-info
371 Show the job configuration when a job starts
372 (Default: off, unless -vv)
374 --show-job-launch
376 --no-show-job-launch
377 Show output for the start of a job
378 (Default: off unless -v)
380 --show-run-info
382 --no-show-run-info
383 Show the run configuration when a run starts
384 (Default: off, unless -vv)
386 -q
388 --quiet
389 Be very quiet
390 -T
392 --show-times
393 Show the timing data for each job
394 -v
396 -vv
397 --verbose
398 Turn on verbose mode.
399 Specify multiple times to be more verbose.
401 --formatter Mod
403 --formatter +Mod
404 Specify the formatter to use
405 (Default: "Test2")
407 Only useful when a renderer is set to "Formatter". This specified
409 the Test2::Formatter::XXX that will be used to render the test
410 output.
411 --no-progress
413 Turn off progress indicators
414 This disables "events seen" counter and buffered event pre-display
416 --qvf
418 Quiet, but verbose on failure
419 Hide all output from tests when they pass, except to say they
421 passed. If a test fails then ALL output from the test is verbosely
422 output.
423 --show-job-end
425 --no-show-job-end
426 Show output when a job ends
427 (Default: on)
429 This is only used when the renderer is set to "Formatter"
431 -r +Module
433 -r Postfix
434 --renderer ...
435 -r +Module=arg1,arg2,...
436 Specify renderers
437 (Default: "Formatter")
439 Use "+" to give a fully qualified module name. Without "+"
441 "Test2::Harness::Renderer::" will be prepended to your argument.
442 You may specify custom arguments to the constructor after an "="
443 sign.
444 Plugins
446 -pPlugin
447 -p+My::Plugin
448 --plugin Plugin
449 Load a plugin
450 can be specified multiple times
452 --no-plugins
454 cancel any plugins listed until now
455 This can be used to negate plugins specified in .yath.rc or similar
457
459 The source code repository for Test2-Harness can be found at
460 http://github.com/Test-More/Test2-Harness/.
461
463 Chad Granum <exodist@cpan.org>
464
466 Chad Granum <exodist@cpan.org>
467
469 Copyright 2019 Chad Granum <exodist7@gmail.com>.
470 This program is free software; you can redistribute it and/or modify it
472 under the same terms as Perl itself.
473 See http://dev.perl.org/licenses/
475perl v5.30.0 2019-08-14 App::Yath::Command::test(3)