---
name: "Test2::Harness::Finder"
section: "3pm"
platform: "linux"
package: "libtest2-harness-perl"
version: "1.000158-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Test2::Harness::Finder"
---

# Test2::Harness::Finder(3pm)

Library that searches for test files

## 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/*