1App::Yath::Command::runU(s3e)r Contributed Perl DocumentaAtpipo:n:Yath::Command::run(3)
2
6 App::Yath::Command::run - Run tests using the persistent test runner
7
9 This command will run tests through an already started persistent
10 instance. See the start command for details on how to launch a
11 persistant instance.
12
14 $ yath [YATH OPTIONS] run [COMMAND OPTIONS]
15 YATH OPTIONS
17 Developer
18 --dev-lib
20 --dev-lib=lib
21 -D
22 -D=lib
23 -Dlib
24 --no-dev-lib
25 Add paths to @INC before loading ANYTHING. This is what you use if
26 you are developing yath or yath plugins to make sure the yath
27 script finds the local code instead of the installed versions of
28 the same code. You can provide an argument (-Dfoo) to provide a
29 custom path, or you can just use -D without and arg to add lib,
30 blib/lib and blib/arch.
31 Can be specified multiple times
33 Environment
35 --persist-dir ARG
37 --persist-dir=ARG
38 --no-persist-dir
39 Where to find persistence files.
40 --persist-file ARG
42 --persist-file=ARG
43 --pfile ARG
44 --pfile=ARG
45 --no-persist-file
46 Where to find the persistence file. The default is
47 /{system-tempdir}/project-yath-persist.json. If no project is
48 specified then it will fall back to the current directory. If the
49 current directory is not writable it will default to
50 /tmp/yath-persist.json which limits you to one persistent runner on
51 your system.
52 --project ARG
54 --project=ARG
55 --project-name ARG
56 --project-name=ARG
57 --no-project
58 This lets you provide a label for your current project/codebase.
59 This is best used in a .yath.rc file. This is necessary for a
60 persistent runner.
61 Finder Options
63 --finder MyFinder
65 --finder +Test2::Harness::Finder::MyFinder
66 --no-finder
67 Specify what Finder subclass to use when searching for
68 files/processing the file list. Use the "+" prefix to specify a
69 fully qualified namespace, otherwise Test2::Harness::Finder::XXX
70 namespace is assumed.
71 Help and Debugging
73 --show-opts
75 --no-show-opts
76 Exit after showing what yath thinks your options mean
77 --version
79 -V
80 --no-version
81 Exit after showing a helpful usage message
82 Plugins
84 --no-scan-plugins
86 --no-no-scan-plugins
87 Normally yath scans for and loads all App::Yath::Plugin::* modules
88 in order to bring in command-line options they may provide. This
89 flag will disable that. This is useful if you have a naughty plugin
90 that it loading other modules when it should not.
91 --plugins PLUGIN
93 --plugins +App::Yath::Plugin::PLUGIN
94 --plugins PLUGIN=arg1,arg2,...
95 --plugin PLUGIN
96 --plugin +App::Yath::Plugin::PLUGIN
97 --plugin PLUGIN=arg1,arg2,...
98 -pPLUGIN
99 --no-plugins
100 Load a yath plugin.
101 Can be specified multiple times
103 COMMAND OPTIONS
105 Display Options
106 --color
108 --no-color
109 Turn color on, default is true if STDOUT is a TTY.
110 --no-wrap
112 --no-no-wrap
113 Do not do fancy text-wrapping, let the terminal handle it
114 --progress
116 --no-progress
117 Toggle progress indicators. On by default if STDOUT is a TTY. You
118 can use --no-progress to disable the 'events seen' counter and
119 buffered event pre-display
120 --quiet
122 -q
123 --no-quiet
124 Be very quiet.
125 Can be specified multiple times
127 --renderers +My::Renderer
129 --renderers Renderer=arg1,arg2,...
130 --renderer +My::Renderer
131 --renderer Renderer=arg1,arg2,...
132 --no-renderers
133 Specify renderers, (Default: "Formatter=Test2"). Use "+" to give a
134 fully qualified module name. Without "+"
135 "Test2::Harness::Renderer::" will be prepended to your argument.
136 Can be specified multiple times. If the same key is listed multiple
138 times the value lists will be appended together.
139 --show-times
141 -T
142 --no-show-times
143 Show the timing data for each job
144 --term-width 80
146 --term-width 200
147 --term-size 80
148 --term-size 200
149 --no-term-width
150 Alternative to setting $TABLE_TERM_SIZE. Setting this will override
151 the terminal width detection to the number of characters specified.
152 --verbose
154 -v
155 --no-verbose
156 Be more verbose
157 Can be specified multiple times
159 Finder Options
161 --default-at-search ARG
163 --default-at-search=ARG
164 --no-default-at-search
165 Specify the default file/dir search when 'AUTHOR_TESTING' is set.
166 Defaults to './xt'. The default AT search is only used if no files
167 were specified at the command line
168 Can be specified multiple times
170 --default-search ARG
172 --default-search=ARG
173 --no-default-search
174 Specify the default file/dir search. defaults to './t', './t2', and
175 'test.pl'. The default search is only used if no files were
176 specified at the command line
177 Can be specified multiple times
179 --durations file.json
181 --durations http://example.com/durations.json
182 --no-durations
183 Point at a json file or url which has a hash of relative test
184 filenames as keys, and 'SHORT', 'MEDIUM', or 'LONG' as values. This
185 will override durations listed in the file headers. An exception
186 will be thrown if the durations file or url does not work.
187 --exclude-file t/nope.t
189 --no-exclude-file
190 Exclude a file from testing
191 Can be specified multiple times
193 --exclude-list file.txt
195 --exclude-list http://example.com/exclusions.txt
196 --no-exclude-list
197 Point at a file or url which has a new line separated list of test
198 file names to exclude from testing. Starting a line with a '#' will
199 comment it out (for compatibility with Test2::Aggregate list
200 files).
201 Can be specified multiple times
203 --exclude-pattern t/nope.t
205 --no-exclude-pattern
206 Exclude a pattern from testing, matched using m/$PATTERN/
207 Can be specified multiple times
209 --extension ARG
211 --extension=ARG
212 --ext ARG
213 --ext=ARG
214 --no-extension
215 Specify valid test filename extensions, default: t and t2
216 Can be specified multiple times
218 --maybe-durations file.json
220 --maybe-durations http://example.com/durations.json
221 --no-maybe-durations
222 Point at a json file or url which has a hash of relative test
223 filenames as keys, and 'SHORT', 'MEDIUM', or 'LONG' as values. This
224 will override durations listed in the file headers. An exception
225 will be thrown if the durations file or url does not work.
226 --no-long
228 --no-no-long
229 Do not run tests that have their duration flag set to 'LONG'
230 --only-long
232 --no-only-long
233 Only run tests that have their duration flag set to 'LONG'
234 --search ARG
236 --search=ARG
237 --no-search
238 List of tests and test directories to use instead of the default
239 search paths. Typically these can simply be listed as command line
240 arguments without the --search prefix.
241 Can be specified multiple times
243 Formatter Options
245 --formatter ARG
247 --formatter=ARG
248 --no-formatter
249 NO DESCRIPTION - FIX ME
250 --qvf
252 --no-qvf
253 [Q]uiet, but [V]erbose on [F]ailure. Hide all output from tests
254 when they pass, except to say they passed. If a test fails then ALL
255 output from the test is verbosely output.
256 --show-job-end
258 --no-show-job-end
259 Show output when a job ends. (Default: on)
260 --show-job-info
262 --no-show-job-info
263 Show the job configuration when a job starts. (Default: off, unless
264 -vv)
265 --show-job-launch
267 --no-show-job-launch
268 Show output for the start of a job. (Default: off unless -v)
269 --show-run-info
271 --no-show-run-info
272 Show the run configuration when a run starts. (Default: off, unless
273 -vv)
274 Help and Debugging
276 --dummy
278 -d
279 --no-dummy
280 Dummy run, do not actually execute anything
281 Can also be set with the following environment variables:
283 "T2_HARNESS_DUMMY"
284 --help
286 -h
287 --no-help
288 exit after showing help information
289 --keep-dirs
291 --keep_dir
292 -k
293 --no-keep-dirs
294 Do not delete directories when done. This is useful if you want to
295 inspect the directories used for various commands.
296 --summary
298 --summary=/path/to/summary.json
299 --no-summary
300 Write out a summary json file, if no path is provided
301 'summary.json' will be used. The .json extension is added
302 automatically if omitted.
303 Logging Options
305 --bzip2
307 --bz2
308 --bzip2_log
309 -B
310 --no-bzip2
311 Use bzip2 compression when writing the log. This option implies -L.
312 The .bz2 prefix is added to log file name for you
313 --gzip
315 --gz
316 --gzip_log
317 -G
318 --no-gzip
319 Use gzip compression when writing the log. This option implies -L.
320 The .gz prefix is added to log file name for you
321 --log
323 -L
324 --no-log
325 Turn on logging
326 --log-dir ARG
328 --log-dir=ARG
329 --no-log-dir
330 Specify a log directory. Will fall back to the system temp dir.
331 --log-file ARG
333 --log-file=ARG
334 -F ARG
335 -F=ARG
336 --no-log-file
337 Specify the name of the log file. This option implies -L.
338 --log-file-format ARG
340 --log-file-format=ARG
341 --lff ARG
342 --lff=ARG
343 --no-log-file-format
344 Specify the format for automatically-generated log files.
345 Overridden by --log-file, if given. This option implies -L
346 (Default: \$YATH_LOG_FILE_FORMAT, if that is set, or else
347 "%!P%Y-%m-%d~%H:%M:%S~%!U~%!p.jsonl"). This is a string in which
348 percent-escape sequences will be replaced as per POSIX::strftime.
349 The following special escape sequences are also replaced: (%!P :
350 Project name followed by a ~, if a project is defined, otherwise
351 empty string) (%!U : the unique test run ID) (%!p : the process ID)
352 (%!S : the number of seconds since local midnight UTC)
353 Can also be set with the following environment variables:
355 "YATH_LOG_FILE_FORMAT", "TEST2_HARNESS_LOG_FORMAT"
356 Notification Options
358 --notify-email foo@example.com
360 --no-notify-email
361 Email the test results to the specified email address(es)
362 Can be specified multiple times
364 --notify-email-fail foo@example.com
366 --no-notify-email-fail
367 Email failing results to the specified email address(es)
368 Can be specified multiple times
370 --notify-email-from foo@example.com
372 --no-notify-email-from
373 If any email is sent, this is who it will be from
374 --notify-email-owner
376 --no-notify-email-owner
377 Email the owner of broken tests files upon failure. Add `# HARNESS-
378 META-OWNER foo@example.com` to the top of a test file to give it an
379 owner
380 --notify-no-batch-email
382 --no-notify-no-batch-email
383 Usually owner failures are sent as a single batch at the end of
384 testing. Toggle this to send failures as they happen.
385 --notify-no-batch-slack
387 --no-notify-no-batch-slack
388 Usually owner failures are sent as a single batch at the end of
389 testing. Toggle this to send failures as they happen.
390 --notify-slack '#foo'
392 --notify-slack '@bar'
393 --no-notify-slack
394 Send results to a slack channel and/or user
395 Can be specified multiple times
397 --notify-slack-fail '#foo'
399 --notify-slack-fail '@bar'
400 --no-notify-slack-fail
401 Send failing results to a slack channel and/or user
402 Can be specified multiple times
404 --notify-slack-owner
406 --no-notify-slack-owner
407 Send slack notifications to the slack channels/users listed in test
408 meta-data when tests fail.
409 --notify-slack-url https://hooks.slack.com/...
411 --no-notify-slack-url
412 Specify an API endpoint for slack webhook integrations
413 --notify-text ARG
415 --notify-text=ARG
416 --message ARG
417 --message=ARG
418 --msg ARG
419 --msg=ARG
420 --no-notify-text
421 Add a custom text snippet to email/slack notifications
422 Run Options
424 --author-testing
426 -A
427 --no-author-testing
428 This will set the AUTHOR_TESTING environment to true
429 --env-var VAR=VAL
431 -EVAR=VAL
432 -E VAR=VAL
433 --no-env-var
434 Set environment variables to set when each test is run.
435 Can be specified multiple times
437 --event-uuids
439 --uuids
440 --no-event-uuids
441 Use Test2::Plugin::UUID inside tests (default: on)
442 --fields name:details
444 --fields JSON_STRING
445 -f name:details
446 -f JSON_STRING
447 --no-fields
448 Add custom data to the harness run
449 Can be specified multiple times
451 --input ARG
453 --input=ARG
454 --no-input
455 Input string to be used as standard input for ALL tests. See also:
456 --input-file
457 --input-file ARG
459 --input-file=ARG
460 --no-input-file
461 Use the specified file as standard input to ALL tests
462 --io-events
464 --no-io-events
465 Use Test2::Plugin::IOEvents inside tests to turn all prints into
466 test2 events (default: off)
467 --link 'https://travis.work/builds/42'
469 --link 'https://jenkins.work/job/42'
470 --link 'https://buildbot.work/builders/foo/builds/42'
471 --no-link
472 Provide one or more links people can follow to see more about this
473 run.
474 Can be specified multiple times
476 --load ARG
478 --load=ARG
479 --load-module ARG
480 --load-module=ARG
481 -m ARG
482 -m=ARG
483 --no-load
484 Load a module in each test (after fork). The "import" method is not
485 called.
486 Can be specified multiple times
488 --load-import Module
490 --load-import Module=import_arg1,arg2,...
491 --loadim Module
492 --loadim Module=import_arg1,arg2,...
493 -M Module
494 -M Module=import_arg1,arg2,...
495 --no-load-import
496 Load a module in each test (after fork). Import is called.
497 Can be specified multiple times. If the same key is listed multiple
499 times the value lists will be appended together.
500 --mem-usage
502 --no-mem-usage
503 Use Test2::Plugin::MemUsage inside tests (default: on)
504 --retry ARG
506 --retry=ARG
507 -r ARG
508 -r=ARG
509 --no-retry
510 Run any jobs that failed a second time. NOTE: --retry=1 means
511 failing tests will be attempted twice!
512 --retry-isolated
514 --retry-iso
515 --no-retry-isolated
516 If true then any job retries will be done in isolation (as though
517 -j1 was set)
518 --run-id
520 --id
521 --no-run-id
522 Set a specific run-id. (Default: a UUID)
523 --test-args ARG
525 --test-args=ARG
526 --no-test-args
527 Arguments to pass in as @ARGV for all tests that are run. These can
528 be provided easier using the '::' argument separator.
529 Can be specified multiple times
531 --stream
533 --no-stream
534 Use the stream formatter (default is on)
535 --tap
537 --TAP
538 ----no-stream
539 --no-tap
540 The TAP format is lossy and clunky. Test2::Harness normally uses a
541 newer streaming format to receive test results. There are
542 old/legacy tests where this causes problems, in which case setting
543 --TAP or --no-stream can help.
544 YathUI Options
546 --yathui-api-key ARG
548 --yathui-api-key=ARG
549 --no-yathui-api-key
550 Yath-UI API key. This is not necessary if your Yath-UI instance is
551 set to single-user
552 --yathui-durations
554 --no-yathui-durations
555 Poll duration data from Yath-UI to help order tests efficiently
556 --yathui-grace
558 --no-yathui-grace
559 If yath cannot connect to yath-ui it normally throws an error, use
560 this to make it fail gracefully. You get a warning, but things keep
561 going.
562 --yathui-long-duration 10
564 --no-yathui-long-duration
565 Minimum duration length (seconds) before a test goes from MEDIUM to
566 LONG
567 --yathui-medium-duration 5
569 --no-yathui-medium-duration
570 Minimum duration length (seconds) before a test goes from SHORT to
571 MEDIUM
572 --yathui-mode summary
574 --yathui-mode qvf
575 --yathui-mode qvfd
576 --yathui-mode complete
577 --no-yathui-mode
578 Set the upload mode (default 'qvfd')
579 --yathui-project ARG
581 --yathui-project=ARG
582 --no-yathui-project
583 The Yath-UI project for your test results
584 --yathui-retry
586 --no-yathui-retry
587 How many times to try an operation before giving up
588 Can be specified multiple times
590 --yathui-upload
592 --no-yathui-upload
593 Upload the log to Yath-UI
594 --yathui-url http://my-yath-ui.com/...
596 --uri http://my-yath-ui.com/...
597 --no-yathui-url
598 Yath-UI url
599
601 The source code repository for Test2-Harness can be found at
602 http://github.com/Test-More/Test2-Harness/.
603
605 Chad Granum <exodist@cpan.org>
606
608 Chad Granum <exodist@cpan.org>
609
611 Copyright 2020 Chad Granum <exodist7@gmail.com>.
612 This program is free software; you can redistribute it and/or modify it
614 under the same terms as Perl itself.
615 See http://dev.perl.org/licenses/
617perl v5.32.0 2020-07-28 App::Yath::Command::run(3)