1Test::Moose::More(3) User Contributed Perl Documentation Test::Moose::More(3)
2
6 Test::Moose::More - More tools for testing Moose packages
7
9 This document describes version 0.050 of Test::Moose::More - released
10 September 20, 2017 as part of Test-Moose-More.
11
13 use Test::Moose::More;
14 is_class_ok 'Some::Class';
16 is_role_ok 'Some::Role';
17 has_method_ok 'Some::Class', 'foo';
18 # ... etc
20
22 This package contains a number of additional tests that can be employed
23 against Moose classes/roles. It is intended to replace Test::Moose in
24 your tests, and re-exports any tests that it has and we do not, yet.
25 Export Groups
27 By default, this package exports all test functions. You can be more
28 selective, however, and there are a number of export groups (aside from
29 the default ":all") to help you achieve those dreams!
30 :all
32 All exportable functions.
33 :validate
35 "validate_attribute", "validate_class", "validate_role",
36 "validate_thing"
37
39 meta_ok $thing
40 Tests $thing to see if it has a metaclass; $thing may be the class name
41 or instance of the class you wish to check. Passes if $thing has a
42 metaclass.
43 no_meta_ok $thing
45 Tests $thing to see if it does not have a metaclass; $thing may be the
46 class name or instance of the class you wish to check. Passes if
47 $thing does not have a metaclass.
48 does_ok $thing, < $role | \@roles >, [ $message ]
50 Checks to see if $thing does the given roles. $thing may be the class
51 name or instance of the class you wish to check.
52 Note that the message will be taken verbatim unless it contains %s
54 somewhere; this will be replaced with the name of the role being tested
55 for.
56 does_not_ok $thing, < $role | \@roles >, [ $message ]
58 Checks to see if $thing does not do the given roles. $thing may be the
59 class name or instance of the class you wish to check.
60 Note that the message will be taken verbatim unless it contains %s
62 somewhere; this will be replaced with the name of the role being tested
63 for.
64 has_attribute_ok $thing, $attribute_name, [ $message ]
66 Checks $thing for an attribute named $attribute_name; $thing may be a
67 class name, instance, or role name.
68 has_method_ok $thing, @methods
70 Queries $thing's metaclass to see if $thing has the methods named in
71 @methods.
72 Note: This does not include inherited methods; see "has_method" in
74 Class::MOP::Class.
75 has_no_method_ok $thing, @methods
77 Queries $thing's metaclass to ensure $thing does not provide the
78 methods named in @methods.
79 Note: This does not include inherited methods; see "has_method" in
81 Class::MOP::Class.
82 has_method_from_anywhere_ok $thing, @methods
84 Queries $thing's metaclass to see if $thing has the methods named in
85 @methods.
86 Note: This does include inherited methods; see "find_method_by_name" in
88 Class::MOP::Class.
89 has_no_method_from_anywhere_ok $thing, @methods
91 Queries $thing's metaclass to ensure $thing does not provide the
92 methods named in @methods.
93 Note: This does include inherited methods; see "find_method_by_name" in
95 Class::MOP::Class.
96 method_from_pkg_ok $thing, $method, $orig_pkg
98 Given a thing (role, class, etc) and a method, test that it originally
99 came from $orig_pkg.
100 method_not_from_pkg_ok $thing, $method, $orig_pkg
102 Given a thing (role, class, etc) and a method, test that it did not
103 come from $orig_pkg.
104 method_is_accessor_ok $thing, $method
106 Given a thing (role, class, etc) and a method, test that the method is
107 an accessor -- that is, it descends from Class::MOP::Method::Accessor.
108 method_is_not_accessor_ok $thing, $method
110 Given a thing (role, class, etc) and a method, test that the method is
111 not an accessor -- that is, it does not descend from
112 Class::MOP::Method::Accessor.
113 definition_context_ok $meta, \%dc
115 Validates the definition context of a metaclass instance. This is a
116 strict comparison.
117 role_wraps_around_method_ok $role, @methods
119 Queries $role's metaclass to see if $role wraps the methods named in
120 @methods with an around method modifier.
121 role_wraps_before_method_ok $role, @methods
123 Queries $role's metaclass to see if $role wraps the methods named in
124 @methods with an before method modifier.
125 role_wraps_after_method_ok $role, @methods
127 Queries $role's metaclass to see if $role wraps the methods named in
128 @methods with an after method modifier.
129 requires_method_ok $thing, @methods
131 Queries $thing's metaclass to see if $thing requires the methods named
132 in @methods.
133 Note that this really only makes sense if $thing is a role.
135 does_not_require_method_ok $thing, @methods
137 Queries $thing's metaclass to ensure $thing does not require the
138 methods named in @methods.
139 Note that this really only makes sense if $thing is a role.
141 is_immutable_ok $thing
143 Passes if $thing is immutable.
144 is_not_immutable_ok $thing
146 Passes if $thing is not immutable; that is, is mutable.
147 is_pristine_ok $thing
149 Passes if $thing is pristine. See "is_pristine" in Class::MOP::Class.
150 is_not_pristine_ok $thing
152 Passes if $thing is not pristine. See "is_pristine" in
153 Class::MOP::Class.
154 is_role_ok $thing
156 Passes if "$thing's" metaclass is a Moose::Meta::Role.
157 is_class_ok $thing
159 Passes if "$thing's" metaclass is a Moose::Meta::Class.
160 is_anon_ok $thing
162 Passes if $thing is "anonymous".
163 is_not_anon_ok $thing
165 Passes if $thing is not "anonymous".
166 check_sugar_removed_ok $thing
168 Ensures that all the standard Moose sugar is no longer directly
169 callable on a given package.
170 check_sugar_ok $thing
172 Checks and makes sure a class/etc can still do all the standard Moose
173 sugar.
174 does_metaroles_ok $thing => { $mop => [ @traits ], ... };
176 Validate the metaclasses associated with a class/role metaclass.
177 e.g., if I wanted to validate that the attribute trait for
179 MooseX::AttributeShortcuts is actually applied, I could do this:
180 { package TestClass; use Moose; use MooseX::AttributeShortcuts; }
182 use Test::Moose::More;
183 use Test::More;
184 does_metaroles_ok TestClass => {
186 attribute => ['MooseX::AttributeShortcuts::Trait::Attribute'],
187 };
188 done_testing;
189 This function will accept either class or role metaclasses for $thing.
191 The MOPs available for classes (Moose::Meta::Class) are:
193 class
195 attribute
196 method
197 wrapped_method
198 instance
199 constructor
200 destructor
201 The MOPs available for roles (Moose::Meta::Role) are:
203 role
205 attribute
206 method
207 required_method
208 wrapped_method
209 conflicting_method
210 application_to_class
211 application_to_role
212 application_to_instance
213 applied_attribute
214 Note! Neither this function nor "does_not_metaroles_ok()" attempts to
216 validate that the MOP type passed in is a member of the above lists.
217 There's no gain here in implementing such a check, and a negative to be
218 had: specifying an invalid MOP type will result in immediate
219 explosions, while it's entirely possible other MOP types will be added
220 (either to core, via traits, or "let's subclass Moose::Meta::Class/etc
221 and implement something new").
222 does_not_metaroles_ok $thing => { $mop => [ @traits ], ... };
224 As with "does_metaroles_ok", but test that the metaroles are not
225 consumed, a la "does_not_ok".
226 attribute_options_ok
228 Validates that an attribute is set up as expected; like
229 "validate_attribute()", but only concerns itself with attribute
230 options.
231 Note that some of these options will skip if used against attributes
233 defined in a role.
234 • "-subtest => 'subtest name...'"
236 If set, all tests run (save the first, "does this thing even have
238 this attribute?" test) will be wrapped in a subtest, the name of
239 which will be whatever "-subtest" is set to.
240 • "is => ro|rw"
242 Tests for reader/writer options set as one would expect.
244 • "isa => ..."
246 Validates that the attribute requires its value to be a given type.
248 • "does => ..."
250 Validates that the attribute requires its value to do a given role.
252 • "builder => '...'"
254 Validates that the attribute expects the method name given to be
256 its builder.
257 • "default => ..."
259 Validates that the attribute has the given default.
261 • "init_arg => '...'"
263 Validates that the attribute has the given initial argument name.
265 • "lazy => 0|1"
267 Validates that the attribute is/isn't lazy.
269 • "required => 0|1"
271 Validates that setting the attribute's value is/isn't required.
273
275 validate_thing
276 Runs a bunch of tests against the given $thing, as defined:
277 validate_thing $thing => (
279 attributes => [ ... ],
281 methods => [ ... ],
282 isa => [ ... ],
283 # ensures sugar is/is-not present
285 sugar => 0,
286 # ensures $thing does these roles
288 does => [ ... ],
289 # ensures $thing does not do these roles
291 does_not => [ ... ],
292 );
293 $thing can be the name of a role or class, an object instance, or a
295 metaclass.
296 • "-subtest => 'subtest name...'"
298 If set, all tests run will be wrapped in a subtest, the name of
300 which will be whatever "-subtest" is set to.
301 • "isa => [ ... ]"
303 A list of superclasses thing should have.
305 • "anonymous => 0|1"
307 Check to see if the class is/isn't anonymous.
309 • "does => [ ... ]"
311 A list of roles the thing should do.
313 • "does_not => [ ... ]"
315 A list of roles the thing should not do.
317 • "attributes => [ ... ]"
319 The attributes list specified here is in the form of a list of
321 names, each optionally followed by a hashref of options to test the
322 attribute for; this hashref takes the same arguments
323 "validate_attribute" does. e.g.:
324 validate_thing $thing => (
326 attributes => [
328 'foo',
329 'bar',
330 baz => { is => 'ro', ... },
331 'bip',
332 ],
333 );
334 • "methods => [ ... ]"
336 A list of methods the thing should have; see "has_method_ok".
338 • "no_methods => [ ... ]"
340 A list of methods the thing should not have; see
342 "has_no_method_ok".
343 • "sugar => 0|1"
345 Ensure that thing can/cannot do the standard Moose sugar.
347 • "metaclasses => { $mop => { ... }, ... }"
349 Validates this thing's metaclasses: that is, given a MOP type (e.g.
351 class, attribute, method, ...) and a hashref, find the associated
352 metaclass of the given type and invoke "validate_thing" on it,
353 using the hashref as options for "validate_thing()".
354 e.g.
356 validate_thing 'TestClass' => (
358 metaclasses => {
359 attribute => {
360 isa => [ 'Moose::Meta::Attribute' ],
361 does => [ 'MetaRole::attribute' ],
362 },
363 },
364 );
365 ...yields:
367 # Subtest: Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1
369 ok 1 - TestClass's attribute metaclass has a metaclass
370 ok 2 - TestClass's attribute metaclass is a Moose class
371 ok 3 - TestClass's attribute metaclass isa Moose::Meta::Attribute
372 ok 4 - TestClass's attribute metaclass does MetaRole::attribute
373 1..4
374 ok 1 - Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1
375 Note that "validate_class()" and "validate_role()" implement this
377 using "class_metaclasses" and "role_metaclasses", respectively.
378 validate_role
380 The same as "validate_thing()", but ensures $thing is a role, and
381 allows for additional role-specific tests.
382 validate_role $thing => (
384 required_methods => [ ... ],
386 # ...and all other options from validate_thing()
388 );
389 • "-compose => 0|1"
391 When true, attempt to compose the role into an anonymous class,
393 then use it to run "validate_class". The options we're given are
394 passed to "validate_class()" directly, except that any
395 "required_methods" entry is removed and its contents pushed onto
396 "methods". (A stub method for each entry in "required_methods"
397 will also be created in the new class.)
398 e.g.:
400 ok 1 - TestRole has a metaclass
402 ok 2 - TestRole is a Moose role
403 ok 3 - TestRole requires method blargh
404 ok 4 - TestRole does TestRole
405 ok 5 - TestRole does not do TestRole::Two
406 ok 6 - TestRole has method method1
407 ok 7 - TestRole has an attribute named bar
408 # Subtest: role composed into Moose::Meta::Class::__ANON__::SERIAL::1
409 ok 1 - TestRole's composed class has a metaclass
410 ok 2 - TestRole's composed class is a Moose class
411 ok 3 - TestRole's composed class does TestRole
412 ok 4 - TestRole's composed class does not do TestRole::Two
413 ok 5 - TestRole's composed class has method method1
414 ok 6 - TestRole's composed class has method blargh
415 ok 7 - TestRole's composed class has an attribute named bar
416 1..7
417 ok 8 - role composed into Moose::Meta::Class::__ANON__::SERIAL::1
418 1..8
419 • "-subtest => 'subtest name...'"
421 If set, all tests run will be wrapped in a subtest, the name of
423 which will be whatever "-subtest" is set to.
424 • "required_methods => [ ... ]"
426 A list of methods the role requires a consuming class to supply.
428 • "before => [ ... ]"
430 A list of methods the role expects to wrap before, on application
432 to a class.
433 See "before" in Moose for information on before method modifiers.
435 • "around => [ ... ]"
437 A list of methods the role expects to wrap around, on application
439 to a class.
440 See "around" in Moose for information on around method modifiers.
442 • "after => [ ... ]"
444 A list of methods the role expects to wrap after, on application to
446 a class.
447 See "after" in Moose for information on after method modifiers.
449 • "role_metaroles => { $mop => [ $role, ... ], ... }"
451 Checks metaclasses to ensure the given metaroles are applied. See
453 "does_metaroles_ok".
454 • "no_role_metaroles => { $mop => [ $role, ... ], ... }"
456 Checks metaclasses to ensure the given metaroles are applied. See
458 "does_not_metaroles_ok".
459 • "role_metaclasses => { $mop => { ... }, ... }"
461 Validates this role's metaclasses: that is, given a MOP type (e.g.
463 role, attribute, method, ...) and a hashref, find the associated
464 metaclass of the given type and invoke "validate_thing" on it,
465 using the hashref as options for "validate_thing()".
466 e.g.
468 validate_role 'TestRole' => (
470 metaclasses => {
471 attribute => {
472 isa => [ 'Moose::Meta::Attribute' ],
473 does => [ 'MetaRole::attribute' ],
474 },
475 },
476 );
477 ...yields:
479 # Subtest: Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1
481 ok 1 - TestRole's attribute metaclass has a metaclass
482 ok 2 - TestRole's attribute metaclass is a Moose class
483 ok 3 - TestRole's attribute metaclass isa Moose::Meta::Attribute
484 ok 4 - TestRole's attribute metaclass does MetaRole::attribute
485 1..4
486 ok 1 - Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1
487 Note that "validate_class()" and "validate_role()" implement this
489 using "class_metaclasses" and "role_metaclasses", respectively.
490 • "class_metaclasses => { $mop => { ... }, ... }"
492 As with role_metaclasses, above, except that this option is only
494 used if "-compose" is also specified.
495 validate_class
497 The same as "validate_thing()", but ensures $thing is a class, and
498 allows for additional class-specific tests.
499 validate_class $thing => (
501 isa => [ ... ],
503 attributes => [ ... ],
505 methods => [ ... ],
506 # ensures sugar is/is-not present
508 sugar => 0,
509 # ensures $thing does these roles
511 does => [ ... ],
512 # ensures $thing does not do these roles
514 does_not => [ ... ],
515 # ...and all other options from validate_thing()
517 );
518 • "-subtest => 'subtest name...'"
520 If set, all tests run will be wrapped in a subtest, the name of
522 which will be whatever "-subtest" is set to.
523 • "immutable => 0|1"
525 Checks the class to see if it is/isn't immutable.
527 • "class_metaroles => { $mop => [ $role, ... ], ... }"
529 Checks metaclasses to ensure the given metaroles are applied. See
531 "does_metaroles_ok".
532 • "no_class_metaroles => { $mop => [ $role, ... ], ... }"
534 Checks metaclasses to ensure the given metaroles are applied. See
536 "does_not_metaroles_ok".
537 • "class_metaclasses => { $mop => { ... }, ... }"
539 Validates this class' metaclasses: that is, given a MOP type (e.g.
541 role, attribute, method, ...) and a hashref, find the associated
542 metaclass of the given type and invoke "validate_thing" on it,
543 using the hashref as options for "validate_thing()".
544 e.g.
546 validate_class 'TestClass' => (
548 metaclasses => {
549 attribute => {
550 isa => [ 'Moose::Meta::Attribute' ],
551 does => [ 'MetaRole::attribute' ],
552 },
553 },
554 );
555 ...yields:
557 ok 1 - TestClass has a metaclass
559 ok 2 - TestClass is a Moose class
560 # Subtest: Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1
561 ok 1 - TestClass's attribute metaclass has a metaclass
562 ok 2 - TestClass's attribute metaclass is a Moose class
563 ok 3 - TestClass's attribute metaclass isa Moose::Meta::Attribute
564 ok 4 - TestClass's attribute metaclass does MetaRole::attribute
565 1..4
566 ok 3 - Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1
567 validate_attribute
569 "validate_attribute()" allows you to test how an attribute looks once
570 built and attached to a class.
571 Let's say you have an attribute defined like this:
573 has foo => (
575 traits => [ 'TestRole' ],
576 is => 'ro',
577 isa => 'Int',
578 builder => '_build_foo',
579 lazy => 1,
580 );
581 You can use "validate_attribute()" to ensure that it's built out in the
583 way you expect:
584 validate_attribute TestClass => foo => (
586 # tests the attribute metaclass instance to ensure it does the roles
588 -does => [ 'TestRole' ],
589 # tests the attribute metaclass instance's inheritance
590 -isa => [ 'Moose::Meta::Attribute' ], # for demonstration's sake
591 traits => [ 'TestRole' ],
593 isa => 'Int',
594 does => 'Bar',
595 handles => { },
596 reader => 'foo',
597 builder => '_build_foo',
598 default => undef,
599 init_arg => 'foo',
600 lazy => 1,
601 required => undef,
602 );
603 Options passed to "validate_attribute()" prefixed with "-" test the
605 attribute's metaclass instance rather than a setting on the attribute;
606 that is, "-does" ensures that the metaclass does a particular role
607 (e.g. MooseX::AttributeShortcuts), while "does" tests the setting of
608 the attribute to require the value do a given role.
609 This function takes all the options "attribute_options_ok" takes, as
611 well as the following:
612 • "-subtest => 'subtest name...'"
614 If set, all tests run will be wrapped in a subtest, the name of
616 which will be whatever "-subtest" is set to.
617
619 Please see those modules/websites for more information related to this
620 module.
621 • Test::Moose
623
625 Please report any bugs or feature requests on the bugtracker website
626 <https://github.com/RsrchBoy/Test-Moose-More/issues>
627 When submitting a bug or request, please include a test-file or a patch
629 to an existing test-file that illustrates the bug or desired feature.
630
632 Chris Weyl <cweyl@alumni.drew.edu>
633
635 • Chad Granum <chad.granum@dreamhost.com>
636 • Karen Etheridge <ether@cpan.org>
638
640 This software is Copyright (c) 2017, 2016, 2015, 2014, 2013, 2012 by
641 Chris Weyl.
642 This is free software, licensed under:
644 The GNU Lesser General Public License, Version 2.1, February 1999
646perl v5.32.1 2021-01-27 Test::Moose::More(3)