Provided by: libtest-routine-perl_0.031-1_all 
NAME
Test::Routine - composable units of assertion
VERSION
version 0.031
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
Test::Routine is a very simple framework for writing your tests as composable units of assertion. In
other words: roles.
For a walkthrough of tests written with Test::Routine, see Test::Routine::Manual::Demo.
Test::Routine is similar to Test::Class in some ways. These similarities are largely superficial, but
the idea of "tests bound together in reusable units" is a useful one to understand when coming to
Test::Routine. If you are already familiar with Test::Class, it is the differences rather than the
similarities that will be more important to understand. If you are not familiar with Test::Class, there
is no need to understand it prior to using Test::Routine.
On the other hand, 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. The Moose::Manual is an excellent resource for learning Moose, and has
links to other online tutorials and documentation.
The Concepts
The Basics of Using Test::Routine
There actually isn't much to Test::Routine other than the basics. It does not provide many complex
features, instead delegating almost everything to the Moose object system.
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 an acceptable target for turning into a test routine, meaning that you may 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.
"test" may also be given a different name for the installed method and the test description. This isn't
usually needed, but can make things clearer when 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 will 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 have
already created a class that composes test routines and have built an instance of it.
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. 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.
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. 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.
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.
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"
PERL VERSION
This module should work on any version of perl still receiving updates from the Perl 5 Porters. This
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.
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@cpan.org>
• Ricardo Signes <rjbs@semiotic.systems>
• Ricardo Signes <rjbs@users.noreply.github.com>
• Yanick Champoux <yanick@babyl.dyndns.org>
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.