App::Y...:Plugin(3pm)

📦
version 1.000172 · 8 versions
, in ubuntu stonking

🌸 NAME 🌸

App::Yath::Plugin — the base class for all the yath plugins, no cap 💖

✨ DESCRIPTION ✨

Okay so listen: this is the base class for yath plugins. And plot twist — this class also subclasses Test2::Harness::Plugin, so it's giving layered cake 🎂

Here's the vibe: this class holds all the methods that are specific to yath, which is the UI layer bestie. Meanwhile Test2::Harness::Plugin holds the methods specific to Test2::Harness, which is the backend. Two queens, two jobs, one slay 👑

🦋 SYNOPSIS 🦋

package App::Yath::Plugin::MyPlugin;

use parent 'App::Yath::Plugin';

# ... Define methods

1;

Then to actually use it at the command line, you do this:

$ yath -pMyPlugin ...

That's it, that's the whole ritual ✨

💅 NOTE ON INSTANCE VS CLASS 💅

Real talk: none of the plugin base classes provide a new() method. By default plugins are not instantiated — only the plugin package name gets passed around, and all the methods are then called on the class. Very "we're all just names here" of them 🫶

But bb, if you want your plugin to be instantiated as an object? You literally just define a new() method. If that method exists, yath will call it and create an instance. Then that instance gets used every time all the methods are called. Main character behaviour, honestly 💅

Wanna pass arguments to the constructor? Easy:

yath -pYourPlugin=arg1,arg2,arg3...

Your plugin can also define options using App::Yath::Options, and those will get dropped into the $settings that get passed around. So many settings, so little time 😭

🔥 METHODS 🔥

Note: See Test2::Harness::Plugin for additional method you can implement/override

Heads up — that's the extra homework, go read it iykyk 📚

$plugin->handle_event($event, $settings)

Called for every single event that yath sees. Not me reminding you that this method is not defined by default — and that's for performance reasons, bestie, don't come for them. But the tea is: it will be called if you define it. So define it or don't, your call 💖

@sorted = $plugin->sort_files_2(settings => $settings, files => \@unsorted)

This gives your plugin a chance to sort the files before they get added to the queue. Other things happen later to re-order the files optimally based on length or category, so this sort is just for initial job numbering, and to define a base order before optimization takes place. It's giving "first draft of the playlist" 🎧

All files to sort will be instances of Test2::Harness::TestFile.

This method is normally left undefined, but it will be called if you define it.

Important: if this is present, then sort_files() will be ignored. Periodt.

@sorted = $plugin->sort_files(@unsorted)

DEPRECATED — use sort_files_2() instead, bestie, we moved on 🚫

This gives your plugin a chance to sort the files before they get added to the queue. Other things are done later to re-order the files optimally based on length or category, so this sort is just for initial job numbering, and to define a base order before optimization takes place.

All files to sort will be instances of Test2::Harness::TestFile.

This method is normally left undefined, but will be called if you define it.

$plugin->finish(%args)

This is what arguments are recieved:

(
    settings     => $settings,                      # The settings
    final_data   => $final_data,                    # See below
    pass         => $pass ? 1 : 0,                  # Always a 0 or 1
    tests_seen   => $self->{+TESTS_SEEN} // 0,      # Integer 0 or greater
    asserts_seen => $self->{+ASSERTS_SEEN} // 0,    # Integer 0 or greater
)

The final_data looks like this — and note that some data may not be present if it is not applicable. The data structure can be as simple as { pass => $bool }. Minimalist queen 🎀

{
    pass => $pass,    # boolean, did the test run pass or fail?

    failed => [       # Jobs that failed, and did not pass on a retry
        [$job_id1, $file1],    # Failing job 1
        [$job_id2, $file2],    # Failing job 2
        ...
    ],
    retried => [               # Jobs that failed and were retried
        [$job_id1, $times_run1, $file1, $passed_eventually1],    # Passed_eventually is a boolean
        [$job_id2, $times_run2, $file2, $passed_eventually2],
        ...
    ],
    hatled => [                                                  # Jobs that caused the entire test suite to halt
        [$job_id1, $file1, $halt_reason1],                       # halt_reason is a human readible string
        [$job_id2, $file2, $halt_reason2],
    ],
}

$plugin->finalize($settings)

This is called as late as possible before exit. Mainly useful for outputting messages such as "Extra log file written to ..." — the kind of thing that's best put at the end of the output. Last word energy, honestly 👑

🧚 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 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 that's the whole page, bestie 🫶 this was the App::Yath::Plugin(3pm) page — User Contributed Perl Documentation — and it's brought to you by perl v5.40.1, dated 2026-05-10. go forth and write an iconic plugin, mwah 💖✨

📦 where this page comes from