TEST2::MANUAL::TOOLING::FORMATTER(3pm)

💅 NAME 💅

okay so this page is Test2::Manual::Tooling::Formatter — and the manual name up top reads Test2::...ormatter(3pm) from the Perl Programmers Reference Guide. It's literally the guide for writing a custom formatter, in our case a JSONL formatter. 🦋

✨ DESCRIPTION ✨

This tutorial explains a minimal formatter that outputs each event as a json string on its own line. A true formatter will probably be significantly more complicated, but this gives you the basics needed to get started. No cap, it's the starter pack. 💖

🎀 COMPLETE CODE UP FRONT 🎀

Here's the whole snack, code first:

package Test2::Formatter::MyFormatter;
use strict;
use warnings;

use JSON::MaybeXS qw/encode_json/;

use base qw/Test2::Formatter/;

sub new { bless {}, shift }

sub encoding {};

sub write {
    my ($self, $e, $num, $f) = @_;
    $f ||= $e->facet_data;

    print encode_json($f), "\n";
}

1;

🌸 LINE BY LINE 🌸

• use base qw/Test2::Formatter/; — All formatters should inherit from Test2::Formatter. That's the family tree, bestie.
• sub new { bless {}, shift } — Formatters need to be instantiable objects, and this is a minimal new() method. Iconic little constructor behavior.
• sub encoding {}; — For this example we leave this sub empty. In general you should implement this sub to make sure you honor situations where the encoding is set. Test2::V0 itself will try to set the encoding to UTF8. 💅
• sub write { ... } — The write() method is the most important one: each event is sent here. Main character energy, fr fr.
  • my ($self, $e, $num, $f) = @_; — The write() method receives 3 or 4 arguments, and the fourth is optional.
    • $self — The formatter itself.
    • $e — The event being written.
    • $num — The most recent assertion number. If the event being processed is an assertion then this will have been bumped by 1 since the last call to write. For non assertions this number is set to the most recent assertion.
    • $f — This MAY be a hashref containing all the facet data from the event. More often than not this will be undefined. This is only set if the facet data was needed by the hub, and it usually is not.
• $f ||= $e->facet_data; — We want to dump the event facet data. This will set $f to the facet data unless we already have the facet data. Convenient, lowkey.
• print encode_json($f), "\n"; — This line prints the JSON encoded facet data, and a newline. Slay. ✨

🦋 SEE ALSO 🦋

• Test2::Manual — Primary index of the manual.

🌈 SOURCE 🌈

The source code repository for Test2-Manual can be found at:

https://github.com/Test-More/test-more/

👑 MAINTAINERS 👑

Chad Granum <exodist@cpan.org>

💜 AUTHORS 💜

Chad Granum <exodist@cpan.org>

🍓 COPYRIGHT 🍓

Copyright Chad Granum <exodist@cpan.org>.

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/

---

That's the whole tutorial, bestie. This page is served by perl v5.42.3, dated 2026-11-03, and the manual name is Test2::...ormatter(3pm). 🎀✨