1App::Yath::Command::proUjseecrtsC(o3n)tributed Perl DocuAmpepn:t:aYtaitohn::Command::projects(3)
2
6 App::Yath::Command::projects - Run tests for multiple projects
7
9 This command will run all the tests for each project within a parent
10 directory.
11
13 $ yath [YATH OPTIONS] projects [COMMAND OPTIONS]
14 YATH OPTIONS
16 Developer
17 --dev-lib
19 --dev-lib=lib
20 -D
21 -D=lib
22 -Dlib
23 --no-dev-lib
24 Add paths to @INC before loading ANYTHING. This is what you use if
25 you are developing yath or yath plugins to make sure the yath
26 script finds the local code instead of the installed versions of
27 the same code. You can provide an argument (-Dfoo) to provide a
28 custom path, or you can just use -D without and arg to add lib,
29 blib/lib and blib/arch.
30 Can be specified multiple times
32 Environment
34 --persist-dir ARG
36 --persist-dir=ARG
37 --no-persist-dir
38 Where to find persistence files.
39 --persist-file ARG
41 --persist-file=ARG
42 --pfile ARG
43 --pfile=ARG
44 --no-persist-file
45 Where to find the persistence file. The default is
46 /{system-tempdir}/project-yath-persist.json. If no project is
47 specified then it will fall back to the current directory. If the
48 current directory is not writable it will default to
49 /tmp/yath-persist.json which limits you to one persistent runner on
50 your system.
51 --project ARG
53 --project=ARG
54 --project-name ARG
55 --project-name=ARG
56 --no-project
57 This lets you provide a label for your current project/codebase.
58 This is best used in a .yath.rc file. This is necessary for a
59 persistent runner.
60 Finder Options
62 --finder MyFinder
64 --finder +Test2::Harness::Finder::MyFinder
65 --no-finder
66 Specify what Finder subclass to use when searching for
67 files/processing the file list. Use the "+" prefix to specify a
68 fully qualified namespace, otherwise Test2::Harness::Finder::XXX
69 namespace is assumed.
70 Help and Debugging
72 --show-opts
74 --no-show-opts
75 Exit after showing what yath thinks your options mean
76 --version
78 -V
79 --no-version
80 Exit after showing a helpful usage message
81 Plugins
83 --no-scan-plugins
85 --no-no-scan-plugins
86 Normally yath scans for and loads all App::Yath::Plugin::* modules
87 in order to bring in command-line options they may provide. This
88 flag will disable that. This is useful if you have a naughty plugin
89 that it loading other modules when it should not.
90 --plugins PLUGIN
92 --plugins +App::Yath::Plugin::PLUGIN
93 --plugins PLUGIN=arg1,arg2,...
94 --plugin PLUGIN
95 --plugin +App::Yath::Plugin::PLUGIN
96 --plugin PLUGIN=arg1,arg2,...
97 -pPLUGIN
98 --no-plugins
99 Load a yath plugin.
100 Can be specified multiple times
102 COMMAND OPTIONS
104 Display Options
105 --color
107 --no-color
108 Turn color on, default is true if STDOUT is a TTY.
109 --no-wrap
111 --no-no-wrap
112 Do not do fancy text-wrapping, let the terminal handle it
113 --progress
115 --no-progress
116 Toggle progress indicators. On by default if STDOUT is a TTY. You
117 can use --no-progress to disable the 'events seen' counter and
118 buffered event pre-display
119 --quiet
121 -q
122 --no-quiet
123 Be very quiet.
124 Can be specified multiple times
126 --renderers +My::Renderer
128 --renderers Renderer=arg1,arg2,...
129 --renderer +My::Renderer
130 --renderer Renderer=arg1,arg2,...
131 --no-renderers
132 Specify renderers, (Default: "Formatter=Test2"). Use "+" to give a
133 fully qualified module name. Without "+"
134 "Test2::Harness::Renderer::" will be prepended to your argument.
135 Can be specified multiple times. If the same key is listed multiple
137 times the value lists will be appended together.
138 --show-times
140 -T
141 --no-show-times
142 Show the timing data for each job
143 --term-width 80
145 --term-width 200
146 --term-size 80
147 --term-size 200
148 --no-term-width
149 Alternative to setting $TABLE_TERM_SIZE. Setting this will override
150 the terminal width detection to the number of characters specified.
151 --verbose
153 -v
154 --no-verbose
155 Be more verbose
156 Can be specified multiple times
158 Finder Options
160 --default-at-search ARG
162 --default-at-search=ARG
163 --no-default-at-search
164 Specify the default file/dir search when 'AUTHOR_TESTING' is set.
165 Defaults to './xt'. The default AT search is only used if no files
166 were specified at the command line
167 Can be specified multiple times
169 --default-search ARG
171 --default-search=ARG
172 --no-default-search
173 Specify the default file/dir search. defaults to './t', './t2', and
174 'test.pl'. The default search is only used if no files were
175 specified at the command line
176 Can be specified multiple times
178 --durations file.json
180 --durations http://example.com/durations.json
181 --no-durations
182 Point at a json file or url which has a hash of relative test
183 filenames as keys, and 'SHORT', 'MEDIUM', or 'LONG' as values. This
184 will override durations listed in the file headers. An exception
185 will be thrown if the durations file or url does not work.
186 --exclude-file t/nope.t
188 --no-exclude-file
189 Exclude a file from testing
190 Can be specified multiple times
192 --exclude-list file.txt
194 --exclude-list http://example.com/exclusions.txt
195 --no-exclude-list
196 Point at a file or url which has a new line separated list of test
197 file names to exclude from testing. Starting a line with a '#' will
198 comment it out (for compatibility with Test2::Aggregate list
199 files).
200 Can be specified multiple times
202 --exclude-pattern t/nope.t
204 --no-exclude-pattern
205 Exclude a pattern from testing, matched using m/$PATTERN/
206 Can be specified multiple times
208 --extension ARG
210 --extension=ARG
211 --ext ARG
212 --ext=ARG
213 --no-extension
214 Specify valid test filename extensions, default: t and t2
215 Can be specified multiple times
217 --maybe-durations file.json
219 --maybe-durations http://example.com/durations.json
220 --no-maybe-durations
221 Point at a json file or url which has a hash of relative test
222 filenames as keys, and 'SHORT', 'MEDIUM', or 'LONG' as values. This
223 will override durations listed in the file headers. An exception
224 will be thrown if the durations file or url does not work.
225 --no-long
227 --no-no-long
228 Do not run tests that have their duration flag set to 'LONG'
229 --only-long
231 --no-only-long
232 Only run tests that have their duration flag set to 'LONG'
233 --search ARG
235 --search=ARG
236 --no-search
237 List of tests and test directories to use instead of the default
238 search paths. Typically these can simply be listed as command line
239 arguments without the --search prefix.
240 Can be specified multiple times
242 Formatter Options
244 --formatter ARG
246 --formatter=ARG
247 --no-formatter
248 NO DESCRIPTION - FIX ME
249 --qvf
251 --no-qvf
252 [Q]uiet, but [V]erbose on [F]ailure. Hide all output from tests
253 when they pass, except to say they passed. If a test fails then ALL
254 output from the test is verbosely output.
255 --show-job-end
257 --no-show-job-end
258 Show output when a job ends. (Default: on)
259 --show-job-info
261 --no-show-job-info
262 Show the job configuration when a job starts. (Default: off, unless
263 -vv)
264 --show-job-launch
266 --no-show-job-launch
267 Show output for the start of a job. (Default: off unless -v)
268 --show-run-info
270 --no-show-run-info
271 Show the run configuration when a run starts. (Default: off, unless
272 -vv)
273 Help and Debugging
275 --dummy
277 -d
278 --no-dummy
279 Dummy run, do not actually execute anything
280 Can also be set with the following environment variables:
282 "T2_HARNESS_DUMMY"
283 --help
285 -h
286 --no-help
287 exit after showing help information
288 --keep-dirs
290 --keep_dir
291 -k
292 --no-keep-dirs
293 Do not delete directories when done. This is useful if you want to
294 inspect the directories used for various commands.
295 --summary
297 --summary=/path/to/summary.json
298 --no-summary
299 Write out a summary json file, if no path is provided
300 'summary.json' will be used. The .json extension is added
301 automatically if omitted.
302 Logging Options
304 --bzip2
306 --bz2
307 --bzip2_log
308 -B
309 --no-bzip2
310 Use bzip2 compression when writing the log. This option implies -L.
311 The .bz2 prefix is added to log file name for you
312 --gzip
314 --gz
315 --gzip_log
316 -G
317 --no-gzip
318 Use gzip compression when writing the log. This option implies -L.
319 The .gz prefix is added to log file name for you
320 --log
322 -L
323 --no-log
324 Turn on logging
325 --log-dir ARG
327 --log-dir=ARG
328 --no-log-dir
329 Specify a log directory. Will fall back to the system temp dir.
330 --log-file ARG
332 --log-file=ARG
333 -F ARG
334 -F=ARG
335 --no-log-file
336 Specify the name of the log file. This option implies -L.
337 --log-file-format ARG
339 --log-file-format=ARG
340 --lff ARG
341 --lff=ARG
342 --no-log-file-format
343 Specify the format for automatically-generated log files.
344 Overridden by --log-file, if given. This option implies -L
345 (Default: \$YATH_LOG_FILE_FORMAT, if that is set, or else
346 "%!P%Y-%m-%d~%H:%M:%S~%!U~%!p.jsonl"). This is a string in which
347 percent-escape sequences will be replaced as per POSIX::strftime.
348 The following special escape sequences are also replaced: (%!P :
349 Project name followed by a ~, if a project is defined, otherwise
350 empty string) (%!U : the unique test run ID) (%!p : the process ID)
351 (%!S : the number of seconds since local midnight UTC)
352 Can also be set with the following environment variables:
354 "YATH_LOG_FILE_FORMAT", "TEST2_HARNESS_LOG_FORMAT"
355 Notification Options
357 --notify-email foo@example.com
359 --no-notify-email
360 Email the test results to the specified email address(es)
361 Can be specified multiple times
363 --notify-email-fail foo@example.com
365 --no-notify-email-fail
366 Email failing results to the specified email address(es)
367 Can be specified multiple times
369 --notify-email-from foo@example.com
371 --no-notify-email-from
372 If any email is sent, this is who it will be from
373 --notify-email-owner
375 --no-notify-email-owner
376 Email the owner of broken tests files upon failure. Add `# HARNESS-
377 META-OWNER foo@example.com` to the top of a test file to give it an
378 owner
379 --notify-no-batch-email
381 --no-notify-no-batch-email
382 Usually owner failures are sent as a single batch at the end of
383 testing. Toggle this to send failures as they happen.
384 --notify-no-batch-slack
386 --no-notify-no-batch-slack
387 Usually owner failures are sent as a single batch at the end of
388 testing. Toggle this to send failures as they happen.
389 --notify-slack '#foo'
391 --notify-slack '@bar'
392 --no-notify-slack
393 Send results to a slack channel and/or user
394 Can be specified multiple times
396 --notify-slack-fail '#foo'
398 --notify-slack-fail '@bar'
399 --no-notify-slack-fail
400 Send failing results to a slack channel and/or user
401 Can be specified multiple times
403 --notify-slack-owner
405 --no-notify-slack-owner
406 Send slack notifications to the slack channels/users listed in test
407 meta-data when tests fail.
408 --notify-slack-url https://hooks.slack.com/...
410 --no-notify-slack-url
411 Specify an API endpoint for slack webhook integrations
412 --notify-text ARG
414 --notify-text=ARG
415 --message ARG
416 --message=ARG
417 --msg ARG
418 --msg=ARG
419 --no-notify-text
420 Add a custom text snippet to email/slack notifications
421 Run Options
423 --author-testing
425 -A
426 --no-author-testing
427 This will set the AUTHOR_TESTING environment to true
428 --env-var VAR=VAL
430 -EVAR=VAL
431 -E VAR=VAL
432 --no-env-var
433 Set environment variables to set when each test is run.
434 Can be specified multiple times
436 --event-uuids
438 --uuids
439 --no-event-uuids
440 Use Test2::Plugin::UUID inside tests (default: on)
441 --fields name:details
443 --fields JSON_STRING
444 -f name:details
445 -f JSON_STRING
446 --no-fields
447 Add custom data to the harness run
448 Can be specified multiple times
450 --input ARG
452 --input=ARG
453 --no-input
454 Input string to be used as standard input for ALL tests. See also:
455 --input-file
456 --input-file ARG
458 --input-file=ARG
459 --no-input-file
460 Use the specified file as standard input to ALL tests
461 --io-events
463 --no-io-events
464 Use Test2::Plugin::IOEvents inside tests to turn all prints into
465 test2 events (default: off)
466 --link 'https://travis.work/builds/42'
468 --link 'https://jenkins.work/job/42'
469 --link 'https://buildbot.work/builders/foo/builds/42'
470 --no-link
471 Provide one or more links people can follow to see more about this
472 run.
473 Can be specified multiple times
475 --load ARG
477 --load=ARG
478 --load-module ARG
479 --load-module=ARG
480 -m ARG
481 -m=ARG
482 --no-load
483 Load a module in each test (after fork). The "import" method is not
484 called.
485 Can be specified multiple times
487 --load-import Module
489 --load-import Module=import_arg1,arg2,...
490 --loadim Module
491 --loadim Module=import_arg1,arg2,...
492 -M Module
493 -M Module=import_arg1,arg2,...
494 --no-load-import
495 Load a module in each test (after fork). Import is called.
496 Can be specified multiple times. If the same key is listed multiple
498 times the value lists will be appended together.
499 --mem-usage
501 --no-mem-usage
502 Use Test2::Plugin::MemUsage inside tests (default: on)
503 --retry ARG
505 --retry=ARG
506 -r ARG
507 -r=ARG
508 --no-retry
509 Run any jobs that failed a second time. NOTE: --retry=1 means
510 failing tests will be attempted twice!
511 --retry-isolated
513 --retry-iso
514 --no-retry-isolated
515 If true then any job retries will be done in isolation (as though
516 -j1 was set)
517 --run-id
519 --id
520 --no-run-id
521 Set a specific run-id. (Default: a UUID)
522 --test-args ARG
524 --test-args=ARG
525 --no-test-args
526 Arguments to pass in as @ARGV for all tests that are run. These can
527 be provided easier using the '::' argument separator.
528 Can be specified multiple times
530 --stream
532 --no-stream
533 Use the stream formatter (default is on)
534 --tap
536 --TAP
537 ----no-stream
538 --no-tap
539 The TAP format is lossy and clunky. Test2::Harness normally uses a
540 newer streaming format to receive test results. There are
541 old/legacy tests where this causes problems, in which case setting
542 --TAP or --no-stream can help.
543 Runner Options
545 --blib
547 -b
548 --no-blib
549 (Default: include if it exists) Include 'blib/lib' and 'blib/arch'
550 in your module path
551 --cover
553 --cover=-silent,1,+ignore,^t/,+ignore,^t2/,+ignore,^xt,+ignore,^test.pl
554 --no-cover
555 Use Devel::Cover to calculate test coverage. This disables forking.
556 If no args are specified the following are used:
557 -silent,1,+ignore,^t/,+ignore,^t2/,+ignore,^xt,+ignore,^test.pl
558 --cover-files
560 --no-cover-files
561 Use Test2::Plugin::Cover to collect coverage data for what files
562 are touched by what tests. Unlike Devel::Cover this has very little
563 performance impact (About 4% difference)
564 --event-timeout SECONDS
566 --et SECONDS
567 --no-event-timeout
568 Kill test if no output is received within timeout period. (Default:
569 60 seconds). Add the "# HARNESS-NO-TIMEOUT" comment to the top of a
570 test file to disable timeouts on a per-test basis. This prevents a
571 hung test from running forever.
572 --include ARG
574 --include=ARG
575 -I ARG
576 -I=ARG
577 --no-include
578 Add a directory to your include paths
579 Can be specified multiple times
581 --job-count ARG
583 --job-count=ARG
584 --jobs ARG
585 --jobs=ARG
586 -j ARG
587 -j=ARG
588 --no-job-count
589 Set the number of concurrent jobs to run (Default: 1)
590 Can also be set with the following environment variables:
592 "YATH_JOB_COUNT", "T2_HARNESS_JOB_COUNT", "HARNESS_JOB_COUNT"
593 --lib
595 -l
596 --no-lib
597 (Default: include if it exists) Include 'lib' in your module path
598 --post-exit-timeout SECONDS
600 --pet SECONDS
601 --no-post-exit-timeout
602 Stop waiting post-exit after the timeout period. (Default: 15
603 seconds) Some tests fork and allow the parent to exit before
604 writing all their output. If Test2::Harness detects an incomplete
605 plan after the test exits it will monitor for more events until the
606 timeout period. Add the "# HARNESS-NO-TIMEOUT" comment to the top
607 of a test file to disable timeouts on a per-test basis.
608 --preload-threshold ARG
610 --preload-threshold=ARG
611 --Pt ARG
612 --Pt=ARG
613 -W ARG
614 -W=ARG
615 --no-preload-threshold
616 Only do preload if at least N tests are going to be run. In some
617 cases a full preload takes longer than simply running the tests,
618 this lets you specify a minimum number of test jobs that will be
619 run for preload to happen. This has no effect for a persistent
620 runner. The default is 0, and it means always preload.
621 --preloads ARG
623 --preloads=ARG
624 --preload ARG
625 --preload=ARG
626 -P ARG
627 -P=ARG
628 --no-preloads
629 Preload a module before running tests
630 Can be specified multiple times
632 --switch ARG
634 --switch=ARG
635 -S ARG
636 -S=ARG
637 --no-switch
638 Pass the specified switch to perl for each test. This is not
639 compatible with preload.
640 Can be specified multiple times
642 --tlib
644 --no-tlib
645 (Default: off) Include 't/lib' in your module path
646 --unsafe-inc
648 --no-unsafe-inc
649 perl is removing '.' from @INC as a security concern. This option
650 keeps things from breaking for now.
651 Can also be set with the following environment variables:
653 "PERL_USE_UNSAFE_INC"
654 --use-fork
656 --fork
657 --no-use-fork
658 (default: on, except on windows) Normally tests are run by forking,
659 which allows for features like preloading. This will turn off the
660 behavior globally (which is not compatible with preloading). This
661 is slower, it is better to tag misbehaving tests with the '#
662 HARNESS-NO-PRELOAD' comment in their header to disable forking only
663 for those tests.
664 Can also be set with the following environment variables:
666 "!T2_NO_FORK", "T2_HARNESS_FORK", "!T2_HARNESS_NO_FORK",
667 "YATH_FORK", "!YATH_NO_FORK"
668 --use-timeout
670 --timeout
671 --no-use-timeout
672 (default: on) Enable/disable timeouts
673 Workspace Options
675 --clear
677 -C
678 --no-clear
679 Clear the work directory if it is not already empty
680 --tmp-dir ARG
682 --tmp-dir=ARG
683 --tmpdir ARG
684 --tmpdir=ARG
685 -t ARG
686 -t=ARG
687 --no-tmp-dir
688 Use a specific temp directory (Default: use system temp dir)
689 Can also be set with the following environment variables:
691 "T2_HARNESS_TEMP_DIR", "YATH_TEMP_DIR", "TMPDIR", "TEMPDIR",
692 "TMP_DIR", "TEMP_DIR"
693 --workdir ARG
695 --workdir=ARG
696 -w ARG
697 -w=ARG
698 --no-workdir
699 Set the work directory (Default: new temp directory)
700 Can also be set with the following environment variables:
702 "T2_WORKDIR", "YATH_WORKDIR"
703 YathUI Options
705 --yathui-api-key ARG
707 --yathui-api-key=ARG
708 --no-yathui-api-key
709 Yath-UI API key. This is not necessary if your Yath-UI instance is
710 set to single-user
711 --yathui-durations
713 --no-yathui-durations
714 Poll duration data from Yath-UI to help order tests efficiently
715 --yathui-grace
717 --no-yathui-grace
718 If yath cannot connect to yath-ui it normally throws an error, use
719 this to make it fail gracefully. You get a warning, but things keep
720 going.
721 --yathui-long-duration 10
723 --no-yathui-long-duration
724 Minimum duration length (seconds) before a test goes from MEDIUM to
725 LONG
726 --yathui-medium-duration 5
728 --no-yathui-medium-duration
729 Minimum duration length (seconds) before a test goes from SHORT to
730 MEDIUM
731 --yathui-mode summary
733 --yathui-mode qvf
734 --yathui-mode qvfd
735 --yathui-mode complete
736 --no-yathui-mode
737 Set the upload mode (default 'qvfd')
738 --yathui-project ARG
740 --yathui-project=ARG
741 --no-yathui-project
742 The Yath-UI project for your test results
743 --yathui-retry
745 --no-yathui-retry
746 How many times to try an operation before giving up
747 Can be specified multiple times
749 --yathui-upload
751 --no-yathui-upload
752 Upload the log to Yath-UI
753 --yathui-url http://my-yath-ui.com/...
755 --uri http://my-yath-ui.com/...
756 --no-yathui-url
757 Yath-UI url
758
760 The source code repository for Test2-Harness can be found at
761 http://github.com/Test-More/Test2-Harness/.
762
764 Chad Granum <exodist@cpan.org>
765
767 Chad Granum <exodist@cpan.org>
768
770 Copyright 2020 Chad Granum <exodist7@gmail.com>.
771 This program is free software; you can redistribute it and/or modify it
773 under the same terms as Perl itself.
774 See http://dev.perl.org/licenses/
776perl v5.32.0 2020-07-28 App::Yath::Command::projects(3)