NAME

MooseX::Test::Role - Test functions for Moose roles

SYNOPSIS

    use MooseX::Test::Role;
    use Test::More tests => 3;
    requires_ok('MyRole', qw/method1 method2/);
    my $consumer = consuming_object(
        'MyRole',
        methods => {
            method1 => 1,
            method2 => sub { shift->method1() },
        }
    );
    ok( $consumer->myrole_method );
    is( $consumer->method1, 1 );
    is( $consumer->method2, 1 );
    my $consuming_class = consuming_class('MyRole');
    ok( $consuming_class->class_method() );

DESCRIPTION

Provides functions for testing roles. Supports roles created with Moose::Role, Moo::Role or Role::Tiny.

BACKGROUND

Unit testing a role can be hard. A major problem is creating classes that consume the role.

One could side-step the problem entirely and just call the subroutines in the role's package directly. For example,

  Fooable->bar();

That only works until "Fooable" calls another method in the consuming class though. Mock objects are a tempting way to solve that problem:

  my $consumer = Test::MockObject->new();
  $consumer->set_always('baz', 1);
  Fooable::bar($consumer);

But if "Fooable::bar" happens to call another method in the role then the mock consumer will have to mock that method too.

A better way is to create a class to consume the role:

  package FooableTest;
  use Moose;
  with 'Fooable';
  sub required_method {}
  package main;
  my $consumer = FooableTest->new();
  $consumer->bar();

This can work well for some roles. Unfortunately, if several variations have to be tested, it may be necessary to create several consuming test classes, which gets tedious.

Moose can create anonymous classes which consume roles:

    my $consumer = Moose::Meta::Class->create_anon_class(
        roles   => ['Fooable'],
        methods => {
            required_method => sub {},
        }
    )->new_object();
    $consumer->bar();

This can still be tedious, especially for roles that require lots of methods. "MooseX::Test::Role" simply makes this easier to do.

EXPORTED FUNCTIONS

"consuming_class($role, methods =" \%methods)>

Creates a class which consumes the role, and returns it's package name.

$role must be the package name of a role. Moose::Role, Moo::Role and Role::Tiny are supported.

Any method required by the role will be stubbed. To override the default stub methods, or to add additional methods, specify the name and a coderef:

    consuming_class('MyRole',
        method1 => sub { 'one' },
        method2 => sub { 'two' },
        required_method => sub { 'required' },
    );
    

For methods that should just return a fixed scalar value, you can ommit the coderef.

    consuming_class('MyRole',
        method1    => 'one',
        method_uc1 => sub {
            my ($self) = @_;
            lc $self->one;
        },
    );
    

"consuming_object($role, methods =" \%methods)>

Creates a class which consumes the role, and returns an instance of it.

If the class does not have a new() method (which is commonly the case for Role::Tiny), then the package name will be returned instead.

See "consuming_class" for arguments. "consuming_object" is essentially equivalent to:

    consuming_class(@_)->new();
    

"consumer_of ($role, %methods)"

Alias of "consuming_object", without named arguments. This is left in for compatibility, new code should use "consuming_object".

"requires_ok ($role, @methods)"

Tests if role requires one or more methods.

GITHUB

Patches, comments or mean-spirited code reviews are all welcomed on GitHub:

<https://github.com/pboyd/MooseX-Test-Role>

AUTHOR

Paul Boyd <boyd.paul2@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Paul Boyd.

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