File Coverage

blib/lib/Test/Class/Moose.pm
Criterion Covered Total %
statement 114 120 95.0
branch 29 36 80.5
condition 5 6 83.3
subroutine 28 28 100.0
pod 6 9 66.6
total 182 199 91.4


line stmt bran cond sub pod time code
1             package Test::Class::Moose;
2              
3             # ABSTRACT: Serious testing for serious Perl
4              
5 30     30   189602 use 5.010000;
  30         97  
6              
7             our $VERSION = '0.97';
8              
9 30     30   12393 use Moose 2.0000;
  30         10373632  
  30         249  
10 30     30   188583 use Carp;
  30         66  
  30         2197  
11 30     30   1957 use namespace::autoclean;
  30         20397  
  30         262  
12 30     30   20024 use Import::Into;
  30         14427  
  30         836  
13 30     30   10886 use Sub::Attribute;
  30         58768  
  30         1734  
14              
15             # We don't use anything from this module in this one, but we want to require a
16             # specific version.
17 30     30   10712 use Test2 1.302118 ();
  30         2945  
  30         619  
18              
19 30     30   12251 use Test::Class::Moose::AttributeRegistry;
  30         90  
  30         817  
20 30     30   11090 use Test::Class::Moose::Config;
  30         160  
  30         1343  
21 30     30   273 use Test::Class::Moose::Deprecated;
  30         73  
  30         218  
