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

NAME

6       Test2::Harness::Finder - Library that searches for test files
7

DESCRIPTION

9       The finder is responsible for locating test files that should be run.
10       You can subclass the finder and instruct yath to use your subclass.
11

SYNOPSIS

13   USING A CUSTOM FINDER
14       To use Test2::Harness::Finder::MyFinder:
15
16           $ yath test --finder MyFinder
17
18       To use Another::Finder
19
20           $ yath test --finder +Another::Finder
21
22       By default "Test2::Harness::Finder::" is prefixed onto your custom
23       finder, use '+' before the class name or prevent this.
24
25   SUBCLASSING
26           use parent 'Test2::Harness::Finder';
27           use Test2::Harness::TestFile;
28
29           # Custom finders may provide their own options if desired.
30           # This is optional.
31           use App::Yath::Options;
32           option foo => (
33               ...
34           );
35
36           # This is the main method to override.
37           sub find_project_files {
38               my $self = shift;
39               my ($plugins, $settings, $search) = @_;
40
41               return [
42                   Test2::Harness::TestFile->new(...),
43                   Test2::Harness::TestFile->new(...),
44                   ...,
45               ];
46           }
47

METHODS

49       These are important state methods, as well as utility methods for use
50       in your subclasses.
51
52       $bool = $finder->multi_project
53           True if the "yath projects" command was used.
54
55       $arrayref = $finder->find_files($plugins, $settings)
56           This is the main method. This method returns an arrayref of
57           Test2::Harness::TestFile instances, each one representing a single
58           test to run.
59
60           $plugins is a list of plugins, some may be class names, others may
61           be instances.
62
63           $settings is an Test2::Harness::Settings instance.
64
65           Note: In many cases it is better to override "find_project_files()"
66           in your subclasses.
67
68       $durations = $finder->duration_data
69           This will fetch the durations data if any was provided. This is a
70           hashref of relative test paths as keys where the value is the
71           duration of the file (SHORT, MEDIUM or LONG).
72
73           Note: The result is cached, see pull_durations() to refresh the
74           data.
75
76       @reasons = $finder->exclude_file($test)
77           The input argument should be an Test2::Harness::Test instance. This
78           will return a list of human readible reasons a test file should be
79           excluded. If the file should not be excluded the list will be
80           empty.
81
82           This is a utility method that verifies the file is not in an
83           exclude list/pattern. The reasons are provided back in case you
84           need to inform the user.
85
86       $bool = $finder->include_file($test)
87           The input argument should be an Test2::Harness::Test instance. This
88           is a convenience method around "exclude_file()", it will return
89           true when "exclude_file()" returns an empty list.
90
91       $arrayref = $finder->find_multi_project_files($plugins, $settings)
92       $arrayref = $finder->find_project_files($plugins, $settings, $search)
93           These do the heavy lifting for "find_files"
94
95           The default "find_files()" implementation is this:
96
97               sub find_files {
98                   my $self = shift;
99                   my ($plugins, $settings) = @_;
100
101                   return $self->find_multi_project_files($plugins, $settings) if $self->multi_project;
102                   return $self->find_project_files($plugins, $settings, $self->search);
103               }
104
105           Each one returns an arrayref of Test2::Harness::TestFile instances.
106
107           Note that "find_multi_project_files()" uses "find_project_files()"
108           internall, once per project directory.
109
110           $plugins is a list of plugins, some may be class names, others may
111           be instances.
112
113           $settings is an Test2::Harness::Settings instance.
114
115           $search is an arrayref of search paths.
116
117       $finder->munge_settings($settings, $options)
118           A callback that lets you munge settings and options.
119
120       $finder->pull_durations
121           This will fetch the durations data if ant was provided. This is a
122           hashref of relative test paths as keys where the value is the
123           duration of the file (SHORT, MEDIUM or LONG).
124
125           duration_data() is a cached version of this. This method will
126           refresh the cache for the other.
127
128   FROM SETTINGS
129       See App::Yath::Options::Finder for up to date documentation on these.
130
131       $finder->default_search
132       $finder->default_at_search
133       $finder->durations
134       $finder->maybe_durations
135       $finder->exclude_files
136       $finder->exclude_patterns
137       $finder->no_long
138       $finder->only_long
139       $finder->search
140       $finder->extensions
141

SOURCE

143       The source code repository for Test2-Harness can be found at
144       http://github.com/Test-More/Test2-Harness/.
145

MAINTAINERS

147       Chad Granum <exodist@cpan.org>
148

AUTHORS

150       Chad Granum <exodist@cpan.org>
151

COPYRIGHT

153       Copyright 2020 Chad Granum <exodist7@gmail.com>.
154
155       This program is free software; you can redistribute it and/or modify it
156       under the same terms as Perl itself.
157
158       See http://dev.perl.org/licenses/
159
160
161
162perl v5.34.1                      2022-07-11         Test2::Harness::Finder(3)