1Test2::Harness::Plugin(U3s)er Contributed Perl DocumentatTieosnt2::Harness::Plugin(3)
2
3
4

NAME

6       Test2::Harness::Plugin - Base class for Test2::Harness plugins.
7

DESCRIPTION

9       This class holds the methods specific to Test2::Harness which is the
10       backend. Most of the time you actually want to subclass
11       App::Yath::Plugin which subclasses this class, and holds additional
12       methods that apply to yath (the UI layer).
13

SYNOPSIS

15       You probably want to subclass App::Yath::Plugin instead. This class
16       here mainly exists to separate concerns, but is not something you
17       should use directly.
18
19           package Test2::Harness::Plugin::MyPlugin;
20
21           use parent 'Test2::Harness::Plugin';
22
23           # ... Define methods
24
25           1;
26

METHODS

28       $plugin->munge_search($input, $default_search, $settings)
29           $input is an arrayref of files and/or directories provided at the
30           command line.
31
32           $default_search is an arrayref with the default files/directories
33           pulled in when nothing is specified at the command ine.
34
35           $settings is an instance of Test2::Harness::Settings
36
37       $undef_or_inst = $plugin->claim_file($path, $settings)
38           This is a chance for a plugin to claim a test file early, before
39           Test2::Harness takes care of it. If your plugin does not want to
40           claim the file just return undef. To claim the file return an
41           instance of Test2::Harness::TestFile created with $path.
42
43       $plugin->munge_files(\@tests, $settings)
44           This is an opportunity for your plugin to modify the data for any
45           test file that will be run. The first argument is an arrayref of
46           Test2::Harness::TestFile objects.
47
48       $hashref = $plugin->duration_data($settings, $test_names)
49           If defined, this can return a hashref of duration data. This should
50           return undef if no duration data is provided. The first plugin
51           listed that provides duration data wins, no other plugins will be
52           checked once duration data is obtained.
53
54           Example duration data:
55
56               {
57                   't/foo.t' => 'medium',
58                   't/bar.t' => 'short',
59                   't/baz.t' => 'long',
60               }
61
62       $hashref_or_arrayref = $plugin->coverage_data(\@changed)
63       $hashref_or_arrayref = $plugin->coverage_data()
64           If defined, this can return a hashref of all coverage data, or an
65           arrayref of tests that cover the tests listed in @changed. This
66           should return undef if no coverage data is available. The first
67           plugin to provide coverage data wins, no other plugins will be
68           checked once coverage data has been obtained.
69
70           Examples:
71
72               [
73                   'foo.t',
74                   'bar.t',
75                   'baz.t',
76               ]
77
78               {
79                   'lib/Foo.pm' => [
80                       't/foo.t',
81                       't/integration.t',
82                   ],
83                   'lib/Bar.pm' => [
84                       't/bar.t',
85                       't/integration.t',
86                   ],
87               }
88
89       $plugin->post_process_coverage_tests($settings, \@tests)
90           This is an opportunity for a plugin to do post-processing on the
91           list of coverage tests to run. This is mainly useful to remove
92           duplicates if multiple plugins add coverage data, or merging
93           entries where applicable. This will be called after all plugins
94           have generated their coverage test list.
95
96           Plugins may implement this without implementing coverage_data(),
97           making this useful if you want to use a pre-existing coverage
98           module and want to do post-processing on what it provides.
99
100       $plugin->inject_run_data(meta => $meta, fields => $fields, run => $run)
101           This is a callback that lets your plugin add meta-data or custom
102           fields to the run event. The meta-data and fields are available in
103           the event log, and are particularily useful to App::Yath::UI.
104
105               sub inject_run_data {
106                   my $class  = shift;
107                   my %params = @_;
108
109                   my $meta   = $params{meta};
110                   my $fields = $params{fields};
111
112                   # Meta-data is a hash, each plugin should define its own key, and put
113                   # data under that key
114                   $meta->{MyPlugin}->{stuff} = "Stuff!";
115
116                   # Fields is an array of fields that a UI might want to display when showing the run.
117                   push @$fields => {name => 'MyPlugin', details => "Human Friendly Stuff", raw => "Less human friendly stuff", data => $all_the_stuff};
118
119                   return;
120               }
121
122       $plugin->setup($settings)
123           This is a callback that lets you run setup logic when the runner
124           starts. Note that in a persistent runner this is run once on
125           startup, it is not run for each "run" command against the
126           persistent runner.
127
128       $plugin->teardown($settings)
129           This is a callback that lets you run teardown logic when the runner
130           stops. Note that in a persistent runner this is run once on
131           termination, it is not run for each "run" command against the
132           persistent runner.
133
134       @files = $plugin->changed_files($settings)
135           Get a list of files that have changed. Plugins are free to define
136           what "changed" means. This may be used by the finder to determine
137           what tests to run based on coverage data collected in previous
138           runs.
139
140           Note that data from all changed_files() calls from all plugins will
141           be merged.
142
143       ($type, $value) = $plugin->changed_diff($settings)
144           Generate a diff that can be used to calculate changed files/subs
145           for which to run tests. Unlike changed_files(), only 1 diff will be
146           used, first plugin listed that returns one wins. This is not run at
147           all if a diff is provided via --changed-diff.
148
149           Diffs must be in the same format as this git command:
150
151               git diff -U1000000 -W --minimal BASE_BRANCH_OR_COMMIT
152
153           Some other diff formats may work by chance, but they are not
154           dirfectly supported. In the future other diff formats may be
155           directly supported, but not yet.
156
157           The following return sets are allowed:
158
159           file => string
160               Path to a diff file
161
162           diff => string
163               In memory diff as a single string
164
165           lines => \@lines
166               Diff where each line is a seperate string in an arrayref.
167
168           line_sub => sub { ... }
169               Sub that returns one line per call and undef when there are no
170               more lines
171
172           handle => $FH
173               A filehandle to the diff
174
175       $exit = $plugin->shellcall($settings, $name, $cmd)
176       $exit = $plugin->shellcall($settings, $name, @cmd)
177           This is essentially the same as system() except that STDERR and
178           STDOUT are redirected to files that the yath collector will pick up
179           so that any output from the command will be seen as events and will
180           be part of the yath log. If no workspace is available this will not
181           redirect IO and it will be identical to calling system().
182
183           This is particularily useful in setup() and teardown() when running
184           external commands, specially any that daemonize and continue to
185           produce output after the setup/teardown method has completed.
186
187           $name is required because it will be used for filenames, and will
188           be used as the output tag (best to limit it to 8 characters).
189
190       $plugin->redirect_io($settings, $name)
191           WARNING: This must NEVER be called in a primary yath process. Only
192           use this in forked processes that you control. If this is used in a
193           main process it could hide ALL output.
194
195           This will redirect STDERR and STDOUT to files that will be picked
196           up by the yath collector so that any output appears as proper yath
197           events and will be included in the yath log.
198
199           $name is required because it will be used for filenames, and will
200           be used as the output tag (best to limit it to 8 characters).
201
202       $plugin->TO_JSON
203           This is here as a bare minimum serialization method. It returns the
204           plugin class name.
205

SOURCE

207       The source code repository for Test2-Harness can be found at
208       http://github.com/Test-More/Test2-Harness/.
209

MAINTAINERS

211       Chad Granum <exodist@cpan.org>
212

AUTHORS

214       Chad Granum <exodist@cpan.org>
215
217       Copyright 2020 Chad Granum <exodist7@gmail.com>.
218
219       This program is free software; you can redistribute it and/or modify it
220       under the same terms as Perl itself.
221
222       See http://dev.perl.org/licenses/
223
224
225
226perl v5.36.1                      2023-10-04         Test2::Harness::Plugin(3)
Impressum