.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Test2::Harness::Finder 3pm"
.TH Test2::Harness::Finder 3pm "2023-03-12" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test2::Harness::Finder \- Library that searches for test files
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The finder is responsible for locating test files that should be run. You can
subclass the finder and instruct yath to use your subclass.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SS "\s-1USING A CUSTOM FINDER\s0"
.IX Subsection "USING A CUSTOM FINDER"
To use Test2::Harness::Finder::MyFinder:
.PP
.Vb 1
\&    $ yath test \-\-finder MyFinder
.Ve
.PP
To use Another::Finder
.PP
.Vb 1
\&    $ yath test \-\-finder +Another::Finder
.Ve
.PP
By default \f(CW\*(C`Test2::Harness::Finder::\*(C'\fR is prefixed onto your custom finder, use
\&'+' before the class name or prevent this.
.SS "\s-1SUBCLASSING\s0"
.IX Subsection "SUBCLASSING"
.Vb 2
\&    use parent \*(AqTest2::Harness::Finder\*(Aq;
\&    use Test2::Harness::TestFile;
\&
\&    # Custom finders may provide their own options if desired.
\&    # This is optional.
\&    use App::Yath::Options;
\&    option foo => (
\&        ...
\&    );
\&
\&    # This is the main method to override.
\&    sub find_project_files {
\&        my $self = shift;
\&        my ($plugins, $settings, $search) = @_;
\&
\&        return [
\&            Test2::Harness::TestFile\->new(...),
\&            Test2::Harness::TestFile\->new(...),
\&            ...,
\&        ];
\&    }
.Ve
.SH "METHODS"
.IX Header "METHODS"
These are important state methods, as well as utility methods for use in your
subclasses.
.ie n .IP "$bool = $finder\->multi_project" 4
.el .IP "\f(CW$bool\fR = \f(CW$finder\fR\->multi_project" 4
.IX Item "$bool = $finder->multi_project"
True if the \f(CW\*(C`yath projects\*(C'\fR command was used.
.ie n .IP "$arrayref = $finder\->find_files($plugins, $settings)" 4
.el .IP "\f(CW$arrayref\fR = \f(CW$finder\fR\->find_files($plugins, \f(CW$settings\fR)" 4
.IX Item "$arrayref = $finder->find_files($plugins, $settings)"
This is the main method. This method returns an arrayref of
Test2::Harness::TestFile instances, each one representing a single test to
run.
.Sp
\&\f(CW$plugins\fR is a list of plugins, some may be class names, others may be
instances.
.Sp
\&\f(CW$settings\fR is an Test2::Harness::Settings instance.
.Sp
\&\fBNote:\fR In many cases it is better to override \f(CW\*(C`find_project_files()\*(C'\fR in your
subclasses.
.ie n .IP "$durations = $finder\->duration_data" 4
.el .IP "\f(CW$durations\fR = \f(CW$finder\fR\->duration_data" 4
.IX Item "$durations = $finder->duration_data"
This will fetch the durations data if any was provided. This is a hashref of
relative test paths as keys where the value is the duration of the file (\s-1SHORT,
MEDIUM\s0 or \s-1LONG\s0).
.Sp
\&\fBNote:\fR The result is cached, see \fBpull_durations()\fR to refresh the data.
.ie n .IP "@reasons = $finder\->exclude_file($test)" 4
.el .IP "\f(CW@reasons\fR = \f(CW$finder\fR\->exclude_file($test)" 4
.IX Item "@reasons = $finder->exclude_file($test)"
The input argument should be an Test2::Harness::Test instance. This will
return a list of human readible reasons a test file should be excluded. If the
file should not be excluded the list will be empty.
.Sp
This is a utility method that verifies the file is not in an exclude
list/pattern. The reasons are provided back in case you need to inform the
user.
.ie n .IP "$bool = $finder\->include_file($test)" 4
.el .IP "\f(CW$bool\fR = \f(CW$finder\fR\->include_file($test)" 4
.IX Item "$bool = $finder->include_file($test)"
The input argument should be an Test2::Harness::Test instance. This is a
convenience method around \f(CW\*(C`exclude_file()\*(C'\fR, it will return true when
\&\f(CW\*(C`exclude_file()\*(C'\fR returns an empty list.
.ie n .IP "$arrayref = $finder\->find_multi_project_files($plugins, $settings)" 4
.el .IP "\f(CW$arrayref\fR = \f(CW$finder\fR\->find_multi_project_files($plugins, \f(CW$settings\fR)" 4
.IX Item "$arrayref = $finder->find_multi_project_files($plugins, $settings)"
.PD 0
.ie n .IP "$arrayref = $finder\->find_project_files($plugins, $settings, $search)" 4
.el .IP "\f(CW$arrayref\fR = \f(CW$finder\fR\->find_project_files($plugins, \f(CW$settings\fR, \f(CW$search\fR)" 4
.IX Item "$arrayref = $finder->find_project_files($plugins, $settings, $search)"
.PD
These do the heavy lifting for \f(CW\*(C`find_files\*(C'\fR
.Sp
The default \f(CW\*(C`find_files()\*(C'\fR implementation is this:
.Sp
.Vb 3
\&    sub find_files {
\&        my $self = shift;
\&        my ($plugins, $settings) = @_;
\&
\&        return $self\->find_multi_project_files($plugins, $settings) if $self\->multi_project;
\&        return $self\->find_project_files($plugins, $settings, $self\->search);
\&    }
.Ve
.Sp
Each one returns an arrayref of Test2::Harness::TestFile instances.
.Sp
Note that \f(CW\*(C`find_multi_project_files()\*(C'\fR uses \f(CW\*(C`find_project_files()\*(C'\fR internall,
once per project directory.
.Sp
\&\f(CW$plugins\fR is a list of plugins, some may be class names, others may be
instances.
.Sp
\&\f(CW$settings\fR is an Test2::Harness::Settings instance.
.Sp
\&\f(CW$search\fR is an arrayref of search paths.
.ie n .IP "$finder\->munge_settings($settings, $options)" 4
.el .IP "\f(CW$finder\fR\->munge_settings($settings, \f(CW$options\fR)" 4
.IX Item "$finder->munge_settings($settings, $options)"
A callback that lets you munge settings and options.
.ie n .IP "$finder\->pull_durations" 4
.el .IP "\f(CW$finder\fR\->pull_durations" 4
.IX Item "$finder->pull_durations"
This will fetch the durations data if ant was provided. This is a hashref of
relative test paths as keys where the value is the duration of the file (\s-1SHORT,
MEDIUM\s0 or \s-1LONG\s0).
.Sp
\&\fBduration_data()\fR is a cached version of this. This method will refresh the
cache for the other.
.SS "\s-1FROM SETTINGS\s0"
.IX Subsection "FROM SETTINGS"
See App::Yath::Options::Finder for up to date documentation on these.
.ie n .IP "$finder\->default_search" 4
.el .IP "\f(CW$finder\fR\->default_search" 4
.IX Item "$finder->default_search"
.PD 0
.ie n .IP "$finder\->default_at_search" 4
.el .IP "\f(CW$finder\fR\->default_at_search" 4
.IX Item "$finder->default_at_search"
.ie n .IP "$finder\->durations" 4
.el .IP "\f(CW$finder\fR\->durations" 4
.IX Item "$finder->durations"
.ie n .IP "$finder\->maybe_durations" 4
.el .IP "\f(CW$finder\fR\->maybe_durations" 4
.IX Item "$finder->maybe_durations"
.ie n .IP "$finder\->exclude_files" 4
.el .IP "\f(CW$finder\fR\->exclude_files" 4
.IX Item "$finder->exclude_files"
.ie n .IP "$finder\->exclude_patterns" 4
.el .IP "\f(CW$finder\fR\->exclude_patterns" 4
.IX Item "$finder->exclude_patterns"
.ie n .IP "$finder\->no_long" 4
.el .IP "\f(CW$finder\fR\->no_long" 4
.IX Item "$finder->no_long"
.ie n .IP "$finder\->only_long" 4
.el .IP "\f(CW$finder\fR\->only_long" 4
.IX Item "$finder->only_long"
.ie n .IP "$finder\->search" 4
.el .IP "\f(CW$finder\fR\->search" 4
.IX Item "$finder->search"
.ie n .IP "$finder\->extensions" 4
.el .IP "\f(CW$finder\fR\->extensions" 4
.IX Item "$finder->extensions"
.PD
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for Test2\-Harness can be found at
\&\fIhttp://github.com/Test\-More/Test2\-Harness/\fR.
.SH "MAINTAINERS"
.IX Header "MAINTAINERS"
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.SH "AUTHORS"
.IX Header "AUTHORS"
.PD 0
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.PD
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2020 Chad Granum <exodist7@gmail.com>.
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.PP
See \fIhttp://dev.perl.org/licenses/\fR