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