22              
23             sub __sub_attr_declaration_code {
24              
25             # XXX sharing this behavior here because my first attempt at creating a
26             # role was a complete failure. MooseX::MethodAttributes can help here, but
27             # I have to parse the attributes manually (as far as I can tell) and I
28             # don't have the simple declarative style any more.
29 32     32   8450 return <<'DECLARE_ATTRIBUTES';
30             sub Tags : ATTR_SUB {
31             my ( $class, $symbol, undef, undef, $data, undef, $file, $line ) = @_;
32              
33             my @tags;
34             if ($data) {
35             $data =~ s/^\s+//g;
36             @tags = split /\s+/, $data;
37             }
38              
39             if ( $symbol eq 'ANON' ) {
40             die "Cannot tag anonymous subs at file $file, line $line\n";
41             }
42              
43             my $method = *{$symbol}{NAME};
44              
45             { # block for localising $@
46             local $@;
47              
48             Test::Class::Moose::AttributeRegistry->add_tags(
49             $class,
50             $method,
51             \@tags,
52             );
53             if ($@) {
54             croak "Error in adding tags: $@";
55             }
56             }
57             }
58              
59             sub Test : ATTR_SUB {
60             my ( $class, $symbol, undef, undef, undef, undef, $file, $line ) = @_;
61              
62             if ( $symbol eq 'ANON' ) {
63             croak("Cannot add plans to anonymous subs at file $file, line $line");
64             }
65              
66             my $method = *{$symbol}{NAME};
67             if ( $method =~ /^test_(?:startup|setup|teardown|shutdown)$/ ) {
68             croak("Test control method '$method' may not have a Test attribute");
69             }
70              
71             Test::Class::Moose::AttributeRegistry->add_plan(
72             $class,
73             $method,
74             1,
75             );
76             $class->meta->add_before_method_modifier($method, sub {
77             my $test = shift;
78             $test->test_report->plan(1);
79             });
80             }
81              
82             sub Tests : ATTR_SUB {
83             my ( $class, $symbol, undef, undef, $data, undef, $file, $line ) = @_;
84              
85             if ( $symbol eq 'ANON' ) {
86             croak("Cannot add plans to anonymous subs at file $file, line $line");
87             }
88              
89             my $method = *{$symbol}{NAME};
90             if ( $method =~ /^test_(?:startup|setup|teardown|shutdown)$/ ) {
91             croak("Test control method '$method' may not have a Test attribute");
92             }
93              
94             Test::Class::Moose::AttributeRegistry->add_plan(
95             $class,
96             $method,
97             $data,
98             );
99             if ( defined $data ) {
100             $class->meta->add_before_method_modifier($method, sub {
101             my $test = shift;
102             $test->test_report->plan($data);
103             });
104             }
105             }
106             DECLARE_ATTRIBUTES
107             }
108              
109             BEGIN {
110 30 100   30 0 3460 eval __PACKAGE__->__sub_attr_declaration_code;
  30 50   30 1 230  
  30 50   30 0 67  
  30 50   30   271  
  23 100   23   24662  
  23 50   3   52  
  23 50   6   78  
  22 100   2   76  
  22         92  
  23         77  
  0         0  
  23         48  
  23         61  
  23         50  
  23         38  
  23         153  
  23         293  
  0         0  
  30         13306  
  30         67  
  30         179  
  3         5546  
  3         16  
  0         0  
  3         5  
  3         9  
  3         18  
  1         23  
  2         12  
  2         8  
  2         72  
  2         53  
  30         9742  
  30         75  
  30         182  
  6         1453  
  6         17  
  0         0  
  6         8  
  6         10  
  6         18  
  0         0  
  6         18  
  6         23  
  4         12  
  6         242  
  6         128  
111 30 50       22313 croak($@) if $@;
112             }
113              
114             has 'test_report' => (
115             is => 'ro',
116             isa => 'Test::Class::Moose::Report',
117             );
118              
119             has 'test_class' => (
120             is => 'ro',
121             isa => 'Str',
122             init_arg => undef,
123             default => sub { ref $_[0] },
124             );
125              
126             has 'test_instance_name' => (
127             is => 'rw',
128             writer => '_set_test_instance_name',
129             isa => 'Str',
130             init_arg => undef,
131             );
132              
133             has 'test_skip' => (
134             is => 'rw',
135             isa => 'Str',
136             clearer => 'test_skip_clear',
137             );
138              
139             sub import {
140 167     167   10261 shift;
141 167         505 my %args = @_;
142              
143 167         374 my $caller = caller;
144              
145 167         432 my @imports = qw(
146             Moose
147             Sub::Attribute
148             strict
149             warnings
150             );
151              
152 167 100       507 unless ( $args{bare} ) {
153 23         4814 require Test::Most;
154 23         401528 push @imports, 'Test::Most';
155             }
156              
157 167         1109 $_->import::into($caller) for @imports;
158              
159 167 100 66     1186667 if ( my $parent = ( delete $args{parent} || delete $args{extends} ) ) {
160 35 100       198 my @parents = 'ARRAY' eq ref $parent ? @$parent : $parent;
161 35         154 $caller->meta->superclasses(@parents);
162 35 100       38621 unless ( $caller->isa(__PACKAGE__) ) {
163 3         38 croak( _bad_parents_error($caller) );
164             }
165             }
166             else {
167 132         502 $caller->meta->superclasses(__PACKAGE__);
168             }
169             }
170              
171             sub _bad_parents_error {
172 3     3   7 my $class = shift;
173              
174 3         12 my @ancestors = $class->meta->linearized_isa;
175              
176             # The first element is always $class
177 3         66 shift @ancestors;
178              
179 3         11 my $me = "The $class class";
180 3 100       11 if ( scalar @ancestors == 1 ) {
181 2         61 return "$me inherits from $ancestors[0] which does not inherit from "
182             . __PACKAGE__;
183             }
184              
185 1         3 my $heritage;
186 1 50       5 if ( scalar @ancestors == 2 ) {
187 0         0 $heritage .= join ' and ', @ancestors;
188             }
189             else {
190 1         2 my $last = pop @ancestors;
191 1         4 $heritage .= join ', ', @ancestors;
192 1         4 $heritage .= ", and $last";
193             }
194              
195             return
196 1         29 "$me has $heritage as ancestors "
197             . "but none of these classes inherit from "
198             . __PACKAGE__;
199             }
200              
201             sub _tcm_make_test_class_instances {
202 39     39   120 my $test_class = shift;
203              
204 39         1291 my $instance = $test_class->new(@_);
205 39         33529 $instance->_set_test_instance_name($test_class);
206              
207 39         133 return $instance;
208             }
209              
210             sub test_methods {
211 189     189 1 2923 my $self = shift;
212              
213 189         311 my @method_list;
214 189         1120 foreach my $method ( $self->meta->get_all_methods ) {
215              
216             # attributes cannot be test methods
217 6925 100       276725 next if $method->isa('Moose::Meta::Method::Accessor');
218              
219 5664         7123 my $class = ref $self;
220 5664         8827 my $name = $method->name;
221             next
222 5664 100 100     13577 unless $name =~ /^test_/
223             || Test::Class::Moose::AttributeRegistry->has_test_attribute(
224             $class, $name );
225              
226             # don't use anything defined in this package
227 1494 100       5177 next if __PACKAGE__->can($name);
228 549         1155 push @method_list => $name;
229             }
230              
231 189         1026 return @method_list;
232             }
233              
234             # empty stub methods guarantee that subclasses can always call these
235       37 1   sub test_startup { }
236       44 1   sub test_setup { }
237       101 1   sub test_teardown { }
238       39 1   sub test_shutdown { }
239              
240 41     41 0 75944 sub run_control_methods_on_skip {0}
241              
242             __PACKAGE__->meta->make_immutable;
243              
244             1;
245              
246             __END__
247              
248             =pod
249              
250             =encoding UTF-8
251              
252             =head1 NAME
253              
254             Test::Class::Moose - Serious testing for serious Perl
255              
256             =head1 VERSION
257              
258             version 0.97
259              
260             =head1 SYNOPSIS
261              
262             package TestsFor::DateTime;
263             use Test::Class::Moose;
264             use DateTime;
265              
266             # methods that begin with test_ are test methods.
267             sub test_constructor {
268             my $test = shift;
269             $test->test_report->plan(3); # strictly optional
270              
271             can_ok 'DateTime', 'new';
272             my %args = (
273             year => 1967,
274             month => 6,
275             day => 20,
276             );
277             isa_ok my $date = DateTime->new(%args), 'DateTime';
278             is $date->year, $args{year}, '... and the year should be correct';
279             }
280              
281             1;
282              
283             =head1 DESCRIPTION
284              
285             See the L<Test::Class::Moose home page|http://houseabsolute.github.io/test-class-moose/> for
286             a summary.
287              
288             C<Test::Class::Moose> is a powerful testing framework for Perl. Out of the box
289             you get:
290              
291             =over 4
292              
293             =item * Reporting
294              
295             =item * Extensibility
296              
297             =item * Tagging tests
298              
299             =item * Parallel testing
300              
301             =item * Test inheritance
302              
303             =item * Write your tests using Moose
304              
305             =item * All the testing functions and behavior from Test::Most
306              
307             =item * Event handlers for startup, setup, teardown, and shutdown of test classes
308              
309             =back
310              
311             Better docs will come later. You should already know how to use Moose and
312             L<Test::Class>.
313              
314             =for Pod::Coverage Tags Tests runtests run_control_methods_on_skip
315              
316             =head1 BASICS
317              
318             =head2 Inheriting from Test::Class::Moose
319              
320             Just C<use Test::Class::Moose>. That's all. You'll get all L<Test::Most> test
321             functions, too, along with C<strict> and C<warnings>. You can use all L<Moose>
322             behavior, too.
323              
324             When you C<use Test::Class::Moose> it inserts itself as a parent class for
325             your test class. This means that if you try to use C<extends> in your test
326             class you will break things unless you include C<Test::Class::Moose> as a
327             parent. We recommend that you use roles in your test classes instead.
328              
329             =head2 Declare a test method
330              
331             All method names that begin with C<test_> are test methods. Methods that do
332             not are not test methods.
333              
334             sub test_this_is_a_method {
335             my $test = shift;
336              
337             $test->this_is_not_a_test_method;
338             ok 1, 'whee!';
339             }
340              
341             sub this_is_not_a_test_method {
342             my $test = shift;
343             # but you can, of course, call it like normal
344             }
345              
346             You may specify C<Test> and C<Tests> method attributes, just like in
347             L<Test::Class> and the method will automatically be a test method, even if
348             does not start with C<test_>:
349              
350             sub this_is_a_test : Test {
351             pass 'we have a single test';
352             }
353              
354             sub another_test_method : Tests { # like "no_plan"
355             # a bunch of tests
356             }
357              
358             sub yet_another_test_method : Tests(7) { # sets plan to 7 tests
359             ...
360             }
361              
362             B<Note>: Prior to version 0.51, this feature only worked if you had the
363             optional C<Sub::Attribute> installed.
364              
365             =head2 Plans
366              
367             No plans needed. The test suite declares a plan of the number of test classes.
368              
369             Each test class is a subtest declaring a plan of the number of test methods.
370              
371             Each test method relies on an implicit C<done_testing> call.
372              
373             If you prefer, you can declare a plan in a test method:
374              
375             sub test_something {
376             my $test = shift;
377             $test->test_report->plan($num_tests);
378             ...
379             }
380              
381             Or with a C<Tests> attribute:
382              
383             sub test_something : Tests(3) {
384             my $test = shift;
385             ...
386             }
387              
388             You may call C<plan()> multiple times for a given test method. Each call to
389             C<plan()> will add that number of tests to the plan. For example, with a
390             method modifier:
391              
392             before 'test_something' => sub {
393             my $test = shift;
394             $test->test_report->plan($num_extra_tests);
395              
396             # more tests
397             };
398              
399             Please note that if you call C<plan>, the plan will still show up at the end
400             of the subtest run, but you'll get the desired failure if the number of tests
401             run does not match the plan.
402              
403             =head2 Inheriting from another Test::Class::Moose class
404              
405             List it as the C<extends> in the import list. If the base class does not use
406             (or extend) Test::Class::Moose, then a compile-time error is thrown.
407              
408             package TestsFor::Some::Class::Subclass;
409             use Test::Class::Moose extends => 'TestsFor::Some::Class';
410              
411             sub test_me {
412             my $test = shift;
413             my $class = $test->test_class;
414             ok 1, "I overrode my parent! ($class)";
415             }
416              
417             before 'test_this_baby' => sub {
418             my $test = shift;
419             my $class = $test->test_class;
420             pass "This should run before my parent method ($class)";
421             };
422              
423             sub this_should_not_run {
424             my $test = shift;
425             fail "We should never see this test";
426             }
427              
428             sub test_this_should_be_run {
429             for ( 1 .. 5 ) {
430             pass "This is test number $_ in this method";
431             }
432             }
433              
434             1;
435              
436             =head2 Skipping Test::Most
437              
438             By default, when you C<use Test::Class::Moose> in your own test class, it
439             exports all the subs from L<Test::Most> into your class. If you'd prefer to
440             import a different set of test tools, you can pass C<< bare => 1 >> when using
441             C<Test::Class::Moose>:
442              
443             use Test::Class::Moose bare => 1;
444              
445             When you pass this, C<Test::Class::Moose> will not export L<Test::Most>'s subs
446             into your class. You will have to explicitly import something like
447             L<Test::More> or L<Test2::Tools::Compare> in order to actually perform tests.
448              
449             =head2 Custom Test Toolkits
450              
451             If you'd like to provide a custom set of test modules to all of your test
452             classes, this is easily done with L<Import::Into>:
453              
454             package MM::Test::Class::Moose;
455              
456             use strict;
457             use warnings;
458             use namespace::autoclean ();
459              
460             use Import::Into;
461             use Test::Class::Moose ();
462             use Test::Fatal;
463             use Test::More;
464              
465             sub import {
466             my @imports = qw(
467             Test::Class::Moose
468             namespace::autoclean
469             Test::Fatal
470             Test::More
471             );
472              
473             my $caller_level = 1;
474             $_->import::into($caller_level) for @imports;
475             }
476              
477             You could also create a kit in a separate module like C<My::Test::Kit> using
478             L<Test::Kit> and then simply export that from your C<My::Test::Class::Moose>
479             module with L<Import::Into>.
480              
481             =head1 TEST CONTROL METHODS
482              
483             Do not run tests in test control methods. This will cause the test control
484             method to fail (this is a feature, not a bug). If a test control method
485             fails, the class/method will fail and testing for that class should stop.
486              
487             B<Every> test control method will be called as a method. The invocant is the
488             instance of your test class
489              
490             The available test control methods are:
491              
492             =head2 C<test_startup>
493              
494             sub test_startup {
495             my $test = shift;
496             $test->next::method;
497             # more startup
498             }
499              
500             Runs at the start of each test class. If you need to know the name of the
501             class you're running this in (though usually you shouldn't), use
502             C<< $test->test_class >>, or you can do this:
503              
504             sub test_startup {
505             my $test = shift;
506             my $report = $test->test_report;
507             my $instance = $report->current_instance->name;
508             my $upcoming_test_method = $report->current_method->name;
509             ...
510             }
511              
512             The C<< $test->test_report >> object is a L<Test::Class::Moose::Report::Instance>
513             object.
514              
515             =head2 C<test_setup>
516              
517             sub test_setup {
518             my $test = shift;
519             $test->next::method;
520             # more setup
521             }
522              
523             Runs at the start of each test method. If you must know the name of the test
524             you're about to run, you can do this:
525              
526             sub test_setup {
527             my $test = shift;
528             $test->next::method;
529             my $test_method = $test->test_report->current_method->name;
530             # do something with it
531             }
532              
533             =head2 C<test_teardown>
534              
535             sub test_teardown {
536             my $test = shift;
537             # more teardown
538             $test->next::method;
539             }
540              
541             Runs at the end of each test method.
542              
543             By default, this is not run if the test class is skipped entirely. You can
544             override the C<run_control_methods_on_skip> in your class to return a true
545             value in order to force this method to be run when the class is skipped.
546              
547             =head2 C<test_shutdown>
548              
549             sub test_shutdown {
550             my $test = shift;
551             # more teardown
552             $test->next::method;
553             }
554              
555             Runs at the end of each test class.
556              
557             By default, this is not run if the test class is skipped entirely. You can
558             override the C<run_control_methods_on_skip> in your class to return a true
559             value in order to force this method to be run when the class is skipped.
560              
561             =head2 Overriding Test Control Methods
562              
563             To override a test control method, just remember that this is OO:
564              
565             sub test_setup {
566             my $test = shift;
567             $test->next::method; # optional to call parent test_setup
568             # more setup code here
569             }
570              
571             =head1 TEST CLASS INSTANCES
572              
573             B<This feature is still considered experimental.>
574              
575             By default, each test class you create will be instantiated once. However, you
576             can tell the L<Test::Class::Moose::Runner> to create multiple instances of a
577             test class.
578              
579             To do this, simply consume the
580             L<Test::Class::Moose::Role::ParameterizedInstances> role in your test
581             class. This role requires you to implement a C<_constructor_parameter_sets>
582             method in your test class. That method will be called as a I<class method>. It
583             is expected to return a list of key/value pairs. The keys are the name of the
584             instance and the values are hashrefs of attributes to be passed to your test
585             class's constructor. Here's a really dumb example:
586              
587             package TestsFor::PlainAndFancy;
588             use Test::Class::Moose;
589             with 'Test::Class::Moose::Role::ParameterizedInstances';
590              
591             has is_fancy => (
592             is => 'ro',
593             isa => 'Bool',
594             required => 1,
595             );
596              
597             sub _constructor_parameter_sets {
598             my $class = shift;
599             return (
600             "$class - plain" => { is_fancy => 0 },
601             "$class - fancy" => { is_fancy => 1 },
602             );
603             }
604              
605             sub test_something { ... }
606              
607             The test runner will run all the test methods in your class I<once per
608             instance>, and each instance will be run in its own subtest. You can
609             dynamically decide to skip your test class completely by having
610             C<_constructor_parameter_sets> return an empty list.
611              
612             Note that this feature has great potential for abuse, so use it
613             cautiously. That said, there are cases where this feature can greatly simplify
614             your test code.
615              
616             =head1 RUNNING THE TEST SUITE
617              
618             See the docs for L<Test::Class::Moose::Runner> for details on running your
619             test suite. If you'd like to get up and running quickly, here's a very simple
620             test file you can use:
621              
622             use Test::Class::Moose::CLI;
623             Test::Class::Moose::CLI->new_with_options->run;
624              
625             Put this in a file like F<t/run-test-class.t>. When you run it with prove it
626             will load all the test classes defined in F<t/lib> and run them sequentially.
627              
628             See the documentation for L<Test::Class::Moose::CLI> on the options you can
629             pass when running tests.
630              
631             =head2 Skipping Classes and Methods
632              
633             If you wish to skip a class, set the reason in the C<test_startup> method.
634              
635             sub test_startup {
636             my $test = shift;
637             $test->test_skip("I don't want to run this class");
638             }
639              
640             If you are using L<test class instances|/"TEST CLASS INSTANCES">, you
641             can also make C<_constructor_parameter_sets> return an empty list,
642             which will result in the class being skipped.
643              
644             If you wish to skip an individual method, do so in the C<test_setup> method.
645              
646             sub test_setup {
647             my $test = shift;
648             my $test_method = $test->test_report->current_method;
649              
650             if ( 'test_time_travel' eq $test_method->name ) {
651             $test->test_skip("Time travel not yet available");
652             }
653             }
654              
655             =head2 The "Tests" and "Test" Attributes
656              
657             If you're comfortable with L<Test::Class>, you know that test methods methods are
658             declared in L<Test::Class> with C<Test> (for a method with a single test) or
659             C<Tests>, for a method with multiple tests. This also works for
660             C<Test::Class::Moose>. Test methods declared this way do not need to start
661             with C<test_>.
662              
663             sub something_we_want_to_check : Test {
664             # this method may have only one test
665             }
666              
667             sub something_else_to_check : Tests {
668             # this method may have multiple tests
669             }
670              
671             sub another_test_method : Tests(3) {
672             # this method must have exactly 3 tests
673             }
674              
675             If a test method overrides a parent test method and calls it, their plans will
676             be added together:
677              
678             package TestsFor::Parent;
679              
680             use Test::Class::Moose;
681              
682             sub some_test : Tests(3) {
683             # three tests
684             }
685              
686             And later:
687              
688             package TestsFor::Child;
689              
690             use Test::Class::Moose extends => 'TestsFor::Parent';
691              
692             sub some_test : Tests(2) {
693             my $test = shift;
694             $test->next::method;
695             # 2 tests here
696             }
697              
698             In the above example, C<TestsFor::Parent::some_test> will run three tests, but
699             C<TestsFor::Child::some_test> will run I<five> tests (two tests, plus the
700             three from the parent).
701              
702             Note that if a plan is explicitly declared, any modifiers or overriding
703             methods calling the original method will also have to assert the number of
704             tests to ensure the plan is correct. The above C<TestsFor::Parent> and
705             C<TestsFor::Child> code would fail if the child's C<some_test> method
706             attribute was C<Tests> without the number of tests asserted.
707              
708             Do not use C<Test> or C<Tests> with test control methods because you don't run
709             tests in those.
710              
711             =head2 Tagging Methods
712              
713             Sometimes you want to be able to assign metadata to help you better manage
714             your test suite. You can do this with tags:
715              
716             sub test_save_poll_data : Tags(api network) {
717             ...
718             }
719              
720             Tags are strictly optional and you can provide one or more tags for each test
721             method with a space separated list of tags. You can use this to filter your
722             tests suite, if desired. For example, if your network goes down and all tests
723             which rely on a network are tagged with C<network>, you can skip those tests
724             with this:
725              
726             Test::Class::Moose::Runner->new( exclude_tags => 'network' )->runtests;
727              
728             Or maybe you want to run all C<api> and C<database> tests, but skip those
729             marked C<deprecated>:
730              
731             Test::Class::Moose::Runner->new(
732             include_tags => [qw/api database/],
733             exclude_tags => 'deprecated',
734             )->runtests;
735              
736             You can also inspect tags within your test classes:
737              
738             sub test_setup {
739             my $test = shift;
740             my $method_to_run = $test->test_report->current_method;
741             if ( $method_to_run->has_tag('db') ) {
742             $test->load_database_fixtures;
743             }
744             }
745              
746             Tagging support relies on L<Sub::Attribute>. If this module is not available,
747             C<include_tags> and C<exclude_tags> will be ignored, but a warning will be
748             issued if those are seen. Prior to version 0.51, C<Sub::Attribute> was
749             optional. Now it's mandatory, so those features should always work.
750              
751             =head1 THINGS YOU CAN OVERRIDE
752              
753             ... but probably shouldn't.
754              
755             As a general rule, methods beginning with C</^test_/> are reserved for
756             L<Test::Class::Moose>. This makes it easier to remember what you can and
757             cannot override. However, any test with C<Test> or C<Tests> are test methods
758             regardless of their names.
759              
760             =head2 C<test_report>
761              
762             my $report = $test->test_report;
763              
764             Returns the L<Test::Class::Moose::Report> object. Useful if you want to do
765             your own reporting and not rely on the default output provided with the
766             C<statistics> boolean option.
767              
768             You can also call it in test classes (most useful in the C<test_setup()> method):
769              
770             sub test_setup {
771             my $test = shift;
772             $self->next::method;
773             my $report = $test->test_report;
774             my $instance = $test->current_instance;
775             my $method = $test->current_method; # the test method we're about to run
776             if ( $method->name =~ /customer/ ) {
777             $test->load_customer_fixture;
778             }
779             # or better still
780             if ( $method->has_tag('customer') ) {
781             $test->load_customer_fixture;
782             }
783             }
784              
785             =head2 C<test_class>
786              
787             my $class = $test->test_class;
788              
789             Returns the name for this test class. Useful if you rebless an object (such as
790             applying a role at runtime) and don't want to lose the original class name.
791              
792             =head2 C<test_methods>
793              
794             You may override this in a subclass. Currently returns all methods in a test
795             class that start with C<test_> (except for the test control methods).
796              
797             Please note that the behavior for C<include> and C<exclude> is also contained
798             in this method. If you override it, you will need to account for those
799             yourself.
800              
801             =head2 C<import>
802              
803             Sadly, we have an C<import> method. This is used to automatically provide you
804             with all of the L<Test::Most> behavior.
805              
806             =head1 SAMPLE TAP OUTPUT
807              
808             We use nested tests (subtests) at each level:
809              
810             1..2
811             #
812             # Executing tests for TestsFor::Basic::Subclass
813             #
814             1..3
815             # TestsFor::Basic::Subclass->test_me()
816             ok 1 - I overrode my parent! (TestsFor::Basic::Subclass)
817             1..1
818             ok 1 - test_me
819             # TestsFor::Basic::Subclass->test_this_baby()
820             ok 1 - This should run before my parent method (TestsFor::Basic::Subclass)
821             ok 2 - whee! (TestsFor::Basic::Subclass)
822             1..2
823             ok 2 - test_this_baby
824             # TestsFor::Basic::Subclass->test_this_should_be_run()
825             ok 1 - This is test number 1 in this method
826             ok 2 - This is test number 2 in this method
827             ok 3 - This is test number 3 in this method
828             ok 4 - This is test number 4 in this method
829             ok 5 - This is test number 5 in this method
830             1..5
831             ok 3 - test_this_should_be_run
832             ok 1 - TestsFor::Basic::Subclass
833             #
834             # Executing tests for TestsFor::Basic
835             #
836             1..2
837             # TestsFor::Basic->test_me()
838             ok 1 - test_me() ran (TestsFor::Basic)
839             ok 2 - this is another test (TestsFor::Basic)
840             1..2
841             ok 1 - test_me
842             # TestsFor::Basic->test_this_baby()
843             ok 1 - whee! (TestsFor::Basic)
844             1..1
845             ok 2 - test_this_baby
846             ok 2 - TestsFor::Basic
847             # Test classes: 2
848             # Test methods: 5
849             # Total tests run: 11
850             ok
851             All tests successful.
852             Files=1, Tests=2, 2 wallclock secs ( 0.03 usr 0.00 sys + 0.27 cusr 0.01 csys = 0.31 CPU)
853             Result: PASS
854              
855             =head1 REPORTING
856              
857             See L<Test::Class::Moose::Report> for more detailed information on reporting.
858              
859             Reporting features are subject to change.
860              
861             Sometimes you want more information about your test classes, it's time to do
862             some reporting. Maybe you even want some tests for your reporting. If you do
863             that, run the test suite in a subtest (because the plans will otherwise be
864             wrong).
865              
866             #!/usr/bin/env perl
867             use lib 'lib';
868             use Test::Most;
869             use Test::Class::Moose::Load qw(t/lib);
870             use Test::Class::Moose::Runner;
871              
872             my $test_suite = Test::Class::Moose::Runner->new;
873              
874             subtest 'run the test suite' => sub {
875             $test_suite->runtests;
876             };
877             my $report = $test_suite->test_report;
878              
879             foreach my $class ( $report->all_test_instances ) {
880             my $class_name = $class->name;
881             ok !$class->is_skipped, "$class_name was not skipped";
882             ok $class->passed, "$class_name passed";
883              
884             subtest "$class_name methods" => sub {
885             foreach my $method ( $class->all_test_methods ) {
886             my $method_name = $method->name;
887             ok $method->passed, "$method_name passed";
888              
889             ok !$method->is_skipped, "$method_name was not skipped";
890             cmp_ok $method->num_tests, '>', 0,
891             '... and some tests should have been run';
892             diag "Run time for $method_name: ".$method->time->duration;
893             }
894             };
895             my $time = $class->time;
896             diag "Run time for $class_name: ".$class->time->duration;
897              
898             my $real = $time->real;
899             my $user = $time->user;
900             my $system = $time->system;
901             # do with these as you will
902             }
903             diag "Number of test classes: " . $report->num_test_classes;
904             diag "Number of test instances: " . $report->num_test_instances;
905             diag "Number of test methods: " . $report->num_test_methods;
906             diag "Number of tests: " . $report->num_tests;
907              
908             done_testing;
909              
910             If you just want to output reporting information, you do not need to run the
911             test suite in a subtest:
912              
913             my $test_suite = Test::Class::Moose::Runner->new->runtests;
914             my $report = $test_suite->test_report;
915             ...
916              
917             Or even shorter:
918              
919             my $report = Test::Class::Moose::Runner->new->runtests->test_report;
920              
921             =head1 EXTRAS
922              
923             If you would like L<Test::Class::Moose> to take care of loading your classes
924             for you, see L<Test::Class::Moose::Role::AutoUse> in this distribution.
925              
926             =head1 DEPRECATIONS AND BACKWARDS INCOMPATIBILITIES
927              
928             =head2 Version 0.79
929              
930             =over 4
931              
932             =item *
933              
934             The L<Test::Class::Moose::Config> class's C<args> method is now
935             deprecated. This was a holdover from when Test::Class::Moose was both a parent
936             class for your test classes and the test class runner.
937              
938             =back
939              
940             =head2 Version 0.77
941              
942             =over 4
943              
944             =item *
945              
946             The passing of the report object as an argument to test methods and test
947             control methods is now deprecated. You can get the report from the test class
948             object itself via the C<< $test->test_report >> method.
949              
950             =item *
951              
952             The C<< Test::Class::Moose->runtests >> method has been removed. Use
953             L<Test::Class::Moose::Runner> to run your test classes.
954              
955             =item *
956              
957             The C<Test::Class::Moose::Role::Parallel> role has been removed. This has not
958             done anything except issue a warning since version 0.55.
959              
960             =back
961              
962             =head2 Version 0.75
963              
964             =over 4
965              
966             =item *
967              
968             The C<test_teardown method> is no longer run when a test is skipped unless
969             C<run_control_methods_on_skip> returns a true value. The C<test_teardown
970             method> was never intended to be run unconditionally.
971              
972             =item *
973              
974             Parallel testing now parallelizes test classes rather than individual test
975             instances. This is only relevant if your test suite contains parameterized
976             test classes. This is slightly less efficient, but made the internal test
977             running code much simpler and made it possible to fix reporting for parallel
978             test runs.
979              
980             =item *
981              
982             The L<Test::Class::Moose::Config> C<builder> method has been removed.
983              
984             =item *
985              
986             The L<Test::Class::Moose::Runner> C<builder> method has been removed.
987              
988             =back
989              
990             =head2 Version 0.67
991              
992             =over 4
993              
994             =item * The L<Test::Class::Moose::Report> class's C<all_test_classes> method is un-deprecated
995              
996             This method now returns a list of L<Test::Class::Moose::Report::Class>
997             objects. A class report contains one or more instance reports.
998              
999             =item *
1000              
1001             Removed the L<Test::Class::Moose::Report::Instance>'s error
1002             attribute. Contrary to the documentation, this attribute was never populated.
1003              
1004             =item *
1005              
1006             Renamed the L<Test::Class::Moose::Report::Method> C<instance_report> method to
1007             C<instance>. This is a better match for other report-related methods, which
1008             don't include a "_report" suffix.
1009              
1010             =item *
1011              
1012             Removed the long-deprecated C<tests_run> methods from
1013             L<Test::Class::Moose::Report> and L<Test::Class::Moose::Report::Method>.
1014              
1015             =item *
1016              
1017             Removed the long-deprecated C<<
1018             Test::Class::Moose::Report::Method->add_to_plan method >>.
1019              
1020             =back
1021              
1022             =head2 Version 0.55
1023              
1024             =over 4
1025              
1026             =item * Running tests with Test::Class::Moose is deprecated - use L<Test::Class::Moose::Runner>
1027              
1028             As of version 0.55, running tests and being a test class have been
1029             separated. Your test classes should continue to C<use Test::Class::Moose>, but
1030             your test runner script should use L<Test::Class::Moose::Runner>:
1031              
1032             use Test::Class::Moose::Load 't/lib';
1033             use Test::Class::Moose::Runner;
1034             Test::Class::Moose::Runner->new->runtests;
1035              
1036             Calling C<< Test::Class::Moose->new->runtests >> still works, but is
1037             deprecated and will issue a warning.
1038              
1039             =item * Parallel testing is totally different
1040              
1041             The C<Test::Class::Moose::Role::Parallel> role won't do anything other than
1042             issue a warning. See the L<Test::Class::Moose::Runner> docs for details on
1043             running tests in parallel.
1044              
1045             =item * The L<Test::Class::Moose::Report> C<all_test_classes> method is deprecated
1046              
1047             This has been replaced with the C<all_test_instances> method. The
1048             C<all_test_classes> method is still present for backwards compatibility, but
1049             it simply calls C<all_test_instances> under the hood.
1050              
1051             =item * The C<Test::Class::Moose::Report::Class> class is gone
1052              
1053             It has been replaced by the C<Test::Class::Moose::Report::Instance> class,
1054             which has the same API.
1055              
1056             =item * The C<Test::Class::Moose::Report::Method> C<class_report> method has been renamed
1057              
1058             This is now called C<instance_report>.
1059              
1060             =back
1061              
1062             =head2 Version 0.40
1063              
1064             =over 4
1065              
1066             =item * C<test_reporting>
1067              
1068             As of version 0.40, the long deprecated method C<test_reporting> has now been
1069             removed.
1070              
1071             =item * C<$report> argument to methods deprecated
1072              
1073             Prior to version 0.40, you used to have a second argument to all test methods
1074             and test control methods:
1075              
1076             sub test_something {
1077             my ( $test, $report ) = @_;
1078             ...
1079             }
1080              
1081             This was annoying. It was doubly annoying in test control methods in case you
1082             forgot it:
1083              
1084             sub test_setup {
1085             my ( $test, $report ) = @_;
1086             $test->next::method; # oops, needed $report
1087             ...
1088             }
1089              
1090             That second argument is still passed, but it's deprecated. It's now
1091             recommended that you call the C<< $test->test_report >> method to get that.
1092             Instead of this:
1093              
1094             sub test_froblinator {
1095             my ( $test, $report ) = @_;
1096             $report->plan(7);
1097             ...
1098             }
1099              
1100             You write this:
1101              
1102             sub test_froblinator {
1103             my $test = shift;
1104             $test->test_report->plan(7);
1105             ...
1106             }
1107              
1108             =back
1109              
1110             =head1 TODO
1111              
1112             =over 4
1113              
1114             =item * Callbacks for tags (for example, 'critical' tags could bailout)
1115              
1116             =item * New test phases - start and end suite, not just start and end class/method
1117              
1118             =back
1119              
1120             =head1 MORE INFO
1121              
1122             You can find documentation for this module with the perldoc command.
1123              
1124             perldoc Test::Class::Moose
1125              
1126             You can also look for information at:
1127              
1128             =over 4
1129              
1130             =item * CPAN Ratings
1131              
1132             L<http://cpanratings.perl.org/d/Test-Class-Moose>
1133              
1134             =item * MetaCPAN
1135              
1136             L<https://metacpan.org/release/Test-Class-Moose/>
1137              
1138             =back
1139              
1140             =head1 SEE ALSO
1141              
1142             =over 4
1143              
1144             =item * L<Test::Routine>
1145              
1146             I always pointed people to this when they would ask about L<Test::Class> +
1147             L<Moose>, but I would always hear "that's not quite what I'm looking for".
1148             I don't quite understand what the reasoning was, but I strongly encourage you
1149             to take a look at L<Test::Routine>.
1150              
1151             =item * L<Test::Roo>
1152              
1153             L<Test::Routine>, but with L<Moo> instead of L<Moose>.
1154              
1155             =item * L<Test::Class>
1156              
1157             xUnit-style testing in Perl.
1158              
1159             =item * L<Test::Class::Most>
1160              
1161             L<Test::Class> + L<Test::Most>.
1162              
1163             =back
1164              
1165             =head1 SUPPORT
1166              
1167             Bugs may be submitted at L<https://github.com/houseabsolute/test-class-moose/issues>.
1168              
1169             I am also usually active on IRC as 'autarch' on C<irc://irc.perl.org>.
1170              
1171             =head1 SOURCE
1172              
1173             The source code repository for Test-Class-Moose can be found at L<https://github.com/houseabsolute/test-class-moose>.
1174              
1175             =head1 AUTHORS
1176              
1177             =over 4
1178              
1179             =item *
1180              
1181             Curtis "Ovid" Poe <ovid@cpan.org>
1182              
1183             =item *
1184              
1185             Dave Rolsky <autarch@urth.org>
1186              
1187             =back
1188              
1189             =head1 CONTRIBUTORS
1190              
1191             =for stopwords Andy Jack Christopher Layne Chuck Adams Denny de la Haye Desmond Daignault Doug Bell Gregory Oschwald Harald Jörg Jeremy Krieg Jonathan C. Otsuka Stowe Karen Etheridge Larry Leszczynski mark-5 mephinet Neil Bowers Olaf Alders Paul Boyd Williams Petrea Corneliu Stefan Steven Humphrey Stuckdownawell Tim Vroom Tom Beresford Heady Udo Oji
1192              
1193             =over 4
1194              
1195             =item *
1196              
1197             Andy Jack <github@veracity.ca>
1198              
1199             =item *
1200              
1201             Christopher Layne <clayne@apple.com>
1202              
1203             =item *
1204              
1205             Chuck Adams <charles_adams@symantec.com>
1206              
1207             =item *
1208              
1209             Denny de la Haye <denny@users.noreply.github.com>
1210              
1211             =item *
1212              
1213             Desmond Daignault <nawglan@users.noreply.github.com>
1214              
1215             =item *
1216              
1217             Doug Bell <madcityzen@gmail.com>
1218              
1219             =item *
1220              
1221             Gregory Oschwald <goschwald@maxmind.com>
1222              
1223             =item *
1224              
1225             Harald Jörg <Harald.Joerg@arcor.de>
1226              
1227             =item *
1228              
1229             Jeremy Krieg <Jeremy.Krieg@YourAmigo.com>
1230              
1231             =item *
1232              
1233             Jonathan C. Otsuka <djgoku@gmail.com>
1234              
1235             =item *
1236              
1237             Jonathan Stowe <jns@gellyfish.co.uk>
1238              
1239             =item *
1240              
1241             Karen Etheridge <ether@cpan.org>
1242              
1243             =item *
1244              
1245             Larry Leszczynski <larryl@cpan.org>
1246              
1247             =item *
1248              
1249             mark-5 <maflick88@gmail.com>
1250              
1251             =item *
1252              
1253             mephinet <mephinet@gmx.net>
1254              
1255             =item *
1256              
1257             Neil Bowers <neil@bowers.com>
1258              
1259             =item *
1260              
1261             Olaf Alders <olaf@wundersolutions.com>
1262              
1263             =item *
1264              
1265             Paul Boyd <pboyd@dev3l.net>
1266              
1267             =item *
1268              
1269             Paul Williams <kwakwaversal@gmail.com>
1270              
1271             =item *
1272              
1273             Petrea Corneliu Stefan <stefan@garage-coding.com>
1274              
1275             =item *
1276              
1277             Steven Humphrey <catchgithub@33k.co.uk>
1278              
1279             =item *
1280              
1281             Stuckdownawell <stuckdownawell@gmail.com>
1282              
1283             =item *
1284              
1285             Tim Vroom <vroom@blockstackers.com>
1286              
1287             =item *
1288              
1289             Tom Beresford <tom.beresford@bskyb.com>
1290              
1291             =item *
1292              
1293             Tom Heady <tom@punch.net>
1294              
1295             =item *
1296              
1297             Udo Oji <Velti@signor.com>
1298              
1299             =back
1300              
1301             =head1 COPYRIGHT AND LICENSE
1302              
1303             This software is copyright (c) 2012 - 2019 by Curtis "Ovid" Poe.
1304              
1305             This is free software; you can redistribute it and/or modify it under
1306             the same terms as the Perl 5 programming language system itself.
1307              
1308             The full text of the license can be found in the
1309             F<LICENSE> file included with this distribution.
1310              
1311             =cut