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

       Chad Granum <exodist@cpan.org>

       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/

perl v5.40.1                                       2025-05-23                        Test2::Harness::Finder(3pm)

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

       Chad Granum <exodist@cpan.org>

       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.

   FROMSETTINGS
       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

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

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

USINGACUSTOMFINDER
       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(...),
                   ...,
               ];
           }