Test2::...lCritic(3)

💖 Test2::Tools::PerlCritic — the manual page, but make it a group chat 💖

okay bestie so the manual name is Test2::Tools::PerlCritic and this is the page for it, and we are gonna read it together and it's gonna be so good I promise 🫶

---

✨ NAME ✨

Test2::Tools::PerlCritic — testing tools to enforce Perl::Critic policies. like, it makes your code get judged. by a robot. lovingly. 💅

---

🌸 VERSION 🌸

version 0.08

---

🦋 SYNOPSIS 🦋

okay so there are two whole vibes here, bestie, pick your fighter:

the original procedural interface (the classic, the icon)

use Test2::V0;
use Test2::Tools::PerlCritic;

perl_critic_ok ['lib','t'], 'test library files';

done_testing;

the new OO interface (main character energy)

use Test2::V0;
use Test2::Tools::PerlCritic ();
use Perl::Critic;

my $test_critic = Test2::Tools::PerlCritic->new({
  files     => ['lib','t'],
  test_name => 'test library_files',
});

$test_critic->perl_critic_ok;

done_testing;

---

👑 DESCRIPTION 👑

So the whole point: you test for Perl::Critic violations using Test2. 💖

And listen — even though this testing tool uses the Test2 API instead of the older Test::Builder API, the real motivation is that the output is just... better. more useful. it ate. 🔥

Here's the tea: policy violations get grouped by policy class, and the policy class name is clearly displayed as a diagnostic. The author finds the former (the grouping) more useful because he tends to address one type of violation at a time. The author finds the latter (the visible policy class name) more useful because he tends to want to look up or adjust the configuration of the policy as he is addressing violations. two for two, slay. ✨

---

💜 FUNCTIONS 💜

🎀 perl_critic_ok

perl_critic_ok $path, \@options, $test_name;
perl_critic_ok \@path, \@options, $test_name;
perl_critic_ok $path, \%options, $test_name;
perl_critic_ok \@path, \%options, $test_name;
perl_critic_ok $path, $critic, $test_name;
perl_critic_ok \@path, $critic, $test_name;
perl_critic_ok $path, $test_name;
perl_critic_ok \@path, $test_name;
perl_critic_ok $path;
perl_critic_ok \@path;

Runs Perl::Critic on the given files or directories. go off, king. 👑

So the first argument ($path or @path) can be either the path to a file or directory, OR an array reference to a list of paths to files and directories. both are valid, we don't gatekeep. 💅

If @options or %options are provided, then they get passed into the Perl::Critic constructor. 🎀

If $critic (an instance of Perl::Critic) is provided, then that Perl::Critic instance will be used instead of creating one internally. bring your own critic, we love that for you.

And finally the $test_name may be provided if you do not like the default test name. it's fine, we won't be offended. 😭

⚠️ Only a single test is run regardless of how many files are processed. this is so that the policy violations can be grouped by policy class across multiple files. one test to rule them all, periodt.

As a convenience, if the test passes then a true value is returned. Otherwise a false will be returned. 🫶

🚨 "done_testing" or the equivalent is NOT called by this function. You are responsible for calling that yourself. not me handing you the aux cord and then walking away. 🙈

Since we do not automatically call "done_testing", you can call "perl_critic_ok" multiple times, but keep in mind that the policy violations will only be grouped in each individual call, so it is probably better to provide a list of paths, rather than make multiple calls. lowkey just pass the list, bestie. 🌈

---

🧚 CONSTRUCTOR 🧚

my $test_critic = Test2::Tools::PerlCritic->new(\%properties);

Properties, babes:

• files — (REQUIRED) ⚠️ list of files or directories. Directories will be recursively searched for Perl files (".pm", ".pl" and ".t"). it's giving thorough. 🦋
• critic — the Perl::Critic instance. One will be created if not provided. no thoughts, it'll handle it. 💭
• test_name — the name of the test. This is used in diagnostics. name her, she deserves it. 🎀

---

💅 METHODS 💅

✨ perl_critic_ok

$test_critic->perl_critic_ok;

The method version works just like the functional version above, except it doesn't take any additional arguments. she said no extra baggage. 💅

✨ add_hook

$test_critic->add_hook($hook_name, \&code);

Adds the given hook. Available hooks, let's go:

🌸 cleanup

$test_critic->add_hook(cleanup => sub ($test_critic, $global) {
  ...
});

This hook is called when the Test2::Tools::PerlCritic instance is destroyed. rip to the instance, but she lived. 😭

If the hook is called during global destruction of the Perl interpreter, $global will be set to a true value. 🌍

This hook can be set multiple times. no cap. ✨

🌸 progressive_check

$test_critic->add_hook(progressive_check => sub ($test_critic, $policy, $file, $count) {
  ...
  return $bool;
});

This hook is made available for violations in existing code when new policies are added. very "we're not gonna fix legacy today" of it. 🫶

Passed in are the Test2::Tools::PerlCritic instance, the policy name, the filename and the number of times the violation was found.

If the violations are from an old code base with grandfathered allowed violations, this hook should return true, and the violation will be reported as a "note" instead of "diag" and will not cause the test as a whole to fail. Otherwise the violation will be reported using "diag" and the test as a whole will fail. so like, be honest with the return value, bestie. 💀

This hook can only be set once. one and done. ⭐

🌸 violations

$test_critic->add_hook(violations => sub ($test_critic, @violations) {
  ...
});

Each time violations are returned from "critique" in Perl::Critic, they are passed into this hook as a list. The order and grouping of violations may change in the future. so don't get too attached to the ordering, it's fluid, it's a vibe. 🌊

---

🚨 CAVEATS 🚨

Test::Perl::Critic has been around longer, and probably does at least some things smarter. we're being humble, we're being real. 🙈

The fact that this module groups policy violations for all files by class means that it has to store more diagnostics in memory before sending them out en masse, whereas Test::Perl::Critic sends violations for each file as it processes them. Test::Perl::Critic also comes with some code to optionally do processing in parallel. Some of these issues may or may not be addressed in future versions of this module. shrug, it's a roadmap, not a promise. 🌈

⚠️ Since this module formats it's output the "-verbose" option is ignored at the "set_format" value is ignored. yes, that's the sentence. it's a little cursed. we report it faithfully. 💀

---

🔍 SEE ALSO 🔍

• Test::Perl::Critic
• Perl::Critic

---

🌟 AUTHOR 🌟

Graham Ollis <plicease@cpan.org> 🫶

---

📜 COPYRIGHT AND LICENSE 📜

This software is copyright (c) 2019-2024 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 💖

---

okay that's the whole page bestie, you ate, we ate, everybody ate 🍓✨ this was Test2::Tools::PerlCritic, documented by perl v5.42.0 and dated 2025-07-25 — mwah, go run your tests, ily, bye 💅👑🎀