NAME

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

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.

SYNOPSIS

   USING A CUSTOM FINDER
       To use Test2::Harness::Finder::MyFinder:

           $ yath test --finder MyFinder

       To use Another::Finder

           $ yath test --finder +Another::Finder

       By default "Test2::Harness::Finder::" is prefixed onto your custom finder, use '+' before
       the class name or prevent this.

   SUBCLASSING
           use parent 'Test2::Harness::Finder';
           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(...),
                   ...,
               ];
           }

METHODS

       These are important state methods, as well as utility methods for use in your subclasses.

       $bool = $finder->multi_project
           True if the "yath projects" command was used.

       $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.

           $plugins is a list of plugins, some may be class names, others may be instances.

           $settings is an Test2::Harness::Settings instance.

           Note: In many cases it is better to override "find_project_files()" in your
           subclasses.

       $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 (SHORT, MEDIUM or
           LONG).

           Note: The result is cached, see pull_durations() to refresh the data.

       @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.

           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.

       $bool = $finder->include_file($test)
           The input argument should be an Test2::Harness::Test instance. This is a convenience
           method around "exclude_file()", it will return true when "exclude_file()" returns an
           empty list.

       $arrayref = $finder->find_multi_project_files($plugins, $settings)
       $arrayref = $finder->find_project_files($plugins, $settings, $search)
           These do the heavy lifting for "find_files"

           The default "find_files()" implementation is this:

               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);
               }

           Each one returns an arrayref of Test2::Harness::TestFile instances.

           Note that "find_multi_project_files()" uses "find_project_files()" internall, once per
           project directory.

           $plugins is a list of plugins, some may be class names, others may be instances.

           $settings is an Test2::Harness::Settings instance.

           $search is an arrayref of search paths.

       $finder->munge_settings($settings, $options)
           A callback that lets you munge settings and options.

       $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 (SHORT, MEDIUM or
           LONG).

           duration_data() is a cached version of this. This method will refresh the cache for
           the other.

   FROM SETTINGS
       See App::Yath::Options::Finder for up to date documentation on these.

       $finder->default_search
       $finder->default_at_search
       $finder->durations
       $finder->maybe_durations
       $finder->exclude_files
       $finder->exclude_patterns
       $finder->no_long
       $finder->only_long
       $finder->search
       $finder->extensions

SOURCE

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

MAINTAINERS

       Chad Granum <exodist@cpan.org>

AUTHORS

       Chad Granum <exodist@cpan.org>

COPYRIGHT

       Copyright 2020 Chad Granum <exodist7@gmail.com>.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

       See http://dev.perl.org/licenses/