Provided by: libtest-moose-more-perl_0.050-3_all bug

NAME

       Test::Moose::More - More tools for testing Moose packages

VERSION

       This document describes version 0.050 of Test::Moose::More - released September 20, 2017
       as part of Test-Moose-More.

SYNOPSIS

           use Test::Moose::More;

           is_class_ok 'Some::Class';
           is_role_ok  'Some::Role';
           has_method_ok 'Some::Class', 'foo';

           # ... etc

DESCRIPTION

       This package contains a number of additional tests that can be employed against Moose
       classes/roles.  It is intended to replace Test::Moose in your tests, and re-exports any
       tests that it has and we do not, yet.

   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"

TEST FUNCTIONS

   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.

VALIDATION METHODS

   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.

SEE ALSO

       Please see those modules/websites for more information related to this module.

       •   Test::Moose

BUGS

       Please report any bugs or feature requests on the bugtracker website
       <https://github.com/RsrchBoy/Test-Moose-More/issues>

       When submitting a bug or request, please include a test-file or a patch to an existing
       test-file that illustrates the bug or desired feature.

AUTHOR

       Chris Weyl <cweyl@alumni.drew.edu>

CONTRIBUTORS

       •   Chad Granum <chad.granum@dreamhost.com>

       •   Karen Etheridge <ether@cpan.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2017, 2016, 2015, 2014, 2013, 2012 by Chris Weyl.

       This is free software, licensed under:

         The GNU Lesser General Public License, Version 2.1, February 1999