1App::Yath(3)          User Contributed Perl Documentation         App::Yath(3)
2
3
4

NAME

6       App::Yath - Yet Another Test Harness (Test2-Harness) Command Line
7       Interface (CLI)
8

DESCRIPTION

10       PLEASE NOTE: Test2::Harness is still experimental, it can all change at
11       any time. Documentation and tests have not been written yet!
12
13       This is the primary documentation for "yath", App::Yath,
14       Test2::Harness.
15
16       The canonical source of up-to-date command options are the help output
17       when using "$ yath help" and "$ yath help COMMAND".
18
19       This document is mainly an overview of "yath" usage and common recipes.
20

OVERVIEW

22       To use Test2::Harness, you use the "yath" command. Yath will find the
23       tests (or use the ones you specify) and run them. As it runs, it will
24       output diagnostic information such as failures. At the end, yath will
25       print a summary of the test run.
26
27       "yath" can be thought of as a more powerful alternative to "prove"
28       (Test::Harness)
29

RECIPES

31       These are common recipes for using "yath".
32
33   RUN PROJECT TESTS
34           $ yath
35
36       Simply running yath with no arguments means "Run all tests for the
37       current project". Yath will look for tests in "./t", "./t2", and
38       "./test.pl" and run any which are found.
39
40       Normally this implies the "test" command but will instead imply the
41       "run" command if a persistent test runner is detected.
42
43   PRELOAD MODULES
44       Yath has the ability to preload modules. Yath normally forks to start
45       new tests, so preloading can reduce the time spent loading modules over
46       and over in each test.
47
48       Note that some tests may depend on certain modules not being loaded. In
49       these cases you can add the "# HARNESS-NO-PRELOAD" directive to the top
50       of the test files that cannot use preload.
51
52       SIMPLE PRELOAD
53
54       Any module can be preloaded:
55
56           $ yath -PMoose
57
58       You can preload as many modules as you want:
59
60           $ yath -PList::Util -PScalar::Util
61
62       COMPLEX PRELOAD
63
64       If your preload is a subclass of Test2::Harness::Preload then more
65       complex preload behavior is possible. See those docs for more info.
66
67   LOGGING
68       RECORDING A LOG
69
70       You can turn on logging with a flag. The filename of the log will be
71       printed at the end.
72
73           $ yath -L
74           ...
75           Wrote log file: test-logs/2017-09-12~22:44:34~1505281474~25709.jsonl
76
77       The event log can be quite large. It can be compressed with bzip2.
78
79           $ yath -B
80           ...
81           Wrote log file: test-logs/2017-09-12~22:44:34~1505281474~25709.jsonl.bz2
82
83       gzip compression is also supported.
84
85           $ yath -G
86           ...
87           Wrote log file: test-logs/2017-09-12~22:44:34~1505281474~25709.jsonl.gz
88
89       "-B" and "-G" both imply "-L".
90
91       REPLAYING FROM A LOG
92
93       You can replay a test run from a log file:
94
95           $ yath test-logs/2017-09-12~22:44:34~1505281474~25709.jsonl.bz2
96
97       This will be significantly faster than the initial run as no tests are
98       actually being executed. All events are simply read from the log, and
99       processed by the harness.
100
101       You can change display options and limit rendering/processing to
102       specific test jobs from the run:
103
104           $ yath test-logs/2017-09-12~22:44:34~1505281474~25709.jsonl.bz2 -v 5 10
105
106       Note: This is done using the "$ yath replay ..." command. The "replay"
107       command is implied if the first argument is a log file.
108
109   PER-TEST TIMING DATA
110       The "-T" option will cause each test file to report how long it took to
111       run.
112
113           $ yath -T
114
115           ( PASSED )  job  1    t/App/Yath.t
116           (  TIME  )  job  1    0.06942s on wallclock (0.07 usr 0.01 sys + 0.00 cusr 0.00 csys = 0.08 CPU)
117
118   PERSISTENT RUNNER
119       yath supports starting a yath session that waits for tests to run. This
120       is very useful when combined with preload.
121
122       STARTING
123
124       This starts the server. Many options available to the 'test' command
125       will work here but not all. See "$ yath help start" for more info.
126
127           $ yath start
128
129       RUNNING
130
131       This will run tests using the persistent runner. By default, it will
132       search for tests just like the 'test' command. Many options available
133       to the "test" command will work for this as well. See "$ yath help run"
134       for more details.
135
136           $ yath run
137
138       STOPPING
139
140       Stopping a persistent runner is easy.
141
142           $ yath stop
143
144       INFORMATIONAL
145
146       The "which" command will tell you which persistent runner will be used.
147       Yath searches for the persistent runner in the current directory, then
148       searches in parent directories until it either hits the root directory,
149       or finds the persistent runner tracking file.
150
151           $ yath which
152
153       The "watch" command will tail the runner's log files.
154
155           $ yath watch
156
157       PRELOAD + PERSISTENT RUNNER
158
159       You can use preloads with the "yath start" command. In this case, yath
160       will track all the modules pulled in during preload. If any of them
161       change, the server will reload itself to bring in the changes. Further,
162       modified modules will be blacklisted so that they are not preloaded on
163       subsequent reloads. This behavior is useful if you are actively working
164       on a module that is normally preloaded.
165
166   MAKING YOUR PROJECT ALWAYS USE YATH
167           $ yath init
168
169       The above command will create "test.pl". "test.pl" is automatically run
170       by most build utils, in which case only the exit value matters. The
171       generated "test.pl" will run "yath" and execute all tests in the "./t"
172       and/or "./t2" directories. Tests in "./t" will ALSO be run by prove but
173       tests in "./t2" will only be run by yath.
174
175   PROJECT-SPECIFIC YATH CONFIG
176       You can write a ".yath.rc" file. The file format is very simple. Create
177       a "[COMMAND]" section to start the configuration for a command and then
178       provide any options normally allowed by it. When "yath" is run inside
179       your project, it will use the config specified in the rc file, unless
180       overridden by command line options.
181
182       Comments start with a semi-colon.
183
184       Example .yath.rc:
185
186           [test]
187           -B ;Always write a bzip2-compressed log
188
189           [start]
190           -PMoose ;Always preload Moose with a persistent runner
191
192       This file is normally committed into the project's repo.
193
194   PROJECT-SPECIFIC YATH CONFIG USER OVERRIDES
195       You can add a ".yath.user.rc" file. Format is the same as the regular
196       ".yath.rc" file. This file will be read in addition to the regular
197       config file. Directives in this file will come AFTER the directives in
198       the primary config so it may be used to override config.
199
200       This file should not normally be committed to the project repo.
201
202   HARNESS DIRECTIVES INSIDE TESTS
203       "yath" will recognise a number of directive comments placed near the
204       top of test files. These directives should be placed after the "#!"
205       line but before any real code.
206
207       Real code is defined as any line that does not start with use, require,
208       BEGIN, package, or #
209
210       good example 1
211               #!/usr/bin/perl
212               # HARNESS-NO-FORK
213
214               ...
215
216       good example 2
217               #!/usr/bin/perl
218               use strict;
219               use warnings;
220
221               # HARNESS-NO-FORK
222
223               ...
224
225       bad example 1
226               #!/usr/bin/perl
227
228               # blah
229
230               # HARNESS-NO-FORK
231
232               ...
233
234       bad example 2
235               #!/usr/bin/perl
236
237               print "hi\n";
238
239               # HARNESS-NO-FORK
240
241               ...
242
243       HARNESS-NO-PRELOAD
244
245           #!/usr/bin/perl
246           # HARNESS-NO-PRELOAD
247
248       Use this if your test will fail when modules are preloaded. This will
249       tell yath to start a new perl process to run the script instead of
250       forking with preloaded modules.
251
252       Currently this implies HARNESS-NO-FORK, but that may not always be the
253       case.
254
255       HARNESS-NO-FORK
256
257           #!/usr/bin/perl
258           # HARNESS-NO-FORK
259
260       Use this if your test file cannot run in a forked process, but instead
261       must be run directly with a new perl process.
262
263       This implies HARNESS-NO-PRELOAD.
264
265       HARNESS-NO-STREAM
266
267       "yath" usually uses the Test2::Formatter::Stream formatter instead of
268       TAP.  Some tests depend on using a TAP formatter. This option will make
269       "yath" use Test2::Formatter::TAP or Test::Builder::Formatter.
270
271       HARNESS-NO-TIMEOUT
272
273       "yath" will usually kill a test if no events occur within a timeout
274       (default 60 seconds). You can add this directive to tests that are
275       expected to trip the timeout, but should be allowed to continue.
276
277       NOTE: you usually are doing the wrong thing if you need to set this.
278       See: "HARNESS-TIMEOUT-EVENT".
279
280       HARNESS-TIMEOUT-EVENT 60
281
282       "yath" can be told to alter the default event timeout from 60 seconds
283       to another value. This is the recommended alternative to HARNESS-NO-
284       TIMEOUT
285
286       HARNESS-TIMEOUT-POSTEXIT 15
287
288       "yath" can be told to alter the default POSTEXIT timeout from 15
289       seconds to another value.
290
291       Sometimes a test will fork producing output in the child while the
292       parent is allowed to exit. In these cases we cannot rely on the
293       original process exit to tell us when a test is complete. In cases
294       where we have an exit, and partial output (assertions with no final
295       plan, or a plan that has not been completed) we wait for a timeout
296       period to see if any additional events come into
297
298       HARNESS-DURATION-LONG
299
300       This lets you tell "yath" that the test file is long-running. This is
301       primarily used when concurrency is turned on in order to run longer
302       tests earlier, and concurrently with shorter ones. There is also a
303       "yath" option to skip all long tests.
304
305       This duration is set automatically if HARNESS-NO-TIMEOUT is set.
306
307       HARNESS-DURATION-MEDIUM
308
309       This lets you tell "yath" that the test is medium.
310
311       This is the default duration.
312
313       HARNESS-DURATION-SHORT
314
315       This lets you tell "yath" That the test is short.
316
317       HARNESS-CATEGORY-ISOLATION
318
319       This lets you tell "yath" that the test cannot be run concurrently with
320       other tests. Yath will hold off and run these tests one at a time after
321       all other tests.
322
323       HARNESS-CATEGORY-IMMISCIBLE
324
325       This lets you tell "yath" that the test cannot be run concurrently with
326       other tests of this class. This is helpful when you have multiple tests
327       which would otherwise have to be run sequentially at the end of the
328       run.
329
330       Yath prioritizes running these tests above HARNESS-CATEGORY-LONG.
331
332       HARNESS-CATEGORY-GENERAL
333
334       This is the default category.
335
336       HARNESS-CONFLICTS-XXX
337
338       This lets you tell "yath" that no other test of type XXX can be run at
339       the same time as this one. You are able to set multiple conflict types
340       and "yath" will honor them.
341
342       XXX can be replaced with any type of your choosing.
343
344       NOTE: This directive does not alter the category of your test. You are
345       free to mark the test with LONG or MEDIUM in addition to this marker.
346
347       Example with multiple lines.
348               #!/usr/bin/perl
349               # DASH and space are split the same way.
350               # HARNESS-CONFLICTS-DAEMON
351               # HARNESS-CONFLICTS  MYSQL
352
353               ...
354
355       Or on a single line.
356               #!/usr/bin/perl
357               # HARNESS-CONFLICTS DAEMON MYSQL
358
359               ...
360

