NAME
Test::Roo - Composable, reusable tests with roles and Moo
VERSION
version 1.002
SYNOPSIS
Define test behaviors and required fixtures in a role:
# t/lib/ObjectCreation.pm
package ObjectCreation;
use Test::Roo::Role; # loads Moo::Role and Test::More
requires 'class'; # we need this fixture
test 'object creation' => sub {
my $self = shift;
require_ok( $self->class );
my $obj = new_ok( $self->class );
};
1;
Provide fixtures and run tests from the .t file:
# t/test.t
use Test::Roo; # loads Moo and Test::More
use lib 't/lib';
# provide the fixture
has class => (
is => 'ro',
default => sub { "Digest::MD5" },
);
# specify behaviors to test
with 'ObjectCreation';
# give our subtests a pretty label
sub _build_description { "Testing " . shift->class }
# run the test with default fixture
run_me;
# run the test with different fixture
run_me( { class => "Digest::SHA1" } );
done_testing;
Result:
$ prove -lv t
t/test.t ..
ok 1 - require Digest::MD5;
ok 2 - The object isa Digest::MD5
1..2
ok 1 - object creation
1..1
ok 1 - Testing Digest::MD5
ok 1 - require Digest::SHA1;
ok 2 - The object isa Digest::SHA1
1..2
ok 1 - object creation
1..1
ok 2 - Testing Digest::SHA1
1..2
ok
All tests successful.
Files=1, Tests=2, 0 wallclock secs ( 0.02 usr 0.01 sys + 0.06 cusr 0.00 csys = 0.09 CPU)
Result: PASS
DESCRIPTION
This module allows you to compose Test::More tests from roles. It is
inspired by the excellent Test::Routine module, but uses Moo instead of
Moose. This gives most of the benefits without the need for Moose as a
test dependency.
Test files are Moo classes. You can define any needed test fixtures as
Moo attributes. You define tests as method modifiers -- similar in
concept to "subtest" in Test::More, but your test method will be passed
the test object for access to fixture attributes. You may compose any
Moo::Role into your test to define attributes, require particular
methods, or define tests.
This means that you can isolate test *behaviors* into roles which
require certain test *fixtures* in order to run. Your main test file
will provide the fixtures and compose the roles to run. This makes it
easy to reuse test behaviors.
For example, if you are creating tests for Awesome::Module, you could
create the test behaviors as Awesome::Module::Test::Role and distribute
it with your module. If another distribution subclasses Awesome::Module,
it can compose the Awesome::Module::Test::Role behavior for its own
tests.
No more copying and pasting tests from a super class! Superclasses
define and share their tests. Subclasses provide their own fixtures and
run the tests.
USAGE
Importing Test::Roo also loads Moo (which gives you strictures with
fatal warnings and other goodies) and makes the current package a
subclass of Test::Roo::Class.
Importing also loads Test::More. No test plan is used. The
"done_testing" function must be used at the end of every test file. Any
import arguments are passed through to Test::More's "import" method.
See also Test::Roo::Role for test role usage.
Creating fixtures
You can create fixtures with normal Moo syntax. You can even make them
lazy if you want:
has fixture => (
is => 'lazy'
);
sub _build_fixture { ... }
This becomes really useful with Test::Roo::Role. A role could define the
attribute and require the builder method to be provided by the main test
class.
Composing test roles
You can use roles to define units of test behavior and then compose them
into your test class using the "with" function. Test roles may define
attributes, declare tests, require certain methods and anything else you
can regularly do with roles.
use Test::Roo;
with 'MyTestRole1', 'MyTestRole2';
See Test::Roo::Role and the Test::Roo::Cookbook for details and
examples.
Setup and teardown
You can add method modifiers around the "setup" and "teardown" methods
and these will be run before tests begin and after tests finish
(respectively).
before setup => sub { ... };
after teardown => sub { ... };
You can also add method modifiers around "each_test", which will be run
before and after every individual test. You could use these to prepare
or reset a fixture.
has fixture => ( is => 'lazy, clearer => 1, predicate => 1 );
after each_test => sub { shift->clear_fixture };
Roles may also modify "setup", "teardown", and "each_test", so the order
that modifiers will be called will depend on when roles are composed. Be
careful with "each_test", though, because the global effect may make
composition more fragile.
You can call test functions in modifiers. For example, you could confirm
that something has been set up or cleaned up.
before each_test => sub { ok( ! shift->has_fixture ) };
Running tests
The simplest way to use Test::Roo with a single .t file is to let the
"main" package be the test class and call "run_me" in it:
# t/test.t
use Test::Roo; # loads Moo and Test::More
has class => (
is => 'ro',
default => sub { "Digest::MD5" },
);
test 'load class' => sub {
my $self = shift;
require_ok( $self->class );
}
run_me;
done_testing;
Calling "run_me(@args)" is equivalent to calling
"__PACKAGE__->run_tests(@args)" and runs tests for the current package.
You may specify an optional description or hash reference of constructor
arguments to customize the test object:
run_me( "load MD5" );
run_me( { class => "Digest::MD5" } );
run_me( "load MD5", { class => "Digest::MD5" } );
See Test::Roo::Class for more about the "run_tests" method.
Alternatively, you can create a separate package (in the test file or in
a separate .pm file) and run tests explicitly on that class.
# t/test.t
package MyTest;
use Test::Roo;
use lib 't/lib';
has class => (
is => 'ro',
required => 1,
);
with 'MyTestRole';
package main;
use strictures;
use Test::More;
for my $c ( qw/Digest::MD5 Digest::SHA/ ) {
MyTest->run_tests("Testing $c", { class => $c } );
}
done_testing;
EXPORTED FUNCTIONS
Loading Test::Roo exports subroutines into the calling package to
declare and run tests.
test
test $label => sub { ... };
The "test" function adds a subtest. The code reference will be called
with the test object as its only argument.
Tests are run in the order declared, so the order of tests from roles
will depend on when they are composed relative to other test
declarations.
run_me
run_me;
run_me( $description );
run_me( $init_args );
run_me( $description, $init_args );
The "run_me" function calls the "run_tests" method on the current
package and passes all arguments to that method. It takes a description
and/or a hash reference of constructor arguments.
DIFFERENCES FROM TEST::ROUTINE
While this module was inspired by Test::Routine, it is not a drop-in
replacement. Here is an overview of major differences:
* Test::Roo uses Moo; Test::Routine uses Moose
* Loading Test::Roo makes the importing package a class; in
Test::Routine it becomes a role
* Loading Test::Roo loads Test::More; Test::Routine does not
* In Test::Roo, "run_test" is a method; in Test::Routine it is a
function and takes arguments in a different order
* In Test::Roo, all role composition must be explicit using "with"; in
Test::Routine, the "run_tests" command can also compose roles
* In Test::Roo, test blocks become method modifiers hooked on an empty
method; in Test::Routine, they become methods run via introspection
* In Test::Roo, setup and teardown are done by modifying "setup" and
"teardown" methods; in Test::Routine they are done by modifying
"run_test"
SUPPORT
Bugs / Feature Requests
Please report any bugs or feature requests through the issue tracker at
<https://github.com/dagolden/Test-Roo/issues>. You will be notified
automatically of any progress on your issue.
Source Code
This is open source software. The code repository is available for
public review and contribution under the terms of the license.
<https://github.com/dagolden/Test-Roo>
git clone https://github.com/dagolden/Test-Roo.git
AUTHOR
David Golden <dagolden@cpan.org>
CONTRIBUTOR
Diab Jerius <djerius@gmail.com>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2013 by David Golden.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004