Test::Routine(3pm)

💖 Test::Routine(3pm) 💖

okay so this is the Test::Routine(3pm) page from the User Contributed Perl Documentation corner of your perl install, and bestie, she is everything. Sit down, grab a snack, we're doing this. 🍓

---

🌟 NAME 🌟

Test::Routine — composable units of assertion. that's the whole name and honestly? iconic. 💅

🎀 VERSION 🎀

version 0.032

she's on 0.032, periodt. ✨

🦋 SYNOPSIS 🦋

# mytest.t
use Test::More;
use Test::Routine;
use Test::Routine::Util;

has fixture => (
  is   => 'ro',
  lazy => 1,
  clearer => 'reset_fixture',
  default => sub { ...expensive setup... },
);

test "we can use our fixture to do stuff" => sub {
  my ($self) = @_;

  $self->reset_fixture; # this test requires a fresh one

  ok( $self->fixture->do_things, "do_things returns true");
  ok( ! $self->fixture->no_op,   "no_op returns false");

  for my $item ($self->fixture->contents) {
    isa_ok($item, 'Fixture::Entry');
  }
};

test "fixture was recycled" => sub {
  my ($self) = @_;

  my $fixture = $self->fixture; # we don't expect a fresh one

  is( $self->fixture->things_done, 1, "we have done one thing already");
};

run_me;
done_testing;

---

💖 DESCRIPTION 💖

okay so what is Test::Routine? she's a very simple framework for writing your tests as composable units of assertion. and "in other words"?? roles. that's the whole thing, no cap. 🙈

wanna see a walkthrough of tests written with Test::Routine? go read Test::Routine::Manual::Demo. it's giving tutorial, it's giving slay. 🦋

Test::Routine is similar to Test::Class in some ways — but lowkey those similarities are largely superficial. the idea of "tests bound together in reusable units" is genuinely useful to understand when you're coming to Test::Routine, though. so: if you're already familiar with Test::Class, it's the differences rather than the similarities that will be more important for you to understand. and if you're not familiar with Test::Class? there is no need to understand it prior to using Test::Routine. zero pressure, bestie. 🫶

on the other hand — and this is the one — an understanding of the basics of Moose is absolutely essential. Test::Routine composes tests from Moose classes, roles, and attributes. without an understanding of those, you will not be able to use Test::Routine. full stop. the Moose::Manual is an excellent resource for learning Moose, and it has links to other online tutorials and documentation. go read it. like actually actually. 📚✨

💭 The Concepts 💭

