Test::Moose::More(3pm)

Export Groups

By default, this package exports all test functions. You can be more selective, however, and there are a number of export groups (aside from the default ":all") to help you achieve those dreams!

:all

All exportable functions.

:validate

"validate_attribute", "validate_class", "validate_role", "validate_thing"

meta_ok $thing

Tests $thing to see if it has a metaclass; $thing may be the class name or instance of the class you wish to check. Passes if $thing has a metaclass.

no_meta_ok $thing

Tests $thing to see if it does not have a metaclass; $thing may be the class name or instance of the class you wish to check. Passes if $thing does not have a metaclass.

does_ok $thing, < $role | \@roles >, [ $message ]

Checks to see if $thing does the given roles. $thing may be the class name or instance of the class you wish to check.

Note that the message will be taken verbatim unless it contains %s somewhere; this will be replaced with the name of the role being tested for.

does_not_ok $thing, < $role | \@roles >, [ $message ]

Checks to see if $thing does not do the given roles. $thing may be the class name or instance of the class you wish to check.

Note that the message will be taken verbatim unless it contains %s somewhere; this will be replaced with the name of the role being tested for.

has_attribute_ok $thing, $attribute_name, [ $message ]

Checks $thing for an attribute named $attribute_name; $thing may be a class name, instance, or role name.

has_method_ok $thing, @methods

Queries $thing's metaclass to see if $thing has the methods named in @methods.

Note: This does not include inherited methods; see "has_method" in Class::MOP::Class.

has_no_method_ok $thing, @methods

Queries $thing's metaclass to ensure $thing does not provide the methods named in @methods.

Note: This does not include inherited methods; see "has_method" in Class::MOP::Class.

has_method_from_anywhere_ok $thing, @methods

Queries $thing's metaclass to see if $thing has the methods named in @methods.

Note: This does include inherited methods; see "find_method_by_name" in Class::MOP::Class.

has_no_method_from_anywhere_ok $thing, @methods

Queries $thing's metaclass to ensure $thing does not provide the methods named in @methods.

Note: This does include inherited methods; see "find_method_by_name" in Class::MOP::Class.

method_from_pkg_ok $thing, $method, $orig_pkg

Given a thing (role, class, etc) and a method, test that it originally came from $orig_pkg.

method_not_from_pkg_ok $thing, $method, $orig_pkg

Given a thing (role, class, etc) and a method, test that it did not come from $orig_pkg.

method_is_accessor_ok $thing, $method

Given a thing (role, class, etc) and a method, test that the method is an accessor -- that is, it descends from Class::MOP::Method::Accessor.

method_is_not_accessor_ok $thing, $method

Given a thing (role, class, etc) and a method, test that the method is not an accessor -- that is, it does not descend from Class::MOP::Method::Accessor.

definition_context_ok $meta, \%dc

Validates the definition context of a metaclass instance. This is a strict comparison.

role_wraps_around_method_ok $role, @methods

Queries $role's metaclass to see if $role wraps the methods named in @methods with an around method modifier.

role_wraps_before_method_ok $role, @methods

Queries $role's metaclass to see if $role wraps the methods named in @methods with an before method modifier.

role_wraps_after_method_ok $role, @methods

Queries $role's metaclass to see if $role wraps the methods named in @methods with an after method modifier.

requires_method_ok $thing, @methods

Queries $thing's metaclass to see if $thing requires the methods named in @methods.

Note that this really only makes sense if $thing is a role.

does_not_require_method_ok $thing, @methods

Queries $thing's metaclass to ensure $thing does not require the methods named in @methods.

Note that this really only makes sense if $thing is a role.

is_immutable_ok $thing

Passes if $thing is immutable.

is_not_immutable_ok $thing

Passes if $thing is not immutable; that is, is mutable.

is_pristine_ok $thing

Passes if $thing is pristine. See "is_pristine" in Class::MOP::Class.

is_not_pristine_ok $thing

Passes if $thing is not pristine. See "is_pristine" in Class::MOP::Class.

is_role_ok $thing

Passes if "$thing's" metaclass is a Moose::Meta::Role.

is_class_ok $thing

