1App::Yath::Command::staUrste(r3)Contributed Perl DocumenAtpapt:i:oYnath::Command::start(3)
2
6 App::Yath::Command::start - Start the persistent test runner
7
9 This command is used to start a persistant instance of yath. A
10 persistant instance is useful because it allows you to preload modules
11 in advance, reducing start time for any tests you decide to run as you
12 work.
13 A running instance will watch for changes to any preloaded files, and
15 restart itself if anything changes. Changed files are blacklisted for
16 subsequent reloads so that reloading is not a frequent occurence when
17 editing the same file over and over again.
18
20 $ yath [YATH OPTIONS] start [COMMAND OPTIONS]
21 YATH OPTIONS
23 Developer
24 --dev-lib
26 --dev-lib=lib
27 -D
28 -D=lib
29 -Dlib
30 --no-dev-lib
31 Add paths to @INC before loading ANYTHING. This is what you use if
32 you are developing yath or yath plugins to make sure the yath
33 script finds the local code instead of the installed versions of
34 the same code. You can provide an argument (-Dfoo) to provide a
35 custom path, or you can just use -D without and arg to add lib,
36 blib/lib and blib/arch.
37 Can be specified multiple times
39 Environment
41 --persist-dir ARG
43 --persist-dir=ARG
44 --no-persist-dir
45 Where to find persistence files.
46 --persist-file ARG
48 --persist-file=ARG
49 --pfile ARG
50 --pfile=ARG
51 --no-persist-file
52 Where to find the persistence file. The default is
53 /{system-tempdir}/project-yath-persist.json. If no project is
54 specified then it will fall back to the current directory. If the
55 current directory is not writable it will default to
56 /tmp/yath-persist.json which limits you to one persistent runner on
57 your system.
58 --project ARG
60 --project=ARG
61 --project-name ARG
62 --project-name=ARG
63 --no-project
64 This lets you provide a label for your current project/codebase.
65 This is best used in a .yath.rc file. This is necessary for a
66 persistent runner.
67 Help and Debugging
69 --show-opts
71 --no-show-opts
72 Exit after showing what yath thinks your options mean
73 --version
75 -V
76 --no-version
77 Exit after showing a helpful usage message
78 Plugins
80 --no-scan-plugins
82 --no-no-scan-plugins
83 Normally yath scans for and loads all App::Yath::Plugin::* modules
84 in order to bring in command-line options they may provide. This
85 flag will disable that. This is useful if you have a naughty plugin
86 that is loading other modules when it should not.
87 --plugins PLUGIN
89 --plugins +App::Yath::Plugin::PLUGIN
90 --plugins PLUGIN=arg1,arg2,...
91 --plugin PLUGIN
92 --plugin +App::Yath::Plugin::PLUGIN
93 --plugin PLUGIN=arg1,arg2,...
94 -pPLUGIN
95 --no-plugins
96 Load a yath plugin.
97 Can be specified multiple times
99 COMMAND OPTIONS
101 Collector Options
102 --max-open-jobs 18
104 --no-max-open-jobs
105 Maximum number of jobs a collector can process at a time, if more
106 jobs are pending their output will be delayed until the earlier
107 jobs have been processed. (Default: double the -j value)
108 --max-poll-events 1000
110 --no-max-poll-events
111 Maximum number of events to poll from a job before jumping to the
112 next job. (Default: 1000)
113 Cover Options
115 --cover-aggregator ByTest
117 --cover-aggregator ByRun
118 --cover-aggregator +Custom::Aggregator
119 --cover-agg ByTest
120 --cover-agg ByRun
121 --cover-agg +Custom::Aggregator
122 --no-cover-aggregator
123 Choose a custom aggregator subclass
124 --cover-class ARG
126 --cover-class=ARG
127 --no-cover-class
128 Choose a Test2::Plugin::Cover subclass
129 --cover-dirs ARG
131 --cover-dirs=ARG
132 --cover-dir ARG
133 --cover-dir=ARG
134 --no-cover-dirs
135 NO DESCRIPTION - FIX ME
136 Can be specified multiple times
138 --cover-exclude-private
140 --no-cover-exclude-private
141 --cover-files
142 --no-cover-files
143 Use Test2::Plugin::Cover to collect coverage data for what files
144 are touched by what tests. Unlike Devel::Cover this has very little
145 performance impact (About 4% difference)
146 --cover-from path/to/log.jsonl
148 --cover-from http://example.com/coverage
149 --cover-from path/to/coverage.jsonl
150 --no-cover-from
151 This can be a test log, a coverage dump (old style json or new
152 jsonl format), or a url to any of the previous. Tests will not be
153 run if the file/url is invalid.
154 --cover-from-type json
156 --cover-from-type jsonl
157 --cover-from-type log
158 --no-cover-from-type
159 File type for coverage source. Usually it can be detected, but when
160 it cannot be you should specify. "json" is old style single-blob
161 coverage data, "jsonl" is the new by-test style, "log" is a logfile
162 from a previous run.
163 --cover-manager My::Coverage::Manager
165 --no-cover-manager
166 Coverage 'from' manager to use when coverage data does not provide
167 one
168 --cover-maybe-from path/to/log.jsonl
170 --cover-maybe-from http://example.com/coverage
171 --cover-maybe-from path/to/coverage.jsonl
172 --no-cover-maybe-from
173 This can be a test log, a coverage dump (old style json or new
174 jsonl format), or a url to any of the previous. Tests will coninue
175 if even if the coverage file/url is invalid.
176 --cover-maybe-from-type json
178 --cover-maybe-from-type jsonl
179 --cover-maybe-from-type log
180 --no-cover-maybe-from-type
181 Same as "from_type" but for "maybe_from". Defaults to "from_type"
182 if that is specified, otherwise auto-detect
183 --cover-metrics
185 --no-cover-metrics
186 --cover-types ARG
187 --cover-types=ARG
188 --cover-type ARG
189 --cover-type=ARG
190 --no-cover-types
191 NO DESCRIPTION - FIX ME
192 Can be specified multiple times
194 --cover-write
196 --cover-write=coverage.jsonl
197 --cover-write=coverage.json
198 --no-cover-write
199 Create a json or jsonl file of all coverage data seen during the
200 run (This implies --cover-files).
201 Git Options
203 --git-change-base master
205 --git-change-base HEAD^
206 --git-change-base df22abe4
207 --no-git-change-base
208 Find files changed by all commits in the current branch from most
209 recent stopping when a commit is found that is also present in the
210 history of the branch/commit specified as the change base.
211 Help and Debugging
213 --dummy
215 -d
216 --no-dummy
217 Dummy run, do not actually execute anything
218 Can also be set with the following environment variables:
220 "T2_HARNESS_DUMMY"
221 --help
223 -h
224 --no-help
225 exit after showing help information
226 --interactive
228 -i
229 --no-interactive
230 Use interactive mode, 1 test at a time, stdin forwarded to it
231 --keep-dirs
233 --keep_dir
234 -k
235 --no-keep-dirs
236 Do not delete directories when done. This is useful if you want to
237 inspect the directories used for various commands.
238 --procname-prefix ARG
240 --procname-prefix=ARG
241 --no-procname-prefix
242 Add a prefix to all proc names (as seen by ps).
243 Persistent Runner Options
245 --quiet
247 -q
248 --no-quiet
249 Be very quiet.
250 Can be specified multiple times
252 --reload
254 -r
255 --no-reload
256 Attempt to reload modified modules in-place, restarting entire
257 stages only when necessary.
258 --restrict-reload
260 --restrict-reload=path
261 --no-restrict-reload
262 Only reload modules under the specified path, if no path is
263 specified look at anything under the .yath.rc path, or the current
264 working directory.
265 Can be specified multiple times
267 Runner Options
269 --abort-on-bail
271 --no-abort-on-bail
272 Abort all testing if a bail-out is encountered (default: on)
273 --blib
275 -b
276 --no-blib
277 (Default: include if it exists) Include 'blib/lib' and 'blib/arch'
278 in your module path
279 --cover
281 --cover=-silent,1,+ignore,^t/,+ignore,^t2/,+ignore,^xt,+ignore,^test.pl
282 --no-cover
283 Use Devel::Cover to calculate test coverage. This disables forking.
284 If no args are specified the following are used:
285 -silent,1,+ignore,^t/,+ignore,^t2/,+ignore,^xt,+ignore,^test.pl
286 --daemon
288 --no-daemon
289 Start the runner as a daemon (Default: True)
290 --dump-depmap
292 --no-dump-depmap
293 When using staged preload, dump the depmap for each stage as json
294 files
295 --event-timeout SECONDS
297 --et SECONDS
298 --no-event-timeout
299 Kill test if no output is received within timeout period. (Default:
300 60 seconds). Add the "# HARNESS-NO-TIMEOUT" comment to the top of a
301 test file to disable timeouts on a per-test basis. This prevents a
302 hung test from running forever.
303 --include ARG
305 --include=ARG
306 -I ARG
307 -I=ARG
308 --no-include
309 Add a directory to your include paths
310 Can be specified multiple times
312 --job-count 4
314 --job-count 8:2
315 --jobs 4
316 --jobs 8:2
317 -j4
318 -j8:2
319 --no-job-count
320 Set the number of concurrent jobs to run. Add a :# if you also wish
321 to designate multiple slots per test. 8:2 means 8 slots, but each
322 test gets 2 slots, so 4 tests run concurrently. Tests can find
323 their concurrency assignemnt in the "T2_HARNESS_MY_JOB_CONCURRENCY"
324 environment variable.
325 Can also be set with the following environment variables:
327 "YATH_JOB_COUNT", "T2_HARNESS_JOB_COUNT", "HARNESS_JOB_COUNT"
328 --lib
330 -l
331 --no-lib
332 (Default: include if it exists) Include 'lib' in your module path
333 --nytprof
335 --no-nytprof
336 Use Devel::NYTProf on tests. This will set addpid=1 for you. This
337 works with or without fork.
338 --post-exit-timeout SECONDS
340 --pet SECONDS
341 --no-post-exit-timeout
342 Stop waiting post-exit after the timeout period. (Default: 15
343 seconds) Some tests fork and allow the parent to exit before
344 writing all their output. If Test2::Harness detects an incomplete
345 plan after the test exits it will monitor for more events until the
346 timeout period. Add the "# HARNESS-NO-TIMEOUT" comment to the top
347 of a test file to disable timeouts on a per-test basis.
348 --preload-threshold ARG
350 --preload-threshold=ARG
351 --Pt ARG
352 --Pt=ARG
353 -W ARG
354 -W=ARG
355 --no-preload-threshold
356 Only do preload if at least N tests are going to be run. In some
357 cases a full preload takes longer than simply running the tests,
358 this lets you specify a minimum number of test jobs that will be
359 run for preload to happen. This has no effect for a persistent
360 runner. The default is 0, and it means always preload.
361 --preloads ARG
363 --preloads=ARG
364 --preload ARG
365 --preload=ARG
366 -P ARG
367 -P=ARG
368 --no-preloads
369 Preload a module before running tests
370 Can be specified multiple times
372 --resource Port
374 --resource +Test2::Harness::Runner::Resource::Port
375 -R Port
376 --no-resource
377 Use a resource module to assign resource assignments to individual
378 tests
379 Can be specified multiple times
381 --runner-id ARG
383 --runner-id=ARG
384 --no-runner-id
385 Runner ID (usually a generated uuid)
386 --shared-jobs-config .sharedjobslots.yml
388 --shared-jobs-config relative/path/.sharedjobslots.yml
389 --shared-jobs-config /absolute/path/.sharedjobslots.yml
390 --no-shared-jobs-config
391 Where to look for a shared slot config file. If a filename with no
392 path is provided yath will search the current and all parent
393 directories for the name.
394 --slots-per-job 2
396 -x2
397 --no-slots-per-job
398 This sets the number of slots each job will use (default 1). This
399 is normally set by the ':#' in '-j#:#'.
400 Can also be set with the following environment variables:
402 "T2_HARNESS_JOB_CONCURRENCY"
403 --switch ARG
405 --switch=ARG
406 -S ARG
407 -S=ARG
408 --no-switch
409 Pass the specified switch to perl for each test. This is not
410 compatible with preload.
411 Can be specified multiple times
413 --tlib
415 --no-tlib
416 (Default: off) Include 't/lib' in your module path
417 --unsafe-inc
419 --no-unsafe-inc
420 perl is removing '.' from @INC as a security concern. This option
421 keeps things from breaking for now.
422 Can also be set with the following environment variables:
424 "PERL_USE_UNSAFE_INC"
425 --use-fork
427 --fork
428 --no-use-fork
429 (default: on, except on windows) Normally tests are run by forking,
430 which allows for features like preloading. This will turn off the
431 behavior globally (which is not compatible with preloading). This
432 is slower, it is better to tag misbehaving tests with the '#
433 HARNESS-NO-PRELOAD' comment in their header to disable forking only
434 for those tests.
435 Can also be set with the following environment variables:
437 "!T2_NO_FORK", "T2_HARNESS_FORK", "!T2_HARNESS_NO_FORK",
438 "YATH_FORK", "!YATH_NO_FORK"
439 --use-timeout
441 --timeout
442 --no-use-timeout
443 (default: on) Enable/disable timeouts
444 Workspace Options
446 --clear
448 -C
449 --no-clear
450 Clear the work directory if it is not already empty
451 --tmp-dir ARG
453 --tmp-dir=ARG
454 --tmpdir ARG
455 --tmpdir=ARG
456 -t ARG
457 -t=ARG
458 --no-tmp-dir
459 Use a specific temp directory (Default: use system temp dir)
460 Can also be set with the following environment variables:
462 "T2_HARNESS_TEMP_DIR", "YATH_TEMP_DIR", "TMPDIR", "TEMPDIR",
463 "TMP_DIR", "TEMP_DIR"
464 --workdir ARG
466 --workdir=ARG
467 -w ARG
468 -w=ARG
469 --no-workdir
470 Set the work directory (Default: new temp directory)
471 Can also be set with the following environment variables:
473 "T2_WORKDIR", "YATH_WORKDIR"
474 YathUI Options
476 --yathui-api-key ARG
478 --yathui-api-key=ARG
479 --no-yathui-api-key
480 Yath-UI API key. This is not necessary if your Yath-UI instance is
481 set to single-user
482 --yathui-db
484 --no-yathui-db
485 Add the YathUI DB renderer in addition to other renderers
486 --yathui-grace
488 --no-yathui-grace
489 If yath cannot connect to yath-ui it normally throws an error, use
490 this to make it fail gracefully. You get a warning, but things keep
491 going.
492 --yathui-long-duration 10
494 --no-yathui-long-duration
495 Minimum duration length (seconds) before a test goes from MEDIUM to
496 LONG
497 --yathui-medium-duration 5
499 --no-yathui-medium-duration
500 Minimum duration length (seconds) before a test goes from SHORT to
501 MEDIUM
502 --yathui-mode summary
504 --yathui-mode qvf
505 --yathui-mode qvfd
506 --yathui-mode complete
507 --no-yathui-mode
508 Set the upload mode (default 'qvfd')
509 --yathui-only
511 --no-yathui-only
512 Only use the YathUI renderer
513 --yathui-only-db
515 --no-yathui-only-db
516 Only use the YathUI DB renderer
517 --yathui-port 8080
519 --no-yathui-port
520 Port to use when running a local server
521 --yathui-port-command get_port.sh
523 --yathui-port-command get_port.sh --pid $$
524 --no-yathui-port-command
525 Use a command to get a port number. "$$" will be replaced with the
526 PID of the yath process
527 --yathui-project ARG
529 --yathui-project=ARG
530 --no-yathui-project
531 The Yath-UI project for your test results
532 --yathui-render
534 --no-yathui-render
535 Add the YathUI renderer in addition to other renderers
536 --yathui-resources
538 --yathui-resources=5
539 --no-yathui-resources
540 Send resource info (for supported resources) to yathui at the
541 specified interval in seconds (5 if not specified)
542 --yathui-retry
544 --no-yathui-retry
545 How many times to try an operation before giving up
546 Can be specified multiple times
548 --yathui-schema PostgreSQL
550 --yathui-schema MySQL
551 --yathui-schema MySQL56
552 --no-yathui-schema
553 What type of DB/schema to use when using a temporary database
554 --yathui-url http://my-yath-ui.com/...
556 --uri http://my-yath-ui.com/...
557 --no-yathui-url
558 Yath-UI url
559 --yathui-user ARG
561 --yathui-user=ARG
562 --no-yathui-user
563 Username to attach to the data sent to the db
564 --yathui-db-buffering none
566 --yathui-db-buffering job
567 --yathui-db-buffering diag
568 --yathui-db-buffering run
569 --no-yathui-db-buffering
570 Type of buffering to use, if "none" then events are written to the
571 db one at a time, which is SLOW
572 --yathui-db-config ARG
574 --yathui-db-config=ARG
575 --no-yathui-db-config
576 Module that implements 'MODULE->yath_ui_config(%params)' which
577 should return a Test2::Harness::UI::Config instance.
578 --yathui-db-coverage
580 --no-yathui-db-coverage
581 Pull coverage data directly from the database (default: off)
582 --yathui-db-driver Pg
584 --yathui-db-drivermysql
585 --yathui-db-driverMariaDB
586 --no-yathui-db-driver
587 DBI Driver to use
588 --yathui-db-dsn ARG
590 --yathui-db-dsn=ARG
591 --no-yathui-db-dsn
592 DSN to use when connecting to the db
593 --yathui-db-duration-limit ARG
595 --yathui-db-duration-limit=ARG
596 --no-yathui-db-duration-limit
597 Limit the number of runs to look at for durations data (default:
598 10)
599 --yathui-db-durations
601 --no-yathui-db-durations
602 Pull duration data directly from the database (default: off)
603 --yathui-db-flush-interval 2
605 --yathui-db-flush-interval 1.5
606 --no-yathui-db-flush-interval
607 When buffering DB writes, force a flush when an event is recieved
608 at least N seconds after the last flush.
609 --yathui-db-host ARG
611 --yathui-db-host=ARG
612 --no-yathui-db-host
613 hostname to use when connecting to the db
614 --yathui-db-name ARG
616 --yathui-db-name=ARG
617 --no-yathui-db-name
618 Name of the database to use for yathui
619 --yathui-db-pass ARG
621 --yathui-db-pass=ARG
622 --no-yathui-db-pass
623 Password to use when connecting to the db
624 --yathui-db-port ARG
626 --yathui-db-port=ARG
627 --no-yathui-db-port
628 port to use when connecting to the db
629 --yathui-db-publisher ARG
631 --yathui-db-publisher=ARG
632 --no-yathui-db-publisher
633 When using coverage or duration data, only use data uploaded by
634 this user
635 --yathui-db-socket ARG
637 --yathui-db-socket=ARG
638 --no-yathui-db-socket
639 socket to use when connecting to the db
640 --yathui-db-user ARG
642 --yathui-db-user=ARG
643 --no-yathui-db-user
644 Username to use when connecting to the db
645
647 The source code repository for Test2-Harness can be found at
648 http://github.com/Test-More/Test2-Harness/.
649
651 Chad Granum <exodist@cpan.org>
652
654 Chad Granum <exodist@cpan.org>
655
657 Copyright 2023 Chad Granum <exodist7@gmail.com>.
658 This program is free software; you can redistribute it and/or modify it
660 under the same terms as Perl itself.
661 See http://dev.perl.org/licenses/
663perl v5.36.1 2023-10-04 App::Yath::Command::start(3)