1Test::Moose::More(3) User Contributed Perl Documentation Test::Moose::More(3)
2
3
4
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
15 is_class_ok 'Some::Class';
16 is_role_ok 'Some::Role';
17 has_method_ok 'Some::Class', 'foo';
18
19 # ... 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
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
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
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
619 Please see those modules/websites for more information related to this
620 module.
621
622 · 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
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
632 Chris Weyl <cweyl@alumni.drew.edu>
633
635 · Chad Granum <chad.granum@dreamhost.com>
636
637 · Karen Etheridge <ether@cpan.org>
638
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.28.0 2017-09-21 Test::Moose::More(3)