Passes if "$thing's" metaclass is a Moose::Meta::Class.

is_anon_ok $thing

Passes if $thing is "anonymous".

is_not_anon_ok $thing

Passes if $thing is not "anonymous".

check_sugar_removed_ok $thing

Ensures that all the standard Moose sugar is no longer directly callable on a given package.

check_sugar_ok $thing

Checks and makes sure a class/etc can still do all the standard Moose sugar.

does_metaroles_ok $thing => { $mop => [ @traits ], ... };

Validate the metaclasses associated with a class/role metaclass.

e.g., if I wanted to validate that the attribute trait for MooseX::AttributeShortcuts is actually applied, I could do this:

    { package TestClass; use Moose; use MooseX::AttributeShortcuts; }
    use Test::Moose::More;
    use Test::More;
    does_metaroles_ok TestClass => {
       attribute => ['MooseX::AttributeShortcuts::Trait::Attribute'],
    };
    done_testing;

This function will accept either class or role metaclasses for $thing.

The MOPs available for classes (Moose::Meta::Class) are:

class

attribute

method

wrapped_method

instance

constructor

destructor

The MOPs available for roles (Moose::Meta::Role) are:

role

attribute

method

required_method

wrapped_method

conflicting_method

application_to_class

application_to_role

application_to_instance

applied_attribute

Note! Neither this function nor "does_not_metaroles_ok()" attempts to validate that the MOP type passed in is a member of the above lists. There's no gain here in implementing such a check, and a negative to be had: specifying an invalid MOP type will result in immediate explosions, while it's entirely possible other MOP types will be added (either to core, via traits, or "let's subclass Moose::Meta::Class/etc and implement something new").

does_not_metaroles_ok $thing => { $mop => [ @traits ], ... };

As with "does_metaroles_ok", but test that the metaroles are not consumed, a la "does_not_ok".

attribute_options_ok

Validates that an attribute is set up as expected; like "validate_attribute()", but only concerns itself with attribute options.

Note that some of these options will skip if used against attributes defined in a role.

•

"-subtest => 'subtest name...'"

If set, all tests run (save the first, "does this thing even have this attribute?" test) will be wrapped in a subtest, the name of which will be whatever "-subtest" is set to.

•

"is => ro|rw"

Tests for reader/writer options set as one would expect.

•

"isa => ..."

Validates that the attribute requires its value to be a given type.

•

"does => ..."

Validates that the attribute requires its value to do a given role.

•

"builder => '...'"

Validates that the attribute expects the method name given to be its builder.

•

"default => ..."

Validates that the attribute has the given default.

•

"init_arg => '...'"

Validates that the attribute has the given initial argument name.

•

"lazy => 0|1"

Validates that the attribute is/isn't lazy.

•

"required => 0|1"

Validates that setting the attribute's value is/isn't required.

validate_thing

Runs a bunch of tests against the given $thing, as defined:

    validate_thing $thing => (
        attributes => [ ... ],
        methods    => [ ... ],
        isa        => [ ... ],
        # ensures sugar is/is-not present
        sugar      => 0,
        # ensures $thing does these roles
        does       => [ ... ],
        # ensures $thing does not do these roles
        does_not   => [ ... ],
    );

$thing can be the name of a role or class, an object instance, or a metaclass.

•

"-subtest => 'subtest name...'"

If set, all tests run will be wrapped in a subtest, the name of which will be whatever "-subtest" is set to.

•

"isa => [ ... ]"

A list of superclasses thing should have.

•

"anonymous => 0|1"

Check to see if the class is/isn't anonymous.

•

"does => [ ... ]"

A list of roles the thing should do.

•

"does_not => [ ... ]"

A list of roles the thing should not do.

•

"attributes => [ ... ]"

The attributes list specified here is in the form of a list of names, each optionally followed by a hashref of options to test the attribute for; this hashref takes the same arguments "validate_attribute" does. e.g.:

    validate_thing $thing => (
        attributes => [
            'foo',
            'bar',
            baz => { is => 'ro', ... },
            'bip',
        ],
    );

•

"methods => [ ... ]"

