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

NAME

6       App::Yath::Tester - Tools for testing yath
7

DESCRIPTION

9       This package provides utilities for running yath from within tests to
10       verify its behavior. This is primarily used for integration testing of
11       yath and for third party components.
12

SYNOPSIS

14           use App::Yath::Tester qw/yath/;
15
16           my $result = yath(
17               # Command and arguments
18               command => 'test',
19               args    => ['-pMyPlugin', 'path/to/test', ...],
20
21               # Exit code we expect from yath
22               exit => 0,
23
24               # Subtest to verify results
25               test => sub {
26                   my $result = shift;
27
28                   # Redundant since we have the exit check above
29                   is($result->{exit}, 0, "Verify exit");
30
31                   is($result->{output}, $expected_output, "Got the expected output from yath");
32               },
33           );
34

EXPORTS

36       There are 2 exports from this module.
37
38   $result = yath(...)
39           my $result = yath(
40               # Command and arguments
41               command => 'test',
42               args    => ['-pMyPlugin', 'path/to/test', ...],
43
44               # Exit code we expect from yath
45               exit => 0,
46
47               # Subtest to verify results
48               test => sub {
49                   my $result = shift;
50
51                   # Redundant since we have the exit check above
52                   is($result->{exit}, 0, "Verify exit");
53
54                   is($result->{output}, $expected_output, "Got the expected output from yath");
55               },
56           );
57
58       ARGUMENTS
59
60       cmd => $command
61       command => $command
62           Either 'cmd' or 'command' can be used. This argument takes a string
63           that should be a command name.
64
65       cli => \@ARGS
66       args => \@ARGS
67           Either 'cli' or 'args' can be used. If none are provided an empty
68           arrayref is used. This argument takes an arrayref of arguments to
69           the yath command.
70
71               $ yath [PRE_COMMAND] [COMMAND] [ARGS]
72
73       pre => \@ARGS
74       pre_command => \@ARGS
75           Either 'pre' or 'pre_command' can be used. An empty arrayref is
76           used if none are provided. These are arguments provided to yath
77           BEFORE the command on the command line.
78
79               $ yath [PRE_COMMAND] [COMMAND] [ARGS]
80
81       env => \%ENV
82           Provide custom environment variable values to set before running
83           the yath command.
84
85       encoding => $encoding_name
86           If you expect your yath command's output to be in a specific
87           encoding you can specify it here to make sure the
88           "$result->{output}" text has been read properly.
89
90       test => sub { ... }
91       tests => sub { ... }
92       subtest => sub { ... }
93           These 3 arguments are all aliases for the same thing, only one
94           should be used.  The codeblock will be called with $result as the
95           onyl argument. The codeblock will be run as a subtest. If you
96           specify the 'exit' argument that check will also happen in the same
97           subtest.
98
99               test => sub {
100                   my $result = shift;
101
102                   ... verify result ...
103               },
104
105       exit => $integer
106           Verify that the yath command exited with the specified exit code.
107           This check will be run in a subtest. If you specify a custom
108           subtest then this check will appear to come from that subtest.
109
110       debug => $integer
111           Output debug info in realtime, depending on the $integer value this
112           may include the output from the yath command being run.
113
114               0 - No debugging
115               1 - Output the command and other action being taken by the tool
116               2 - Echo yath output as it happens
117
118       inc => $bool
119           This defaults to true.
120
121           When true the tool will look for a directory next to your test file
122           with an identical name except that '.t' or '.t2' will be stripped
123           from it. If that directory exists it will be added as a dev-lib to
124           the yath command.
125
126           If your test file is 't/foo/bar.t' then your yath command will look
127           like this:
128
129               $ yath -D=t/foo/bar [PRE-COMMAND] [COMMAND] [ARGS]
130
131       capture => $bool
132           Defaults to true.
133
134           When true the yath output will be captured and put into
135           "$result->{output}".
136
137       log => $bool
138           Defaults to false.
139
140           When true yath will be instructed to produce a log, the log will be
141           accessible via "$result->{log}". "$result->{log}" will be an
142           instance of Test2::Harness::Util::File::JSONL.
143
144       no_app_path => $bool
145           Default to false.
146
147           Normally "-D=/path/to/lib" is added to the yath command where
148           '/path/to/lib' is the path the the lib dir App::Yath was loaded
149           from.  This normally insures the correct version of yath libraries
150           is loaded.
151
152           When this argument is set to true the path is not added.
153
154       lib => [...]
155           This poorly named argument allows you to inject command line
156           argumentes between "perl" and "yath" in the command.
157
158               perl [LIB] path/to/yath [PRE-COMMAND] [COMMAND] [ARGS]
159
160       RESULT
161
162       The result hashref may containt he following fields depending on the
163       arguments passed into yath().
164
165       exit => $integer
166           Exit value returned from yath.
167
168       output => $string
169           The output produced by the yath command.
170
171       log => $jsonl_object
172           An instance of Test2::Harness::Util::File::JSONL opened from the
173           log file produced by the yath command.
174
175           Note: By default no logging is done, you must specify the "log =>
176           1" argument to enable it.
177
178   $path = make_example_dir()
179       This will create a temporary directory with 't', 't2', and 'xt'
180       subdirectories each of which will contain a single passing test.
181

SOURCE

183       The source code repository for Test2-Harness can be found at
184       http://github.com/Test-More/Test2-Harness/.
185

MAINTAINERS

187       Chad Granum <exodist@cpan.org>
188

AUTHORS

190       Chad Granum <exodist@cpan.org>
191
193       Copyright 2020 Chad Granum <exodist7@gmail.com>.
194
195       This program is free software; you can redistribute it and/or modify it
196       under the same terms as Perl itself.
197
198       See http://dev.perl.org/licenses/
199
200
201
202perl v5.38.0                      2023-10-04              App::Yath::Tester(3)
Impressum