1package Test2::Formatter; 2use strict; 3use warnings; 4 5our $VERSION = '1.302133'; 6 7 8my %ADDED; 9sub import { 10 my $class = shift; 11 return if $class eq __PACKAGE__; 12 return if $ADDED{$class}++; 13 require Test2::API; 14 Test2::API::test2_formatter_add($class); 15} 16 17sub new_root { 18 my $class = shift; 19 return $class->new(@_); 20} 21 22sub hide_buffered { 1 } 23 24sub terminate { } 25 26sub finalize { } 27 281; 29 30__END__ 31 32=pod 33 34=encoding UTF-8 35 36=head1 NAME 37 38Test2::Formatter - Namespace for formatters. 39 40=head1 DESCRIPTION 41 42This is the namespace for formatters. This is an empty package. 43 44=head1 CREATING FORMATTERS 45 46A formatter is any package or object with a C<write($event, $num)> method. 47 48 package Test2::Formatter::Foo; 49 use strict; 50 use warnings; 51 52 sub write { 53 my $self_or_class = shift; 54 my ($event, $assert_num) = @_; 55 ... 56 } 57 58 sub hide_buffered { 1 } 59 60 sub terminate { } 61 62 sub finalize { } 63 64 sub new_root { 65 my $class = shift; 66 ... 67 $class->new(@_); 68 } 69 70 1; 71 72The C<write> method is a method, so it either gets a class or instance. The two 73arguments are the C<$event> object it should record, and the C<$assert_num> 74which is the number of the current assertion (ok), or the last assertion if 75this event is not itself an assertion. The assertion number may be any integer 0 76or greater, and may be undefined in some cases. 77 78The C<hide_buffered()> method must return a boolean. This is used to tell 79buffered subtests whether or not to send it events as they are being buffered. 80See L<Test2::API/"run_subtest(...)"> for more information. 81 82The C<terminate> and C<finalize> methods are optional methods called that you 83can implement if the format you're generating needs to handle these cases, for 84example if you are generating XML and need close open tags. 85 86The C<terminate> method is called when an event's C<terminate> method returns 87true, for example when a L<Test2::Event::Plan> has a C<'skip_all'> plan, or 88when a L<Test2::Event::Bail> event is sent. The C<terminate> method is passed 89a single argument, the L<Test2::Event> object which triggered the terminate. 90 91The C<finalize> method is always the last thing called on the formatter, I<< 92except when C<terminate> is called for a Bail event >>. It is passed the 93following arguments: 94 95The C<new_root> method is called when C<Test2::API::Stack> Initializes the root 96hub for the first time. Most formatters will simply have this call C<< 97$class->new >>, which is the default behavior. Some formatters however may want 98to take extra action during construction of the root formatter, this is where 99they can do that. 100 101=over 4 102 103=item * The number of tests that were planned 104 105=item * The number of tests actually seen 106 107=item * The number of tests which failed 108 109=item * A boolean indicating whether or not the test suite passed 110 111=item * A boolean indicating whether or not this call is for a subtest 112 113=back 114 115=head1 SOURCE 116 117The source code repository for Test2 can be found at 118F<http://github.com/Test-More/test-more/>. 119 120=head1 MAINTAINERS 121 122=over 4 123 124=item Chad Granum E<lt>exodist@cpan.orgE<gt> 125 126=back 127 128=head1 AUTHORS 129 130=over 4 131 132=item Chad Granum E<lt>exodist@cpan.orgE<gt> 133 134=back 135 136=head1 COPYRIGHT 137 138Copyright 2018 Chad Granum E<lt>exodist@cpan.orgE<gt>. 139 140This program is free software; you can redistribute it and/or 141modify it under the same terms as Perl itself. 142 143See F<http://dev.perl.org/licenses/> 144 145=cut 146