Test2:...Finder(3pm)

💖 NAME 💖

Test2::Harness::Finder — the library that goes and finds your test files, bestie 🔍✨

---

🌸 DESCRIPTION 🌸

So like, the finder is the one who's responsible for locating the test files that should actually be run. That's its whole job. That's its moment. 👑

And plot twist: you can totally subclass the finder and tell yath to use your subclass instead. Main character energy fr fr.

---

✨ SYNOPSIS ✨

🎀 USING A CUSTOM FINDER

Okay so to use Test2::Harness::Finder::MyFinder:

$ yath test --finder MyFinder

And to use Another::Finder:

$ yath test --finder +Another::Finder

So the thing is, by default Test2::Harness::Finder:: gets prefixed onto your custom finder name. Use a + before the class name to prevent this (like, to stop the prefixing). 💅

🦋 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 the important state methods, plus utility methods for you to use in your subclasses. Slay.

• $bool = $finder->multi_project — True if the yath projects command was used. Simple as that. ✅
• $arrayref = $finder->find_files($plugins, $settings) — This is the main method, periodt. It returns an arrayref of Test2::Harness::TestFile instances, and each one represents 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. iykyk

• $durations = $finder->duration_data — This will fetch the durations data if any was provided. It's a hashref where the keys are relative test paths and the value is the duration of the file (SHORT, MEDIUM or LONG). ⏱️

Note: The result is cached, so peep pull_durations() if you wanna refresh the data.

• @reasons = $finder->exclude_file($test) — The input argument should be an Test2::Harness::Test instance. This returns 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 handed back to you 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 wrapped around exclude_file(), and it returns 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 two do the heavy lifting for find_files. 💪
  • The default find_files() implementation is literally 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. Go off. 🔧
• $finder->pull_durations — This will fetch the durations data if ant was provided. It's a hashref where the keys are relative test paths and 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 one.

---

👑 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/

---

okay and that's the whole page bestie, tysm for reading, mwah 💋✨ This was brought to you by perl v5.40.1, dated 2026-05-10, and manual page Test2:...Finder(3pm) — User Contributed Perl Documentation. Go find some tests, queen. 🦋👑