Test::...e::More(3pm)

📦
version 0.050 · 5 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Test::Moose::More — more tools for testing Moose packages 💖

(that's the Test::Moose::More(3pm) page, part of the User Contributed Perl Documentation — bestie, buckle up)

✨ VERSION ✨

This doc 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

okay so that's literally the whole vibe. importing, testing, slaying. 🫶

🦋 DESCRIPTION 🦋

This package is a whole little treasure chest 🎀 of extra tests you can run against your Moose classes and roles. It's meant to replace Test::Moose in your test suite — and it re-exports any tests that Test::Moose has that we don't have yet, so you're not losing anything, bestie. no cap.

🎀 Export Groups 🎀

By default this package exports all the test functions, because it's generous like that. 💖 But you can be picky — there are lots of export groups (besides the default :all) to help you live your dreams:

  • :all — every single exportable function. the whole squad. 👑
  • :validate — pulls in validate_attribute, validate_class, validate_role, and validate_thing.

🔥 TEST FUNCTIONS 🔥

💜 meta_ok $thing

Checks whether $thing has a metaclass. $thing can be the class name or an instance of the class you wanna poke at. Passes if $thing has a metaclass. ✨

💜 no_meta_ok $thing

Checks whether $thing does not have a metaclass. $thing can be a class name or an instance. Passes if $thing doesn't have one. 💀

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

Checks if $thing does the given role(s). $thing can be a class name or an instance of the class you're checking.

Heads up bestie: the message gets taken verbatim unless it has %s somewhere in it — if it does, that %s gets swapped out for the name of the role being tested. 🎯

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

Checks if $thing does not do the given role(s). $thing can be a class name or an instance.

Same deal: message is verbatim unless it contains %s, which gets replaced with the name of the role being tested. 🌸

💜 has_attribute_ok $thing, $attribute_name, [ $message ]

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

💜 has_method_ok $thing, @methods

Asks $thing's metaclass whether $thing has all 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

Asks $thing's metaclass to make sure $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

Asks $thing's metaclass whether $thing has the methods named in @methods.

👀 Note: this one does include inherited methods. see "find_method_by_name" in Class::MOP::Class.

💜 has_no_method_from_anywhere_ok $thing, @methods

Asks $thing's metaclass to make sure $thing does not provide the methods named in @methods.

👀 Note: this one 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, whatever) 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 — meaning it descends from Class::MOP::Method::Accessor. slay. 💅

💜 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, bestie. no wiggle room. 😤

💜 role_wraps_around_method_ok $role, @methods

Asks $role's metaclass whether $role wraps the methods named in @methods with an around method modifier. 🌈

💜 role_wraps_before_method_ok $role, @methods

Asks $role's metaclass whether $role wraps the methods named in @methods with a before method modifier. 🌈

💜 role_wraps_after_method_ok $role, @methods

Asks $role's metaclass whether $role wraps the methods named in @methods with an after method modifier. 🌈

💜 requires_method_ok $thing, @methods

Asks $thing's metaclass whether $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

Asks $thing's metaclass to make sure $thing does not require the methods named in @methods.

Again: only really 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 — i.e. it's 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

Makes sure 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 ], ... };