MODULE DOCS

362       This section documents the App::Yath module itself.
363
364   SYNOPSIS
365       This is the entire "yath" script, comments removed.
366
367           #!/usr/bin/env perl
368           use App::Yath(\@ARGV, \$App::Yath::RUN);
369           exit($App::Yath::RUN->());
370
371   METHODS
372       $class->import(\@argv, \$runref)
373           This will find, load, and process the command as found via @argv
374           processing.  It will set $runref to a coderef that should be
375           executed at runtime (IE not in the "BEGIN" block implied by "use".
376
377           Please note that statements after the import may never be reached.
378           A source filter may be used to rewrite the rest of the file to be
379           the source of a running test.
380
381       $class->info("Message")
382           Print a message to STDOUT.
383
384       $class->run_command($cmd_class, $cmd_name, \@argv)
385           Run a command identified by $cmd_class and $cmd_name, using
386           "\@argv" as input.
387
388       $cmd_name = $class->parse_argv(\@argv)
389           Determine what command should be used based on "\@argv". "\@argv"
390           may be modified depending on what it contains.
391
392       $cmd_class = $class->load_command($cmd_name)
393           Load a command by name, returns the class of the command.
394

SOURCE

396       The source code repository for Test2-Harness can be found at
397       http://github.com/Test-More/Test2-Harness/.
398

MAINTAINERS

400       Chad Granum <exodist@cpan.org>
401

AUTHORS

403       Chad Granum <exodist@cpan.org>
404

COPYRIGHT

406       Copyright 2019 Chad Granum <exodist7@gmail.com>.
407
408       This program is free software; you can redistribute it and/or modify it
409       under the same terms as Perl itself.
410
411       See http://dev.perl.org/licenses/
412
413
414
415perl v5.30.1                      2020-01-30                      App::Yath(3)