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/