Test::Moose::More(3pm)

1Test::Moose::More(3)  User Contributed Perl Documentation Test::Moose::More(3)
2
3
4

NAME

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

VERSION

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

SYNOPSIS

13           use Test::Moose::More;
14
15           is_class_ok 'Some::Class';
16           is_role_ok  'Some::Role';
17           has_method_ok 'Some::Class', 'foo';
18
19           # ... etc
20

DESCRIPTION

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
26   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
31       :all
32           All exportable functions.
33
34       :validate
35           "validate_attribute", "validate_class", "validate_role",
36           "validate_thing"
37

TEST FUNCTIONS

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
44   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
49   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
53       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
57   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
61       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
65   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
69   has_method_ok $thing, @methods
70       Queries $thing's metaclass to see if $thing has the methods named in
71       @methods.
72
73       Note: This does not include inherited methods; see "has_method" in
74       Class::MOP::Class.
75
76   has_no_method_ok $thing, @methods
77       Queries $thing's metaclass to ensure $thing does not provide the
78       methods named in @methods.
79
80       Note: This does not include inherited methods; see "has_method" in
81       Class::MOP::Class.
82
83   has_method_from_anywhere_ok $thing, @methods
84       Queries $thing's metaclass to see if $thing has the methods named in
85       @methods.
86
87       Note: This does include inherited methods; see "find_method_by_name" in
88       Class::MOP::Class.
89
90   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
94       Note: This does include inherited methods; see "find_method_by_name" in
95       Class::MOP::Class.
96
97   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
101   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
105   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
109   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
114   definition_context_ok $meta, \%dc
115       Validates the definition context of a metaclass instance.  This is a
116       strict comparison.
117
118   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
122   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
126   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
130   requires_method_ok $thing, @methods
131       Queries $thing's metaclass to see if $thing requires the methods named
132       in @methods.
133
134       Note that this really only makes sense if $thing is a role.
135
136   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
140       Note that this really only makes sense if $thing is a role.
141
142   is_immutable_ok $thing
143       Passes if $thing is immutable.
144
145   is_not_immutable_ok $thing
146       Passes if $thing is not immutable; that is, is mutable.
147
148   is_pristine_ok $thing
149       Passes if $thing is pristine.  See "is_pristine" in Class::MOP::Class.
150
151   is_not_pristine_ok $thing
152       Passes if $thing is not pristine.  See "is_pristine" in
153       Class::MOP::Class.
154
155   is_role_ok $thing
156       Passes if "$thing's" metaclass is a Moose::Meta::Role.
157
158   is_class_ok $thing
159       Passes if "$thing's" metaclass is a Moose::Meta::Class.
160
161   is_anon_ok $thing
162       Passes if $thing is "anonymous".
163
164   is_not_anon_ok $thing
165       Passes if $thing is not "anonymous".
166
167   check_sugar_removed_ok $thing
168       Ensures that all the standard Moose sugar is no longer directly
169       callable on a given package.
170
171   check_sugar_ok $thing
172       Checks and makes sure a class/etc can still do all the standard Moose
173       sugar.
174
175   does_metaroles_ok $thing => { $mop => [ @traits ], ... };
176       Validate the metaclasses associated with a class/role metaclass.
177
178       e.g., if I wanted to validate that the attribute trait for
179       MooseX::AttributeShortcuts is actually applied, I could do this:
180
181           { package TestClass; use Moose; use MooseX::AttributeShortcuts; }
182           use Test::Moose::More;
183           use Test::More;
184
185           does_metaroles_ok TestClass => {
186              attribute => ['MooseX::AttributeShortcuts::Trait::Attribute'],
187           };
188           done_testing;
189
190       This function will accept either class or role metaclasses for $thing.
191
192       The MOPs available for classes (Moose::Meta::Class) are:
193
194       class
195       attribute
196       method
197       wrapped_method
198       instance
199       constructor
200       destructor
201
202       The MOPs available for roles (Moose::Meta::Role) are:
203
204       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
215       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
223   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
227   attribute_options_ok
228       Validates that an attribute is set up as expected; like
229       validate_attribute(), but only concerns itself with attribute options.
230
231       Note that some of these options will skip if used against attributes
232       defined in a role.
233
234       •   "-subtest => 'subtest name...'"
235
236           If set, all tests run (save the first, "does this thing even have
237           this attribute?" test) will be wrapped in a subtest, the name of
238           which will be whatever "-subtest" is set to.
239
240       •   "is => ro|rw"
241
242           Tests for reader/writer options set as one would expect.
243
244       •   "isa => ..."
245
246           Validates that the attribute requires its value to be a given type.
247
248       •   "does => ..."
249
250           Validates that the attribute requires its value to do a given role.
251
252       •   "builder => '...'"
253
254           Validates that the attribute expects the method name given to be
255           its builder.
256
257       •   "default => ..."
258
259           Validates that the attribute has the given default.
260
261       •   "init_arg => '...'"
262
263           Validates that the attribute has the given initial argument name.
264
265       •   "lazy => 0|1"
266
267           Validates that the attribute is/isn't lazy.
268
269       •   "required => 0|1"
270
271           Validates that setting the attribute's value is/isn't required.
272

VALIDATION METHODS

274   validate_thing
275       Runs a bunch of tests against the given $thing, as defined:
276
277           validate_thing $thing => (
278
279               attributes => [ ... ],
280               methods    => [ ... ],
281               isa        => [ ... ],
282
283               # ensures sugar is/is-not present
284               sugar      => 0,
285
286               # ensures $thing does these roles
287               does       => [ ... ],
288
289               # ensures $thing does not do these roles
290               does_not   => [ ... ],
291           );
292
293       $thing can be the name of a role or class, an object instance, or a
294       metaclass.
295
296       •   "-subtest => 'subtest name...'"
297
298           If set, all tests run will be wrapped in a subtest, the name of
299           which will be whatever "-subtest" is set to.
300
301       •   "isa => [ ... ]"
302
303           A list of superclasses thing should have.
304
305       •   "anonymous => 0|1"
306
307           Check to see if the class is/isn't anonymous.
308
309       •   "does => [ ... ]"
310
311           A list of roles the thing should do.
312
313       •   "does_not => [ ... ]"
314
315           A list of roles the thing should not do.
316
317       •   "attributes => [ ... ]"
318
319           The attributes list specified here is in the form of a list of
320           names, each optionally followed by a hashref of options to test the
321           attribute for; this hashref takes the same arguments
322           "validate_attribute" does.  e.g.:
323
324               validate_thing $thing => (
325
326                   attributes => [
327                       'foo',
328                       'bar',
329                       baz => { is => 'ro', ... },
330                       'bip',
331                   ],
332               );
333
334       •   "methods => [ ... ]"
335
336           A list of methods the thing should have; see "has_method_ok".
337
338       •   "no_methods => [ ... ]"
339
340           A list of methods the thing should not have; see
341           "has_no_method_ok".
342
343       •   "sugar => 0|1"
344
345           Ensure that thing can/cannot do the standard Moose sugar.
346
347       •   "metaclasses => { $mop => { ... }, ... }"
348
349           Validates this thing's metaclasses: that is, given a MOP type (e.g.
350           class, attribute, method, ...) and a hashref, find the associated
351           metaclass of the given type and invoke "validate_thing" on it,
352           using the hashref as options for validate_thing().
353
354           e.g.
355
356               validate_thing 'TestClass' => (
357                   metaclasses  => {
358                       attribute => {
359                           isa  => [ 'Moose::Meta::Attribute' ],
360                           does => [ 'MetaRole::attribute'    ],
361                       },
362                   },
363               );
364
365           ...yields:
366
367               # Subtest: Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1
368                   ok 1 - TestClass's attribute metaclass has a metaclass
369                   ok 2 - TestClass's attribute metaclass is a Moose class
370                   ok 3 - TestClass's attribute metaclass isa Moose::Meta::Attribute
371                   ok 4 - TestClass's attribute metaclass does MetaRole::attribute
372                   1..4
373               ok 1 - Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1
374
375           Note that validate_class() and validate_role() implement this using
376           "class_metaclasses" and "role_metaclasses", respectively.
377
378   validate_role
379       The same as validate_thing(), but ensures $thing is a role, and allows
380       for additional role-specific tests.
381
382           validate_role $thing => (
383
384               required_methods => [ ... ],
385
386               # ...and all other options from validate_thing()
387           );
388
389       •   "-compose => 0|1"
390
391           When true, attempt to compose the role into an anonymous class,
392           then use it to run "validate_class".  The options we're given are
393           passed to validate_class() directly, except that any
394           "required_methods" entry is removed and its contents pushed onto
395           "methods".  (A stub method for each entry in "required_methods"
396           will also be created in the new class.)
397
398           e.g.:
399
400               ok 1 - TestRole has a metaclass
401               ok 2 - TestRole is a Moose role
402               ok 3 - TestRole requires method blargh
403               ok 4 - TestRole does TestRole
404               ok 5 - TestRole does not do TestRole::Two
405               ok 6 - TestRole has method method1
406               ok 7 - TestRole has an attribute named bar
407               # Subtest: role composed into Moose::Meta::Class::__ANON__::SERIAL::1
408                   ok 1 - TestRole's composed class has a metaclass
409                   ok 2 - TestRole's composed class is a Moose class
410                   ok 3 - TestRole's composed class does TestRole
411                   ok 4 - TestRole's composed class does not do TestRole::Two
412                   ok 5 - TestRole's composed class has method method1
413                   ok 6 - TestRole's composed class has method blargh
414                   ok 7 - TestRole's composed class has an attribute named bar
415                   1..7
416               ok 8 - role composed into Moose::Meta::Class::__ANON__::SERIAL::1
417               1..8
418
419       •   "-subtest => 'subtest name...'"
420
421           If set, all tests run will be wrapped in a subtest, the name of
422           which will be whatever "-subtest" is set to.
423
424       •   "required_methods => [ ... ]"
425
426           A list of methods the role requires a consuming class to supply.
427
428       •   "before => [ ... ]"
429
430           A list of methods the role expects to wrap before, on application
431           to a class.
432
433           See "before" in Moose for information on before method modifiers.
434
435       •   "around => [ ... ]"
436
437           A list of methods the role expects to wrap around, on application
438           to a class.
439
440           See "around" in Moose for information on around method modifiers.
441
442       •   "after => [ ... ]"
443
444           A list of methods the role expects to wrap after, on application to
445           a class.
446
447           See "after" in Moose for information on after method modifiers.
448
449       •   "role_metaroles => { $mop => [ $role, ... ], ... }"
450
451           Checks metaclasses to ensure the given metaroles are applied.  See
452           "does_metaroles_ok".
453
454       •   "no_role_metaroles => { $mop => [ $role, ... ], ... }"
455
456           Checks metaclasses to ensure the given metaroles are applied.  See
457           "does_not_metaroles_ok".
458
459       •   "role_metaclasses => { $mop => { ... }, ... }"
460
461           Validates this role's metaclasses: that is, given a MOP type (e.g.
462           role, attribute, method, ...) and a hashref, find the associated
463           metaclass of the given type and invoke "validate_thing" on it,
464           using the hashref as options for validate_thing().
465
466           e.g.
467
468               validate_role 'TestRole' => (
469                   metaclasses  => {
470                       attribute => {
471                           isa  => [ 'Moose::Meta::Attribute' ],
472                           does => [ 'MetaRole::attribute'    ],
473                       },
474                   },
475               );
476
477           ...yields:
478
479               # Subtest: Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1
480                   ok 1 - TestRole's attribute metaclass has a metaclass
481                   ok 2 - TestRole's attribute metaclass is a Moose class
482                   ok 3 - TestRole's attribute metaclass isa Moose::Meta::Attribute
483                   ok 4 - TestRole's attribute metaclass does MetaRole::attribute
484                   1..4
485               ok 1 - Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1
486
487           Note that validate_class() and validate_role() implement this using
488           "class_metaclasses" and "role_metaclasses", respectively.
489
490       •   "class_metaclasses => { $mop => { ... }, ... }"
491
492           As with role_metaclasses, above, except that this option is only
493           used if "-compose" is also specified.
494
495   validate_class
496       The same as validate_thing(), but ensures $thing is a class, and allows
497       for additional class-specific tests.
498
499           validate_class $thing => (
500
501               isa  => [ ... ],
502
503               attributes => [ ... ],
504               methods    => [ ... ],
505
506               # ensures sugar is/is-not present
507               sugar      => 0,
508
509               # ensures $thing does these roles
510               does       => [ ... ],
511
512               # ensures $thing does not do these roles
513               does_not   => [ ... ],
514
515               # ...and all other options from validate_thing()
516           );
517
518       •   "-subtest => 'subtest name...'"
519
520           If set, all tests run will be wrapped in a subtest, the name of
521           which will be whatever "-subtest" is set to.
522
523       •   "immutable => 0|1"
524
525           Checks the class to see if it is/isn't immutable.
526
527       •   "class_metaroles => { $mop => [ $role, ... ], ... }"
528
529           Checks metaclasses to ensure the given metaroles are applied.  See
530           "does_metaroles_ok".
531
532       •   "no_class_metaroles => { $mop => [ $role, ... ], ... }"
533
534           Checks metaclasses to ensure the given metaroles are applied.  See
535           "does_not_metaroles_ok".
536
537       •   "class_metaclasses => { $mop => { ... }, ... }"
538
539           Validates this class' metaclasses: that is, given a MOP type (e.g.
540           role, attribute, method, ...) and a hashref, find the associated
541           metaclass of the given type and invoke "validate_thing" on it,
542           using the hashref as options for validate_thing().
543
544           e.g.
545
546               validate_class 'TestClass' => (
547                   metaclasses  => {
548                       attribute => {
549                           isa  => [ 'Moose::Meta::Attribute' ],
550                           does => [ 'MetaRole::attribute'    ],
551                       },
552                   },
553               );
554
555           ...yields:
556
557               ok 1 - TestClass has a metaclass
558               ok 2 - TestClass is a Moose class
559               # Subtest: Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1
560                   ok 1 - TestClass's attribute metaclass has a metaclass
561                   ok 2 - TestClass's attribute metaclass is a Moose class
562                   ok 3 - TestClass's attribute metaclass isa Moose::Meta::Attribute
563                   ok 4 - TestClass's attribute metaclass does MetaRole::attribute
564                   1..4
565               ok 3 - Checking the attribute metaclass, Moose::Meta::Class::__ANON__::SERIAL::1
566
567   validate_attribute
568       validate_attribute() allows you to test how an attribute looks once
569       built and attached to a class.
570
571       Let's say you have an attribute defined like this:
572
573           has foo => (
574               traits  => [ 'TestRole' ],
575               is      => 'ro',
576               isa     => 'Int',
577               builder => '_build_foo',
578               lazy    => 1,
579           );
580
581       You can use validate_attribute() to ensure that it's built out in the
582       way you expect:
583
584           validate_attribute TestClass => foo => (
585
586               # tests the attribute metaclass instance to ensure it does the roles
587               -does => [ 'TestRole' ],
588               # tests the attribute metaclass instance's inheritance
589               -isa  => [ 'Moose::Meta::Attribute' ], # for demonstration's sake
590
591               traits   => [ 'TestRole' ],
592               isa      => 'Int',
593               does     => 'Bar',
594               handles  => { },
595               reader   => 'foo',
596               builder  => '_build_foo',
597               default  => undef,
598               init_arg => 'foo',
599               lazy     => 1,
600               required => undef,
601           );
602
603       Options passed to validate_attribute() prefixed with "-" test the
604       attribute's metaclass instance rather than a setting on the attribute;
605       that is, "-does" ensures that the metaclass does a particular role
606       (e.g.  MooseX::AttributeShortcuts), while "does" tests the setting of
607       the attribute to require the value do a given role.
608
609       This function takes all the options "attribute_options_ok" takes, as
610       well as the following:
611
612       •   "-subtest => 'subtest name...'"
613
614           If set, all tests run will be wrapped in a subtest, the name of
615           which will be whatever "-subtest" is set to.
616

BUGS

624       Please report any bugs or feature requests on the bugtracker website
625       <https://github.com/RsrchBoy/Test-Moose-More/issues>
626
627       When submitting a bug or request, please include a test-file or a patch
628       to an existing test-file that illustrates the bug or desired feature.
629

AUTHOR

631       Chris Weyl <cweyl@alumni.drew.edu>
632

CONTRIBUTORS

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

COPYRIGHT AND LICENSE

639       This software is Copyright (c) 2017, 2016, 2015, 2014, 2013, 2012 by
640       Chris Weyl.
641
642       This is free software, licensed under:
643
644         The GNU Lesser General Public License, Version 2.1, February 1999
645
646
647
648perl v5.38.0                      2023-07-21              Test::Moose::More(3)