1Test2::Harness::Plugin(U3s)er Contributed Perl DocumentatTieosnt2::Harness::Plugin(3)
2
6 Test2::Harness::Plugin - Base class for Test2::Harness plugins.
7
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
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 package Test2::Harness::Plugin::MyPlugin;
20 use parent 'Test2::Harness::Plugin';
22 # ... Define methods
24 1;
26
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 $default_search is an arrayref with the default files/directories
33 pulled in when nothing is specified at the command ine.
34 $settings is an instance of Test2::Harness::Settings
36 $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 $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 $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 Example duration data:
55 {
57 't/foo.t' => 'medium',
58 't/bar.t' => 'short',
59 't/baz.t' => 'long',
60 }
61 $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 Examples:
71 [
73 'foo.t',
74 'bar.t',
75 'baz.t',
76 ]
77 {
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 $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 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 $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 sub inject_run_data {
106 my $class = shift;
107 my %params = @_;
108 my $meta = $params{meta};
110 my $fields = $params{fields};
111 # 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 # 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 return;
120 }
121 $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 $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 @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 Note that data from all changed_files() calls from all plugins will
141 be merged.
142 ($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 Diffs must be in the same format as this git command:
150 git diff -U1000000 -W --minimal BASE_BRANCH_OR_COMMIT
152 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 The following return sets are allowed:
158 file => string
160 Path to a diff file
161 diff => string
163 In memory diff as a single string
164 lines => \@lines
166 Diff where each line is a seperate string in an arrayref.
167 line_sub => sub { ... }
169 Sub that returns one line per call and undef when there are no
170 more lines
171 handle => $FH
173 A filehandle to the diff
174 $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 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 $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 $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 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 $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 $plugin->TO_JSON
203 This is here as a bare minimum serialization method. It returns the
204 plugin class name.
205
207 The source code repository for Test2-Harness can be found at
208 http://github.com/Test-More/Test2-Harness/.
209
211 Chad Granum <exodist@cpan.org>
212
214 Chad Granum <exodist@cpan.org>
215
217 Copyright 2020 Chad Granum <exodist7@gmail.com>.
218 This program is free software; you can redistribute it and/or modify it
220 under the same terms as Perl itself.
221 See http://dev.perl.org/licenses/
223perl v5.38.0 2023-10-04 Test2::Harness::Plugin(3)