A list of methods the thing should have; see "has_method_ok".

•

"no_methods => [ ... ]"

A list of methods the thing should not have; see "has_no_method_ok".

•

"sugar => 0|1"

Ensure that thing can/cannot do the standard Moose sugar.

•

"metaclasses => { $mop => { ... }, ... }"

Validates this thing's metaclasses: that is, given a MOP type (e.g. class, attribute, method, ...) and a hashref, find the associated metaclass of the given type and invoke "validate_thing" on it, using the hashref as options for "validate_thing()".

e.g.

    validate_thing 'TestClass' => (
        metaclasses  => {
            attribute => {
                isa  => [ 'Moose::Meta::Attribute' ],
                does => [ 'MetaRole::attribute'    ],
            },
        },
    );

...yields:

    # Subtest: Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1
        ok 1 - TestClass's attribute metaclass has a metaclass
        ok 2 - TestClass's attribute metaclass is a Moose class
        ok 3 - TestClass's attribute metaclass isa Moose::Meta::Attribute
        ok 4 - TestClass's attribute metaclass does MetaRole::attribute
        1..4
    ok 1 - Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1

Note that "validate_class()" and "validate_role()" implement this using "class_metaclasses" and "role_metaclasses", respectively.

validate_role

The same as "validate_thing()", but ensures $thing is a role, and allows for additional role-specific tests.

    validate_role $thing => (
        required_methods => [ ... ],
        # ...and all other options from validate_thing()
    );

•

"-compose => 0|1"

When true, attempt to compose the role into an anonymous class, then use it to run "validate_class". The options we're given are passed to "validate_class()" directly, except that any "required_methods" entry is removed and its contents pushed onto "methods". (A stub method for each entry in "required_methods" will also be created in the new class.)

e.g.:

    ok 1 - TestRole has a metaclass
    ok 2 - TestRole is a Moose role
    ok 3 - TestRole requires method blargh
    ok 4 - TestRole does TestRole
    ok 5 - TestRole does not do TestRole::Two
    ok 6 - TestRole has method method1
    ok 7 - TestRole has an attribute named bar
    # Subtest: role composed into Moose::Meta::Class::__ANON__::SERIAL::1
        ok 1 - TestRole's composed class has a metaclass
        ok 2 - TestRole's composed class is a Moose class
        ok 3 - TestRole's composed class does TestRole
        ok 4 - TestRole's composed class does not do TestRole::Two
        ok 5 - TestRole's composed class has method method1
        ok 6 - TestRole's composed class has method blargh
        ok 7 - TestRole's composed class has an attribute named bar
        1..7
    ok 8 - role composed into Moose::Meta::Class::__ANON__::SERIAL::1
    1..8

•

"-subtest => 'subtest name...'"

If set, all tests run will be wrapped in a subtest, the name of which will be whatever "-subtest" is set to.

•

"required_methods => [ ... ]"

A list of methods the role requires a consuming class to supply.

•

"before => [ ... ]"

A list of methods the role expects to wrap before, on application to a class.

See "before" in Moose for information on before method modifiers.

•

"around => [ ... ]"

A list of methods the role expects to wrap around, on application to a class.

See "around" in Moose for information on around method modifiers.

•

"after => [ ... ]"

A list of methods the role expects to wrap after, on application to a class.

See "after" in Moose for information on after method modifiers.

•

"role_metaroles => { $mop => [ $role, ... ], ... }"

Checks metaclasses to ensure the given metaroles are applied. See "does_metaroles_ok".

•

"no_role_metaroles => { $mop => [ $role, ... ], ... }"

Checks metaclasses to ensure the given metaroles are applied. See "does_not_metaroles_ok".

•

"role_metaclasses => { $mop => { ... }, ... }"

Validates this role's metaclasses: that is, given a MOP type (e.g. role, attribute, method, ...) and a hashref, find the associated metaclass of the given type and invoke "validate_thing" on it, using the hashref as options for "validate_thing()".

e.g.

    validate_role 'TestRole' => (
        metaclasses  => {
            attribute => {
                isa  => [ 'Moose::Meta::Attribute' ],
                does => [ 'MetaRole::attribute'    ],
            },
        },
    );