Validates 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() tries to validate that the MOP type you passed in is a member of the lists above. There's no gain in implementing such a check, and a negative: specifying an invalid MOP type will result in immediate explosions 💥, while it's entirely possible other MOP types will get added later (either to core, via traits, or because someone's like "let's subclass Moose::Meta::Class/etc and implement something new").

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

Same as does_metaroles_ok, but tests 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 it only cares about 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 (except the very first one, the "does this thing even have this attribute?" test) get wrapped up in a subtest, and the subtest gets whatever name -subtest is set to. 📦
  • is => ro|rw — tests for reader/writer options set the way you'd 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 given method name 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 whether the attribute is/isn't lazy. 😴
  • required => 0|1 — validates whether setting the attribute's value is/isn't required. ✅

🌈 VALIDATION METHODS 🌈

💖 validate_thing

Runs a whole 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 a class, an object instance, or a metaclass. 🎯

  • -subtest => 'subtest name...' — if set, all tests run get wrapped in a subtest, whose name is whatever -subtest is set to. 📦
  • isa => [ ... ] — a list of superclasses the thing should have. 👑👑
  • anonymous => 0|1 — check whether 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 => [ ... ] — this attributes list is a list of names, each optionally followed by a hashref of options to test that attribute for. That hashref takes the exact 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 — make sure the thing can/cannot do the standard Moose sugar. 🍬
  • metaclasses => { $mop => { ... }, ... } — validates this thing's metaclasses: given a MOP type (e.g. class, attribute, method, ...) and a hashref, it finds the associated metaclass of that type and invokes 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 💅

Okay bestie, validate_role is literally the same vibe as validate_thing(), but it makes sure $thing is a role, and it lets you do extra role-specific tests. Obsessed. 🫶

validate_role $thing => (

    required_methods => [ ... ],

    # ...and all other options from validate_thing()
);
  • -compose => 0|1 — when this is true, it tries to compose the role into an anonymous class, then uses that to run validate_class. The options you gave are passed straight to validate_class(), except any required_methods entry gets removed and its contents get pushed onto methods. (A stub method for each entry in required_methods will also be created in the new class.) no cap.

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 this is set, all the tests run get wrapped in a subtest, and the subtest's name is whatever -subtest is set to. iconic.
  • required_methods => [ ... ] — a list of methods the role requires a consuming class to supply. periodt.
  • before => [ ... ] — a list of methods the role expects to wrap before, on application to a class.

See before in Moose for info 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 info 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 info on after method modifiers. 🌸

  • role_metaroles => { $mop => [ $role, ... ], ... } — checks metaclasses to make sure the given metaroles are applied. See does_metaroles_ok.
  • no_role_metaroles => { $mop => [ $role, ... ], ... } — checks metaclasses to make sure 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, it finds the associated metaclass of the given type and invokes validate_thing on it, using the hashref as options for validate_thing(). iykyk.

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 => { ... }, ... } — same as role_metaclasses, above, except this option is only used if -compose is also specified. 💀

👑 validate_class 👑

validate_class is the same as validate_thing(), but it makes sure $thing is a class, and it allows extra class-specific tests. main character energy fr fr.

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 this is set, all the tests run get wrapped in a subtest, and the subtest's name is whatever -subtest is set to. 💅
  • immutable => 0|1 — checks the class to see if it is/isn't immutable. vibe check.
  • class_metaroles => { $mop => [ $role, ... ], ... } — checks metaclasses to make sure the given metaroles are applied. See does_metaroles_ok.
  • no_class_metaroles => { $mop => [ $role, ... ], ... } — checks metaclasses to make sure 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, it finds the associated metaclass of the given type and invokes validate_thing on it, using the hashref as options for validate_thing(). obsessed.

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() lets you test how an attribute looks once it's built and attached to a class. Slay. 💖

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 make sure 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() that are prefixed with - test the attribute's metaclass instance rather than a setting on the attribute; that is, -does makes sure 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. periodt.

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

  • -subtest => 'subtest name...' — if this is set, all the tests run get wrapped in a subtest, and the subtest's name is whatever -subtest is set to. 🎀

✨ SEE ALSO ✨

Please see those modules/websites for more info 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. bestie help them out 🙈

👑 AUTHOR 👑

Chris Weyl <cweyl@alumni.drew.edu>

🌈 CONTRIBUTORS 🌈

  • Chad Granum <chad.granum@dreamhost.com>
  • Karen Etheridge <ether@cpan.org>

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

okay bestie that's the whole page fr fr — this came from Test::...e::More(3pm) on perl v5.36.0, dated 2022-10-14. go forth and slay your tests 💅✨

📦 where this page comes from