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

💖 NAME 💖

Test2::Manual::Tooling::Formatter — bestie, this is literally the tutorial on how to write your own custom formatter. And in this case, we're building a JSONL formatter, so slay.

(Also it lives in the Perl Programmers Reference Guide, iykyk 💅)

---

✨ DESCRIPTION ✨

Okay so this tutorial walks you through a minimal formatter that dumps every event as a json string, one per line. That's it. That's the whole vibe. 🌸

A real formatter is gonna be way more complicated than this, no cap — but this gives you the basics you need to get started. Think of it as the starter pack. 🎀

---

🧚 COMPLETE CODE UP FRONT 🧚

Here's the whole thing, no cliffhangers, we're not gatekeeping:

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;

Iconic. Obsessed. Now let's go line by line because the details matter fr fr. 💅

---

🌈 LINE BY LINE 🌈

• use base qw/Test2::Formatter/; — Every single formatter ever should inherit from Test2::Formatter. That's the rule, periodt.
• sub new { bless {}, shift } — Formatters need to be instantiable objects, so here's a tiny lil new() method, minimal but functional.
• sub encoding {}; — For this example we just leave this sub empty. In general though? You should implement this sub so you honor the situations where the encoding is set. Fun fact: Test2::V0 itself will try to set the encoding to UTF8.
• sub write { ... } — The write() method is the most important one — this is where every event gets sent. Main character sub, honestly. 👑

Inside write() we've got this:

my ($self, $e, $num, $f) = @_;

The write() method receives 3 or 4 arguments — that fourth one is optional, bestie.

• $self — The formatter itself. Hi, that's you. 👋
• $e — The event being written.
• $num — The most recent assertion number. If the event being processed is an assertion, then this has 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. But more often than not it'll be undefined. It's only set if the facet data was needed by the hub, and usually... it just isn't. 🙈

Then:

$f ||= $e->facet_data;

We want to dump the event facet data, so this sets $f to the facet data — unless we already have it, in which case we're good. Efficiency, queen. ✨

And finally:

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

This line prints the JSON encoded facet data, plus a newline. That's it, that's the whole formatter doing its thing. 🦋

---

Lowkey important reminder: this is a minimal example. Your real formatter will probably be doing way more than this, and that's totally fine.

---

💜 SEE ALSO 💜

• Test2::Manual — The primary index of the manual. Go there if you want the whole map, bestie. 🗺️

---

🔥 SOURCE 🔥

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

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

Go star it or whatever, support the ecosystem. ⭐

---

👑 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/

---

And that's a wrap, bestie! 🫶 This was perl v5.44.0, dated 2026-10-17 — go forth and format some events, you absolute icon. 💖✨