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 --changed path/to/file
163 --no-changed
164 Specify one or more files as having been changed.
165 Can be specified multiple times
167 --changed-only
169 --no-changed-only
170 Only search for tests for changed files (Requires --coverage-from,
171 also requires a list of changes either from the --changed option,
172 or a plugin that implements changed_files())
173 --changes-plugin Git
175 --changes-plugin +App::Yath::Plugin::Git
176 --no-changes-plugin
177 What plugin should be used to detect changed files.
178 --coverage-from path/to/log.jsonl
180 --coverage-from http://example.com/coverage
181 --coverage-from path/to/coverage.json
182 --no-coverage-from
183 Where to fetch coverage data. Can be a path to a .jsonl(.bz|.gz)?
184 log file. Can be a path or url to a json file containing a hash
185 where source files are key, and value is a list of tests to run.
186 --coverage-url-use-post
188 --no-coverage-url-use-post
189 If coverage_from is a url, use the http POST method with a list of
190 changed files. This allows the server to tell us what tests to run
191 instead of downloading all the coverage data and determining what
192 tests to run from that.
193 --default-at-search ARG
195 --default-at-search=ARG
196 --no-default-at-search
197 Specify the default file/dir search when 'AUTHOR_TESTING' is set.
198 Defaults to './xt'. The default AT search is only used if no files
199 were specified at the command line
200 Can be specified multiple times
202 --default-search ARG
204 --default-search=ARG
205 --no-default-search
206 Specify the default file/dir search. defaults to './t', './t2', and
207 'test.pl'. The default search is only used if no files were
208 specified at the command line
209 Can be specified multiple times
211 --durations file.json
213 --durations http://example.com/durations.json
214 --no-durations
215 Point at a json file or url which has a hash of relative test
216 filenames as keys, and 'SHORT', 'MEDIUM', or 'LONG' as values. This
217 will override durations listed in the file headers. An exception
218 will be thrown if the durations file or url does not work.
219 --exclude-file t/nope.t
221 --no-exclude-file
222 Exclude a file from testing
223 Can be specified multiple times
225 --exclude-list file.txt
227 --exclude-list http://example.com/exclusions.txt
228 --no-exclude-list
229 Point at a file or url which has a new line separated list of test
230 file names to exclude from testing. Starting a line with a '#' will
231 comment it out (for compatibility with Test2::Aggregate list
232 files).
233 Can be specified multiple times
235 --exclude-pattern t/nope.t
237 --no-exclude-pattern
238 Exclude a pattern from testing, matched using m/$PATTERN/
239 Can be specified multiple times
241 --extension ARG
243 --extension=ARG
244 --ext ARG
245 --ext=ARG
246 --no-extension
247 Specify valid test filename extensions, default: t and t2
248 Can be specified multiple times
250 --maybe-coverage-from path/to/log.jsonl
252 --maybe-coverage-from http://example.com/coverage
253 --maybe-coverage-from path/to/coverage.json
254 --no-maybe-coverage-from
255 Where to fetch coverage data. Can be a path to a .jsonl(.bz|.gz)?
256 log file. Can be a path or url to a json file containing a hash
257 where source files are key, and value is a list of tests to run.
258 --maybe-durations file.json
260 --maybe-durations http://example.com/durations.json
261 --no-maybe-durations
262 Point at a json file or url which has a hash of relative test
263 filenames as keys, and 'SHORT', 'MEDIUM', or 'LONG' as values. This
264 will override durations listed in the file headers. An exception
265 will be thrown if the durations file or url does not work.
266 --no-long
268 --no-no-long
269 Do not run tests that have their duration flag set to 'LONG'
270 --only-long
272 --no-only-long
273 Only run tests that have their duration flag set to 'LONG'
274 --search ARG
276 --search=ARG
277 --no-search
278 List of tests and test directories to use instead of the default
279 search paths. Typically these can simply be listed as command line
280 arguments without the --search prefix.
281 Can be specified multiple times
283 --show-changed-files
285 --no-show-changed-files
286 Print a list of changed files if any are found
287 Formatter Options
289 --formatter ARG
291 --formatter=ARG
292 --no-formatter
293 NO DESCRIPTION - FIX ME
294 --qvf
296 --no-qvf
297 [Q]uiet, but [V]erbose on [F]ailure. Hide all output from tests
298 when they pass, except to say they passed. If a test fails then ALL
299 output from the test is verbosely output.
300 --show-job-end
302 --no-show-job-end
303 Show output when a job ends. (Default: on)
304 --show-job-info
306 --no-show-job-info
307 Show the job configuration when a job starts. (Default: off, unless
308 -vv)
309 --show-job-launch
311 --no-show-job-launch
312 Show output for the start of a job. (Default: off unless -v)
313 --show-run-info
315 --no-show-run-info
316 Show the run configuration when a run starts. (Default: off, unless
317 -vv)
318 Git Options
320 --git-change-base master
322 --git-change-base HEAD^
323 --git-change-base df22abe4
324 --no-git-change-base
325 Find files changed by all commits in the current branch from most
326 recent stopping when a commit is found that is also present in the
327 history of the branch/commit specified as the change base.
328 Help and Debugging
330 --dummy
332 -d
333 --no-dummy
334 Dummy run, do not actually execute anything
335 Can also be set with the following environment variables:
337 "T2_HARNESS_DUMMY"
338 --help
340 -h
341 --no-help
342 exit after showing help information
343 --keep-dirs
345 --keep_dir
346 -k
347 --no-keep-dirs
348 Do not delete directories when done. This is useful if you want to
349 inspect the directories used for various commands.
350 --summary
352 --summary=/path/to/summary.json
353 --no-summary
354 Write out a summary json file, if no path is provided
355 'summary.json' will be used. The .json extension is added
356 automatically if omitted.
357 Logging Options
359 --bzip2
361 --bz2
362 --bzip2_log
363 -B
364 --no-bzip2
365 Use bzip2 compression when writing the log. This option implies -L.
366 The .bz2 prefix is added to log file name for you
367 --gzip
369 --gz
370 --gzip_log
371 -G
372 --no-gzip
373 Use gzip compression when writing the log. This option implies -L.
374 The .gz prefix is added to log file name for you
375 --log
377 -L
378 --no-log
379 Turn on logging
380 --log-dir ARG
382 --log-dir=ARG
383 --no-log-dir
384 Specify a log directory. Will fall back to the system temp dir.
385 --log-file ARG
387 --log-file=ARG
388 -F ARG
389 -F=ARG
390 --no-log-file
391 Specify the name of the log file. This option implies -L.
392 --log-file-format ARG
394 --log-file-format=ARG
395 --lff ARG
396 --lff=ARG
397 --no-log-file-format
398 Specify the format for automatically-generated log files.
399 Overridden by --log-file, if given. This option implies -L
400 (Default: \$YATH_LOG_FILE_FORMAT, if that is set, or else
401 "%!P%Y-%m-%d~%H:%M:%S~%!U~%!p.jsonl"). This is a string in which
402 percent-escape sequences will be replaced as per POSIX::strftime.
403 The following special escape sequences are also replaced: (%!P :
404 Project name followed by a ~, if a project is defined, otherwise
405 empty string) (%!U : the unique test run ID) (%!p : the process ID)
406 (%!S : the number of seconds since local midnight UTC)
407 Can also be set with the following environment variables:
409 "YATH_LOG_FILE_FORMAT", "TEST2_HARNESS_LOG_FORMAT"
410 --write-coverage
412 --write-coverage=coverage.json
413 --no-write-coverage
414 Create a json file of all coverage data seen during the run (This
415 implies --cover-files).
416 Notification Options
418 --notify-email foo@example.com
420 --no-notify-email
421 Email the test results to the specified email address(es)
422 Can be specified multiple times
424 --notify-email-fail foo@example.com
426 --no-notify-email-fail
427 Email failing results to the specified email address(es)
428 Can be specified multiple times
430 --notify-email-from foo@example.com
432 --no-notify-email-from
433 If any email is sent, this is who it will be from
434 --notify-email-owner
436 --no-notify-email-owner
437 Email the owner of broken tests files upon failure. Add `# HARNESS-
438 META-OWNER foo@example.com` to the top of a test file to give it an
439 owner
440 --notify-no-batch-email
442 --no-notify-no-batch-email
443 Usually owner failures are sent as a single batch at the end of
444 testing. Toggle this to send failures as they happen.
445 --notify-no-batch-slack
447 --no-notify-no-batch-slack
448 Usually owner failures are sent as a single batch at the end of
449 testing. Toggle this to send failures as they happen.
450 --notify-slack '#foo'
452 --notify-slack '@bar'
453 --no-notify-slack
454 Send results to a slack channel and/or user
455 Can be specified multiple times
457 --notify-slack-fail '#foo'
459 --notify-slack-fail '@bar'
460 --no-notify-slack-fail
461 Send failing results to a slack channel and/or user
462 Can be specified multiple times
464 --notify-slack-owner
466 --no-notify-slack-owner
467 Send slack notifications to the slack channels/users listed in test
468 meta-data when tests fail.
469 --notify-slack-url https://hooks.slack.com/...
471 --no-notify-slack-url
472 Specify an API endpoint for slack webhook integrations
473 --notify-text ARG
475 --notify-text=ARG
476 --message ARG
477 --message=ARG
478 --msg ARG
479 --msg=ARG
480 --no-notify-text
481 Add a custom text snippet to email/slack notifications
482 Run Options
484 --author-testing
486 -A
487 --no-author-testing
488 This will set the AUTHOR_TESTING environment to true
489 --cover-files
491 --no-cover-files
492 Use Test2::Plugin::Cover to collect coverage data for what files
493 are touched by what tests. Unlike Devel::Cover this has very little
494 performance impact (About 4% difference)
495 --dbi-profiling
497 --no-dbi-profiling
498 Use Test2::Plugin::DBIProfile to collect database profiling data
499 --env-var VAR=VAL
501 -EVAR=VAL
502 -E VAR=VAL
503 --no-env-var
504 Set environment variables to set when each test is run.
505 Can be specified multiple times
507 --event-uuids
509 --uuids
510 --no-event-uuids
511 Use Test2::Plugin::UUID inside tests (default: on)
512 --fields name:details
514 --fields JSON_STRING
515 -f name:details
516 -f JSON_STRING
517 --no-fields
518 Add custom data to the harness run
519 Can be specified multiple times
521 --input ARG
523 --input=ARG
524 --no-input
525 Input string to be used as standard input for ALL tests. See also:
526 --input-file
527 --input-file ARG
529 --input-file=ARG
530 --no-input-file
531 Use the specified file as standard input to ALL tests
532 --io-events
534 --no-io-events
535 Use Test2::Plugin::IOEvents inside tests to turn all prints into
536 test2 events (default: off)
537 --link 'https://travis.work/builds/42'
539 --link 'https://jenkins.work/job/42'
540 --link 'https://buildbot.work/builders/foo/builds/42'
541 --no-link
542 Provide one or more links people can follow to see more about this
543 run.
544 Can be specified multiple times
546 --load ARG
548 --load=ARG
549 --load-module ARG
550 --load-module=ARG
551 -m ARG
552 -m=ARG
553 --no-load
554 Load a module in each test (after fork). The "import" method is not
555 called.
556 Can be specified multiple times
558 --load-import Module
560 --load-import Module=import_arg1,arg2,...
561 --loadim Module
562 --loadim Module=import_arg1,arg2,...
563 -M Module
564 -M Module=import_arg1,arg2,...
565 --no-load-import
566 Load a module in each test (after fork). Import is called.
567 Can be specified multiple times. If the same key is listed multiple
569 times the value lists will be appended together.
570 --mem-usage
572 --no-mem-usage
573 Use Test2::Plugin::MemUsage inside tests (default: on)
574 --retry ARG
576 --retry=ARG
577 -r ARG
578 -r=ARG
579 --no-retry
580 Run any jobs that failed a second time. NOTE: --retry=1 means
581 failing tests will be attempted twice!
582 --retry-isolated
584 --retry-iso
585 --no-retry-isolated
586 If true then any job retries will be done in isolation (as though
587 -j1 was set)
588 --run-id
590 --id
591 --no-run-id
592 Set a specific run-id. (Default: a UUID)
593 --test-args ARG
595 --test-args=ARG
596 --no-test-args
597 Arguments to pass in as @ARGV for all tests that are run. These can
598 be provided easier using the '::' argument separator.
599 Can be specified multiple times
601 --stream
603 --no-stream
604 Use the stream formatter (default is on)
605 --tap
607 --TAP
608 ----no-stream
609 --no-tap
610 The TAP format is lossy and clunky. Test2::Harness normally uses a
611 newer streaming format to receive test results. There are
612 old/legacy tests where this causes problems, in which case setting
613 --TAP or --no-stream can help.
614 YathUI Options
616 --yathui-api-key ARG
618 --yathui-api-key=ARG
619 --no-yathui-api-key
620 Yath-UI API key. This is not necessary if your Yath-UI instance is
621 set to single-user
622 --yathui-coverage
624 --no-yathui-coverage
625 Poll coverage data from Yath-UI to determine what tests should be
626 run for changed files
627 --yathui-db
629 --no-yathui-db
630 Add the YathUI DB renderer in addition to other renderers
631 --yathui-durations
633 --no-yathui-durations
634 Poll duration data from Yath-UI to help order tests efficiently
635 --yathui-grace
637 --no-yathui-grace
638 If yath cannot connect to yath-ui it normally throws an error, use
639 this to make it fail gracefully. You get a warning, but things keep
640 going.
641 --yathui-long-duration 10
643 --no-yathui-long-duration
644 Minimum duration length (seconds) before a test goes from MEDIUM to
645 LONG
646 --yathui-medium-duration 5
648 --no-yathui-medium-duration
649 Minimum duration length (seconds) before a test goes from SHORT to
650 MEDIUM
651 --yathui-mode summary
653 --yathui-mode qvf
654 --yathui-mode qvfd
655 --yathui-mode complete
656 --no-yathui-mode
657 Set the upload mode (default 'qvfd')
658 --yathui-only
660 --no-yathui-only
661 Only use the YathUI renderer
662 --yathui-only-db
664 --no-yathui-only-db
665 Only use the YathUI DB renderer
666 --yathui-port 8080
668 --no-yathui-port
669 Port to use when running a local server
670 --yathui-port-command get_port.sh
672 --yathui-port-command get_port.sh --pid $$
673 --no-yathui-port-command
674 Use a command to get a port number. "$$" will be replaced with the
675 PID of the yath process
676 --yathui-project ARG
678 --yathui-project=ARG
679 --no-yathui-project
680 The Yath-UI project for your test results
681 --yathui-render
683 --no-yathui-render
684 Add the YathUI renderer in addition to other renderers
685 --yathui-retry
687 --no-yathui-retry
688 How many times to try an operation before giving up
689 Can be specified multiple times
691 --yathui-schema PostgreSQL
693 --yathui-schema MySQL
694 --yathui-schema MySQL56
695 --no-yathui-schema
696 What type of DB/schema to use when using a temporary database
697 --yathui-upload
699 --no-yathui-upload
700 Upload the log to Yath-UI
701 --yathui-url http://my-yath-ui.com/...
703 --uri http://my-yath-ui.com/...
704 --no-yathui-url
705 Yath-UI url
706 --yathui-user ARG
708 --yathui-user=ARG
709 --no-yathui-user
710 Username to attach to the data sent to the db
711 --yathui-db-buffering none
713 --yathui-db-buffering job
714 --yathui-db-buffering diag
715 --yathui-db-buffering run
716 --no-yathui-db-buffering
717 Type of buffering to use, if "none" then events are written to the
718 db one at a time, which is SLOW
719 --yathui-db-config ARG
721 --yathui-db-config=ARG
722 --no-yathui-db-config
723 Module that implements 'MODULE->yath_ui_config(%params)' which
724 should return a Test2::Harness::UI::Config instance.
725 --yathui-db-driver Pg
727 --yathui-db-drivermysql
728 --yathui-db-driverMariaDB
729 --no-yathui-db-driver
730 DBI Driver to use
731 --yathui-db-dsn ARG
733 --yathui-db-dsn=ARG
734 --no-yathui-db-dsn
735 DSN to use when connecting to the db
736 --yathui-db-flush-interval 2
738 --yathui-db-flush-interval 1.5
739 --no-yathui-db-flush-interval
740 When buffering DB writes, force a flush when an event is recieved
741 at least N seconds after the last flush.
742 --yathui-db-host ARG
744 --yathui-db-host=ARG
745 --no-yathui-db-host
746 hostname to use when connecting to the db
747 --yathui-db-name ARG
749 --yathui-db-name=ARG
750 --no-yathui-db-name
751 Name of the database to use for yathui
752 --yathui-db-pass ARG
754 --yathui-db-pass=ARG
755 --no-yathui-db-pass
756 Password to use when connecting to the db
757 --yathui-db-port ARG
759 --yathui-db-port=ARG
760 --no-yathui-db-port
761 port to use when connecting to the db
762 --yathui-db-socket ARG
764 --yathui-db-socket=ARG
765 --no-yathui-db-socket
766 socket to use when connecting to the db
767 --yathui-db-user ARG
769 --yathui-db-user=ARG
770 --no-yathui-db-user
771 Username to use when connecting to the db
772
774 The source code repository for Test2-Harness can be found at
775 http://github.com/Test-More/Test2-Harness/.
776
778 Chad Granum <exodist@cpan.org>
779
781 Chad Granum <exodist@cpan.org>
782
784 Copyright 2021 Chad Granum <exodist7@gmail.com>.
785 This program is free software; you can redistribute it and/or modify it
787 under the same terms as Perl itself.
788 See http://dev.perl.org/licenses/
790perl v5.32.1 2021-03-12 App::Yath::Command::run(3)