...yields:

    # Subtest: Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1
        ok 1 - TestRole's attribute metaclass has a metaclass
        ok 2 - TestRole's attribute metaclass is a Moose class
        ok 3 - TestRole's attribute metaclass isa Moose::Meta::Attribute
        ok 4 - TestRole's attribute metaclass does MetaRole::attribute
        1..4
    ok 1 - Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1

Note that "validate_class()" and "validate_role()" implement this using "class_metaclasses" and "role_metaclasses", respectively.

•

"class_metaclasses => { $mop => { ... }, ... }"

As with role_metaclasses, above, except that this option is only used if "-compose" is also specified.

validate_class

The same as "validate_thing()", but ensures $thing is a class, and allows for additional class-specific tests.

    validate_class $thing => (
        isa  => [ ... ],
        attributes => [ ... ],
        methods    => [ ... ],
        # ensures sugar is/is-not present
        sugar      => 0,
        # ensures $thing does these roles
        does       => [ ... ],
        # ensures $thing does not do these roles
        does_not   => [ ... ],
        # ...and all other options from validate_thing()
    );

•

"-subtest => 'subtest name...'"

If set, all tests run will be wrapped in a subtest, the name of which will be whatever "-subtest" is set to.

•

"immutable => 0|1"

Checks the class to see if it is/isn't immutable.

•

"class_metaroles => { $mop => [ $role, ... ], ... }"

Checks metaclasses to ensure the given metaroles are applied. See "does_metaroles_ok".

•

"no_class_metaroles => { $mop => [ $role, ... ], ... }"

Checks metaclasses to ensure the given metaroles are applied. See "does_not_metaroles_ok".

•

"class_metaclasses => { $mop => { ... }, ... }"

Validates this class' metaclasses: that is, given a MOP type (e.g. role, attribute, method, ...) and a hashref, find the associated metaclass of the given type and invoke "validate_thing" on it, using the hashref as options for "validate_thing()".

e.g.

    validate_class 'TestClass' => (
        metaclasses  => {
            attribute => {
                isa  => [ 'Moose::Meta::Attribute' ],
                does => [ 'MetaRole::attribute'    ],
            },
        },
    );

...yields:

    ok 1 - TestClass has a metaclass
    ok 2 - TestClass is a Moose class
    # Subtest: Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1
        ok 1 - TestClass's attribute metaclass has a metaclass
        ok 2 - TestClass's attribute metaclass is a Moose class
        ok 3 - TestClass's attribute metaclass isa Moose::Meta::Attribute
        ok 4 - TestClass's attribute metaclass does MetaRole::attribute
        1..4
    ok 3 - Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1

validate_attribute

"validate_attribute()" allows you to test how an attribute looks once built and attached to a class.

Let's say you have an attribute defined like this:

    has foo => (
        traits  => [ 'TestRole' ],
        is      => 'ro',
        isa     => 'Int',
        builder => '_build_foo',
        lazy    => 1,
    );

You can use "validate_attribute()" to ensure that it's built out in the way you expect:

    validate_attribute TestClass => foo => (
        # tests the attribute metaclass instance to ensure it does the roles
        -does => [ 'TestRole' ],
        # tests the attribute metaclass instance's inheritance
        -isa  => [ 'Moose::Meta::Attribute' ], # for demonstration's sake
        traits   => [ 'TestRole' ],
        isa      => 'Int',
        does     => 'Bar',
        handles  => { },
        reader   => 'foo',
        builder  => '_build_foo',
        default  => undef,
        init_arg => 'foo',
        lazy     => 1,
        required => undef,
    );

Options passed to "validate_attribute()" prefixed with "-" test the attribute's metaclass instance rather than a setting on the attribute; that is, "-does" ensures that the metaclass does a particular role (e.g. MooseX::AttributeShortcuts), while "does" tests the setting of the attribute to require the value do a given role.

This function takes all the options "attribute_options_ok" takes, as well as the following:

•

"-subtest => 'subtest name...'"

If set, all tests run will be wrapped in a subtest, the name of which will be whatever "-subtest" is set to.