1App::Yath::Plugin(3)  User Contributed Perl Documentation App::Yath::Plugin(3)
2
3
4

NAME

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

DESCRIPTION

9       This is a base class for yath plugins. Note this class also subclasses
10       Test2::Harness::Plugin.
11
12       This class holds the methods specific to yath, which is the UI layer.
13       Test2::Harness::Plugin holds the methods specific to Test2::Harness
14       which is the backend.
15

SYNOPSIS

17           package App::Yath::Plugin::MyPlugin;
18
19           use parent 'App::Yath::Plugin';
20
21           # ... Define methods
22
23           1;
24
25       Then to use it at the command line:
26
27           $ yath -pMyPlugin ...
28

NOTE ON INSTANCE VS CLASS

30       None of the plugin base classes provide a new() method. By default
31       plugins are not instantiated and only the plugin package name is passed
32       around. All methods are then called on the class.
33
34       If you want your plugin to be instantiated as an object you need only
35       define a new() method. If this method is defined yath will call it and
36       create an instance. The instance created will then be used when calling
37       all the methods.
38
39       To pass arguments to the constructor you can use "yath
40       -pYourPlugin=arg1,arg2,arg3...". Your plugin can also define options
41       using App::Yath::Options which will be dropped into the $settings that
42       get passed around.
43

METHODS

45       Note: See Test2::Harness::Plugin for additional method you can
46       implement/override
47
48       $plugin->handle_event($event, $settings)
49           Called for every single event that yath sees. Note that this method
50           is not defined by default for performance reasons, however it will
51           be called if you define it.
52
53       @sorted = $plugin->sort_files_2(settings => $settings, files =>
54       \@unsorted)
55           This gives your plugin a chance to sort the files before they are
56           added to the queue. Other things are done later to re-order the
57           files optimally based on length or category, so this sort is just
58           for initial job numbering, and to define a base order before
59           optimization takes place.
60
61           All files to sort will be instances of Test2::Harness::TestFile.
62
63           This method is normally left undefined, but will be called if you
64           define it.
65
66           If this is present then sort_files() will be ignored.
67
68       @sorted = $plugin->sort_files(@unsorted)
69           DEPRECATED Use sort_files_2() instead.
70
71           This gives your plugin a chance to sort the files before they are
72           added to the queue. Other things are done later to re-order the
73           files optimally based on length or category, so this sort is just
74           for initial job numbering, and to define a base order before
75           optimization takes place.
76
77           All files to sort will be instances of Test2::Harness::TestFile.
78
79           This method is normally left undefined, but will be called if you
80           define it.
81
82       $plugin->finish(%args)
83           This is what arguments are recieved:
84
85               (
86                   settings     => $settings,                      # The settings
87                   final_data   => $final_data,                    # See below
88                   pass         => $pass ? 1 : 0,                  # Always a 0 or 1
89                   tests_seen   => $self->{+TESTS_SEEN} // 0,      # Integer 0 or greater
90                   asserts_seen => $self->{+ASSERTS_SEEN} // 0,    # Integer 0 or greater
91               )
92
93           The final_data looks like this, note that some data may not be
94           present if it is not applicable. The data structure can be as
95           simple as "{ pass => $bool }".
96
97               {
98                   pass => $pass,    # boolean, did the test run pass or fail?
99
100                   failed => [       # Jobs that failed, and did not pass on a retry
101                       [$job_id1, $file1],    # Failing job 1
102                       [$job_id2, $file2],    # Failing job 2
103                       ...
104                   ],
105                   retried => [               # Jobs that failed and were retried
106                       [$job_id1, $times_run1, $file1, $passed_eventually1],    # Passed_eventually is a boolean
107                       [$job_id2, $times_run2, $file2, $passed_eventually2],
108                       ...
109                   ],
110                   hatled => [                                                  # Jobs that caused the entire test suite to halt
111                       [$job_id1, $file1, $halt_reason1],                       # halt_reason is a human readible string
112                       [$job_id2, $file2, $halt_reason2],
113                   ],
114               }
115
116       $plugin->finalize($settings)
117           This is called as late as possible before exit. This is mainly
118           useful for outputting messages such as "Extra log file written to
119           ..." which are best put at the end of output.
120

SOURCE

122       The source code repository for Test2-Harness can be found at
123       http://github.com/Test-More/Test2-Harness/.
124

MAINTAINERS

126       Chad Granum <exodist@cpan.org>
127

AUTHORS

129       Chad Granum <exodist@cpan.org>
130

COPYRIGHT

132       Copyright 2020 Chad Granum <exodist7@gmail.com>.
133
134       This program is free software; you can redistribute it and/or modify it
135       under the same terms as Perl itself.
136
137       See http://dev.perl.org/licenses/
138
139
140
141perl v5.36.1                      2023-10-04              App::Yath::Plugin(3)