NAME

       App::Yath::Plugin - Base class for yath plugins

DESCRIPTION

       This is a base class for yath plugins. Note this class also subclasses
       Test2::Harness::Plugin.

       This class holds the methods specific to yath, which is the UI layer.
       Test2::Harness::Plugin holds the methods specific to Test2::Harness which is the backend.

SYNOPSIS

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

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

           # ... Define methods

           1;

       Then to use it at the command line:

           $ yath -pMyPlugin ...

NOTE ON INSTANCE VS CLASS

       None of the plugin base classes provide a "new()" method. By default plugins are not
       instantiated and only the plugin package name is passed around. All methods are then
       called on the class.

       If you want your plugin to be instantiated as an object you need only define a "new()"
       method. If this method is defined yath will call it and create an instance. The instance
       created will then be used when calling all the methods.

       To pass arguments to the constructor you can use "yath -pYourPlugin=arg1,arg2,arg3...".
       Your plugin can also define options using App::Yath::Options which will be dropped into
       the $settings that get passed around.

METHODS

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

       $plugin->handle_event($event, $settings)
           Called for every single event that yath sees. Note that this method is not defined by
           default for performance reasons, however it will be called if you define it.

       @sorted = $plugin->sort_files_2(settings => $settings, files => \@unsorted)
           This gives your plugin a chance to sort the files before they are 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.

           If this is present then "sort_files()" will be ignored.

       @sorted = $plugin->sort_files(@unsorted)
           DEPRECATED Use "sort_files_2()" instead.

           This gives your plugin a chance to sort the files before they are 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, note that some data may not be present if it is not
           applicable. The data structure can be as simple as "{ pass => $bool }".

               {
                   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. This is mainly useful for outputting
           messages such as "Extra log file written to ..." which are best put at the end of
           output.

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/