(this heading is doing absolutely nothing in the original either, she's just vibing 😌 — the real tea is right below)

🧚 The Basics of Using Test::Routine 🧚

there actually isn't much to Test::Routine other than the basics. she does not provide many complex features — instead she delegates almost everything to the Moose object system, as a queen should. 👑

✍️ Writing Tests

to write a set of tests (a test routine, which is a role), you add use Test::Routine; to your package. main is a perfectly acceptable target for turning into a test routine, which means you may absolutely use Test::Routine in your *.t files in your distribution. 🌸

use-ing Test::Routine will turn your package into a role that composes Test::Routine::Common, and will give you the test declarator for adding tests to your routine. Test::Routine::Common adds the run_test method that will be called to run each test.

the test declarator is very simple, and will generally be called like this:

test $NAME_OF_TEST => sub {
  my ($self) = @_;

  is($self->foo, 123, "we got the foo we expected");
  ...
  ...
};

this defines a test with a given name, which will be invoked like a method on the test object (described below). tests are ordered by declaration within the file — but when multiple test routines are run in a single test, the ordering of the routines is undefined. chaotic. we respect it. 💀

test may also be given a different name for the installed method and the test description. this isn't usually needed, but it can make things clearer when you're referring to tests as methods:

test $NAME_OF_TEST_METHOD => { description => $TEST_DESCRIPTION } => sub {
  ...
}

each test will be run by the run_test method. to add setup or teardown behavior, advice (method modifiers) may be attached to that method. for example, to call an attribute clearer before each test, you could add:

before run_test => sub {
  my ($self) = @_;

  $self->clear_some_attribute;
};

🏃 Running Tests

to run tests, you'll need to use Test::Routine::Util, which will provide two functions for running tests: run_tests and run_me. the former is given a set of packages to compose and run as tests. the latter runs the caller, assuming it to be a test routine.

run_tests can be called in several ways:

run_tests( $desc, $object );

run_tests( $desc, \@packages, $arg );

run_tests( $desc, $package, $arg );  # equivalent to ($desc, [$pkg], $arg)

in the first case, the object is assumed to be a fully formed, testable object. in other words, you've already created a class that composes test routines and you've built an instance of it. proud of you. 🥹

in the other cases, run_tests will produce an instance for you. it divides the given packages into classes and roles. if more than one class was given, an exception is thrown — so don't do that. a new class is created subclassing the given class and applying the given roles. if no class was in the list, Moose::Object is used. the new class's new is called with the given $arg (if any).

the composition mechanism makes it easy to run a test routine without first writing a class to which to apply it. this is what makes it possible to write your test routine in the main package and run it directly from your *.t file. the following is a valid, trivial use of Test::Routine:

use Test::More;
use Test::Routine;
use Test::Routine::Util;

test demo_test => sub { pass("everything is okay") };

run_tests('our tests', 'main');
done_testing;

in this circumstance, though, you'd probably use run_me, which runs the tests in the caller. you'd just replace the run_tests line with run_me;. a description for the run may be supplied, if you like. cute, optional, we love. 🎀

each call to run_me or run_tests generates a new instance, and you can call them as many times, with as many different arguments, as you like. but since Test::Routine can't know how many times you'll call different test routines, you are responsible for calling done_testing when you're done testing. that's on you, bestie. don't forget. 🫶

🔍 Running individual tests

if you only want to run a subset of the tests, you can set the TEST_METHOD environment variable to a regular expression that matches the names of the tests you want to run. yes way. 🙈

for example, to run just the test named "customer profile" in the MyTests class:

use Test::More;
use Test::Routine::Util;

$ENV{TEST_METHOD} = 'customer profile';
run_tests('one test', 'MyTests');
done_testing;

to run all tests with "customer" in the name:

use Test::More;
use Test::Routine::Util;

$ENV{TEST_METHOD}= '.*customer.*';
run_tests('some tests', 'MyTests');
done_testing;

if you specify an invalid regular expression, your tests will not be run:

use Test::More;
use Test::Routine::Util

$ENV{TEST_METHOD} = 'C++'
run_tests('invalid', 'MyTests');
done_testing;

when you run it:

    1..0
    # No tests run!
not ok 1 - No tests run for subtest "invalid"

💀 yep. that's what happens. choose your regex wisely, queen.

---

🐪 PERL VERSION 🐪

this module should work on any version of perl still receiving updates from the Perl 5 Porters. which means it should work on any version of perl released in the last two to three years. (that is: if the most recently released version is v5.40, then this module should work on both v5.40 and v5.38.) 🌈

although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. the version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. harsh? yes. true? also yes. 💅

👑 AUTHOR 👑

Ricardo Signes <cpan@semiotic.systems>

🌈 CONTRIBUTORS 🌈

• Alex White <VVu@geekfarm.org>
• Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
• gregor herrmann <gregoa@debian.org>
• Jesse Luehrs <doy@tozt.net>
• Matthew Horsfall <wolfsage@gmail.com>
• Ricardo Signes <rjbs@semiotic.systems>
• Yanick Champoux <yanick@babyl.dyndns.org>

look at that roster. legendary. all of them. 💜

📜 COPYRIGHT AND LICENSE 📜

this software is copyright (c) 2010 by Ricardo Signes.

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

---

and that's the whole page, babes 🫶 she came from perl v5.40.1, dated 2026-03-21, and her name on the shelf is Test::Routine(3pm). go write some roles and slay. 👑🌸💖