Provided by: libtest-routine-perl_0.030-1_all 
NAME
Test::Routine - composable units of assertion
VERSION
version 0.030
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>
• Ricardo Signes <rjbs@cpan.org>
• Ricardo Signes <rjbs@semiotic.systems>
• 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.