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
230       options.
231
232       Note that some of these options will skip if used against attributes
233       defined in a role.
234
235       ·   "-subtest => 'subtest name...'"
236
237           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
241       ·   "is => ro|rw"
242
243           Tests for reader/writer options set as one would expect.
244
245       ·   "isa => ..."
246
247           Validates that the attribute requires its value to be a given type.
248
249       ·   "does => ..."
250
251           Validates that the attribute requires its value to do a given role.
252
253       ·   "builder => '...'"
254
255           Validates that the attribute expects the method name given to be
256           its builder.
257
258       ·   "default => ..."
259
260           Validates that the attribute has the given default.
261
262       ·   "init_arg => '...'"
263
264           Validates that the attribute has the given initial argument name.
265
266       ·   "lazy => 0|1"
267
268           Validates that the attribute is/isn't lazy.
269
270       ·   "required => 0|1"
271
272           Validates that setting the attribute's value is/isn't required.
273

VALIDATION METHODS

275   validate_thing
276       Runs a bunch of tests against the given $thing, as defined:
277
278           validate_thing $thing => (
279
280               attributes => [ ... ],
281               methods    => [ ... ],
282               isa        => [ ... ],
283
284               # ensures sugar is/is-not present
285               sugar      => 0,
286
287               # ensures $thing does these roles
288               does       => [ ... ],
289
290               # ensures $thing does not do these roles
291               does_not   => [ ... ],
292           );
293
294       $thing can be the name of a role or class, an object instance, or a
295       metaclass.
296
297       ·   "-subtest => 'subtest name...'"
298
299           If set, all tests run will be wrapped in a subtest, the name of
300           which will be whatever "-subtest" is set to.
301
302       ·   "isa => [ ... ]"
303
304           A list of superclasses thing should have.
305
306       ·   "anonymous => 0|1"
307
308           Check to see if the class is/isn't anonymous.
309
310       ·   "does => [ ... ]"
311
312           A list of roles the thing should do.
313
314       ·   "does_not => [ ... ]"
315
316           A list of roles the thing should not do.
317
318       ·   "attributes => [ ... ]"
319
320           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
325               validate_thing $thing => (
326
327                   attributes => [
328                       'foo',
329                       'bar',
330                       baz => { is => 'ro', ... },
331                       'bip',
332                   ],
333               );
334
335       ·   "methods => [ ... ]"
336
337           A list of methods the thing should have; see "has_method_ok".
338
339       ·   "no_methods => [ ... ]"
340
341           A list of methods the thing should not have; see
342           "has_no_method_ok".
343
344       ·   "sugar => 0|1"
345
346           Ensure that thing can/cannot do the standard Moose sugar.
347
348       ·   "metaclasses => { $mop => { ... }, ... }"
349
350           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
355           e.g.
356
357               validate_thing 'TestClass' => (
358                   metaclasses  => {
359                       attribute => {
360                           isa  => [ 'Moose::Meta::Attribute' ],
361                           does => [ 'MetaRole::attribute'    ],
362                       },
363                   },
364               );
365
366           ...yields:
367
368               # 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
376           Note that "validate_class()" and "validate_role()" implement this
377           using "class_metaclasses" and "role_metaclasses", respectively.
378
379   validate_role
380       The same as "validate_thing()", but ensures $thing is a role, and
381       allows for additional role-specific tests.
382
383           validate_role $thing => (
384
385               required_methods => [ ... ],
386
387               # ...and all other options from validate_thing()
388           );
389
390       ·   "-compose => 0|1"
391
392           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
399           e.g.:
400
401               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
420       ·   "-subtest => 'subtest name...'"
421
422           If set, all tests run will be wrapped in a subtest, the name of
423           which will be whatever "-subtest" is set to.
424
425       ·   "required_methods => [ ... ]"
426
427           A list of methods the role requires a consuming class to supply.
428
429       ·   "before => [ ... ]"
430
431           A list of methods the role expects to wrap before, on application
432           to a class.
433
434           See "before" in Moose for information on before method modifiers.
435
436       ·   "around => [ ... ]"
437
438           A list of methods the role expects to wrap around, on application
439           to a class.
440
441           See "around" in Moose for information on around method modifiers.
442
443       ·   "after => [ ... ]"
444
445           A list of methods the role expects to wrap after, on application to
446           a class.
447
448           See "after" in Moose for information on after method modifiers.
449
450       ·   "role_metaroles => { $mop => [ $role, ... ], ... }"
451
452           Checks metaclasses to ensure the given metaroles are applied.  See
453           "does_metaroles_ok".
454
455       ·   "no_role_metaroles => { $mop => [ $role, ... ], ... }"
456
457           Checks metaclasses to ensure the given metaroles are applied.  See
458           "does_not_metaroles_ok".
459
460       ·   "role_metaclasses => { $mop => { ... }, ... }"
461
462           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
467           e.g.
468
469               validate_role 'TestRole' => (
470                   metaclasses  => {
471                       attribute => {
472                           isa  => [ 'Moose::Meta::Attribute' ],
473                           does => [ 'MetaRole::attribute'    ],
474                       },
475                   },
476               );
477
478           ...yields:
479
480               # 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
488           Note that "validate_class()" and "validate_role()" implement this
489           using "class_metaclasses" and "role_metaclasses", respectively.
490
491       ·   "class_metaclasses => { $mop => { ... }, ... }"
492
493           As with role_metaclasses, above, except that this option is only
494           used if "-compose" is also specified.
495
496   validate_class
497       The same as "validate_thing()", but ensures $thing is a class, and
498       allows for additional class-specific tests.
499
500           validate_class $thing => (
501
502               isa  => [ ... ],
503
504               attributes => [ ... ],
505               methods    => [ ... ],
506
507               # ensures sugar is/is-not present
508               sugar      => 0,
509
510               # ensures $thing does these roles
511               does       => [ ... ],
512
513               # ensures $thing does not do these roles
514               does_not   => [ ... ],
515
516               # ...and all other options from validate_thing()
517           );
518
519       ·   "-subtest => 'subtest name...'"
520
521           If set, all tests run will be wrapped in a subtest, the name of
522           which will be whatever "-subtest" is set to.
523
524       ·   "immutable => 0|1"
525
526           Checks the class to see if it is/isn't immutable.
527
528       ·   "class_metaroles => { $mop => [ $role, ... ], ... }"
529
530           Checks metaclasses to ensure the given metaroles are applied.  See
531           "does_metaroles_ok".
532
533       ·   "no_class_metaroles => { $mop => [ $role, ... ], ... }"
534
535           Checks metaclasses to ensure the given metaroles are applied.  See
536           "does_not_metaroles_ok".
537
538       ·   "class_metaclasses => { $mop => { ... }, ... }"
539
540           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
545           e.g.
546
547               validate_class 'TestClass' => (
548                   metaclasses  => {
549                       attribute => {
550                           isa  => [ 'Moose::Meta::Attribute' ],
551                           does => [ 'MetaRole::attribute'    ],
552                       },
553                   },
554               );
555
556           ...yields:
557
558               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
568   validate_attribute
569       "validate_attribute()" allows you to test how an attribute looks once
570       built and attached to a class.
571
572       Let's say you have an attribute defined like this:
573
574           has foo => (
575               traits  => [ 'TestRole' ],
576               is      => 'ro',
577               isa     => 'Int',
578               builder => '_build_foo',
579               lazy    => 1,
580           );
581
582       You can use "validate_attribute()" to ensure that it's built out in the
583       way you expect:
584
585           validate_attribute TestClass => foo => (
586
587               # 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
592               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
604       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
610       This function takes all the options "attribute_options_ok" takes, as
611       well as the following:
612
613       ·   "-subtest => 'subtest name...'"
614
615           If set, all tests run will be wrapped in a subtest, the name of
616           which will be whatever "-subtest" is set to.
617

BUGS

625       Please report any bugs or feature requests on the bugtracker website
626       <https://github.com/RsrchBoy/Test-Moose-More/issues>
627
628       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

AUTHOR

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

CONTRIBUTORS

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

COPYRIGHT AND LICENSE

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