File Coverage

blib/lib/Test/Routine.pm
Criterion Covered Total %
statement 54 58 93.1
branch 14 20 70.0
condition 4 9 44.4
subroutine 10 10 100.0
pod 0 2 0.0
total 82 99 82.8


line stmt bran cond sub pod time code
1 11     11   137899 use v5.12.0;
  11         138  
2 11     11   68 use warnings;
  11         29  
  11         937  
3             package Test::Routine 0.031;
4             # ABSTRACT: composable units of assertion
5              
6             #pod =head1 SYNOPSIS
7             #pod
8             #pod # mytest.t
9             #pod use Test::More;
10             #pod use Test::Routine;
11             #pod use Test::Routine::Util;
12             #pod
13             #pod has fixture => (
14             #pod is => 'ro',
15             #pod lazy => 1,
16             #pod clearer => 'reset_fixture',
17             #pod default => sub { ...expensive setup... },
18             #pod );
19             #pod
20             #pod test "we can use our fixture to do stuff" => sub {
21             #pod my ($self) = @_;
22             #pod
23             #pod $self->reset_fixture; # this test requires a fresh one
24             #pod
25             #pod ok( $self->fixture->do_things, "do_things returns true");
26             #pod ok( ! $self->fixture->no_op, "no_op returns false");
27             #pod
28             #pod for my $item ($self->fixture->contents) {
29             #pod isa_ok($item, 'Fixture::Entry');
30             #pod }
31             #pod };
32             #pod
33             #pod test "fixture was recycled" => sub {
34             #pod my ($self) = @_;
35             #pod
36             #pod my $fixture = $self->fixture; # we don't expect a fresh one
37             #pod
38             #pod is( $self->fixture->things_done, 1, "we have done one thing already");
39             #pod };
40             #pod
41             #pod run_me;
42             #pod done_testing;
43             #pod
44             #pod =head1 DESCRIPTION
45             #pod
46             #pod Test::Routine is a very simple framework for writing your tests as composable
47             #pod units of assertion. In other words: roles.
48             #pod
49             #pod For a walkthrough of tests written with Test::Routine, see
50             #pod L<Test::Routine::Manual::Demo>.
51             #pod
52             #pod Test::Routine is similar to L<Test::Class> in some ways. These similarities
53             #pod are largely superficial, but the idea of "tests bound together in reusable
54             #pod units" is a useful one to understand when coming to Test::Routine. If you are
55             #pod already familiar with Test::Class, it is the differences rather than the
56             #pod similarities that will be more important to understand. If you are not
57             #pod familiar with Test::Class, there is no need to understand it prior to using
58             #pod Test::Routine.
59             #pod
60             #pod On the other hand, an understanding of the basics of L<Moose> is absolutely
61             #pod essential. Test::Routine composes tests from Moose classes, roles, and
62             #pod attributes. Without an understanding of those, you will not be able to use
63             #pod Test::Routine. The L<Moose::Manual> is an excellent resource for learning
64             #pod Moose, and has links to other online tutorials and documentation.
65             #pod
66             #pod =head2 The Concepts
67             #pod
68             #pod =head2 The Basics of Using Test::Routine
69             #pod
70             #pod There actually isn't much to Test::Routine I<other> than the basics. It does
71             #pod not provide many complex features, instead delegating almost everything to the
72             #pod Moose object system.
73             #pod
74             #pod =head3 Writing Tests
75             #pod
76             #pod To write a set of tests (a test routine, which is a role), you add C<use
77             #pod Test::Routine;> to your package. C<main> is an acceptable target for turning
78             #pod into a test routine, meaning that you may use Test::Routine in your F<*.t>
79             #pod files in your distribution.
80             #pod
81             #pod C<use>-ing Test::Routine will turn your package into a role that composes
82             #pod L<Test::Routine::Common>, and will give you the C<test> declarator for adding
83             #pod tests to your routine. Test::Routine::Common adds the C<run_test> method that
84             #pod will be called to run each test.
85             #pod
86             #pod The C<test> declarator is very simple, and will generally be called like this:
87             #pod
88             #pod test $NAME_OF_TEST => sub {
89             #pod my ($self) = @_;
90             #pod
91             #pod is($self->foo, 123, "we got the foo we expected");
92             #pod ...
93             #pod ...
94             #pod };
95             #pod
96             #pod This defines a test with a given name, which will be invoked like a method on
97             #pod the test object (described below). Tests are ordered by declaration within the
98             #pod file, but when multiple test routines are run in a single test, the ordering of
99             #pod the routines is B<undefined>.
100             #pod
101             #pod C<test> may also be given a different name for the installed method and the
102             #pod test description. This isn't usually needed, but can make things clearer when
103             #pod referring to tests as methods:
104             #pod
105             #pod test $NAME_OF_TEST_METHOD => { description => $TEST_DESCRIPTION } => sub {
106             #pod ...
107             #pod }
108             #pod
109             #pod Each test will be run by the C<run_test> method. To add setup or teardown
110             #pod behavior, advice (method modifiers) may be attached to that method. For
111             #pod example, to call an attribute clearer before each test, you could add:
112             #pod
113             #pod before run_test => sub {
114             #pod my ($self) = @_;
115             #pod
116             #pod $self->clear_some_attribute;
117             #pod };
118             #pod
119             #pod =head3 Running Tests
120             #pod
121             #pod To run tests, you will need to use L<Test::Routine::Util>, which will provide
122             #pod two functions for running tests: C<run_tests> and C<run_me>. The former is
123             #pod given a set of packages to compose and run as tests. The latter runs the
124             #pod caller, assuming it to be a test routine.
125             #pod
126             #pod C<run_tests> can be called in several ways:
127             #pod
128             #pod run_tests( $desc, $object );
129             #pod
130             #pod run_tests( $desc, \@packages, $arg );
131             #pod
132             #pod run_tests( $desc, $package, $arg ); # equivalent to ($desc, [$pkg], $arg)
133             #pod
134             #pod In the first case, the object is assumed to be a fully formed, testable object.
135             #pod In other words, you have already created a class that composes test routines
136             #pod and have built an instance of it.
137             #pod
138             #pod In the other cases, C<run_tests> will produce an instance for you. It divides
139             #pod the given packages into classes and roles. If more than one class was given,
140             #pod an exception is thrown. A new class is created subclassing the given class and
141             #pod applying the given roles. If no class was in the list, Moose::Object is used.
142             #pod The new class's C<new> is called with the given C<$arg> (if any).
143             #pod
144             #pod The composition mechanism makes it easy to run a test routine without first
145             #pod writing a class to which to apply it. This is what makes it possible to write
146             #pod your test routine in the C<main> package and run it directly from your F<*.t>
147             #pod file. The following is a valid, trivial use of Test::Routine:
148             #pod
149             #pod use Test::More;
150             #pod use Test::Routine;
151             #pod use Test::Routine::Util;
152             #pod
153             #pod test demo_test => sub { pass("everything is okay") };
154             #pod
155             #pod run_tests('our tests', 'main');
156             #pod done_testing;
157             #pod
158             #pod In this circumstance, though, you'd probably use C<run_me>, which runs the
159             #pod tests in the caller. You'd just replace the C<run_tests> line with
160             #pod C<< run_me; >>. A description for the run may be supplied, if you like.
161             #pod
162             #pod Each call to C<run_me> or C<run_tests> generates a new instance, and you can
163             #pod call them as many times, with as many different arguments, as you like. Since
164             #pod Test::Routine can't know how many times you'll call different test routines,
165             #pod you are responsible for calling C<L<done_testing|Test::More/done_testing>> when
166             #pod you're done testing.
167             #pod
168             #pod =head4 Running individual tests
169             #pod
170             #pod If you only want to run a subset of the tests, you can set the
171             #pod C<TEST_METHOD> environment variable to a regular expression that matches
172             #pod the names of the tests you want to run.
173             #pod
174             #pod For example, to run just the test named C<customer profile> in the
175             #pod C<MyTests> class.
176             #pod
177             #pod use Test::More;
178             #pod use Test::Routine::Util;
179             #pod
180             #pod $ENV{TEST_METHOD} = 'customer profile';
181             #pod run_tests('one test', 'MyTests');
182             #pod done_testing;
183             #pod
184             #pod To run all tests with C<customer> in the name:
185             #pod
186             #pod use Test::More;
187             #pod use Test::Routine::Util;
188             #pod
189             #pod $ENV{TEST_METHOD}= '.*customer.*';
190             #pod run_tests('some tests', 'MyTests');
191             #pod done_testing;
192             #pod
193             #pod If you specify an invalid regular expression, your tests will not be
194             #pod run:
195             #pod
196             #pod use Test::More;
197             #pod use Test::Routine::Util
198             #pod
199             #pod $ENV{TEST_METHOD} = 'C++'
200             #pod run_tests('invalid', 'MyTests');
201             #pod done_testing;
202             #pod
203             #pod When you run it:
204             #pod
205             #pod 1..0
206             #pod # No tests run!
207             #pod not ok 1 - No tests run for subtest "invalid"
208             #pod
209             #pod =cut
210              
211 11     11   4680 use Moose::Exporter;
  11         1137879  
  11         91  
212              
213 11     11   4217 use Moose::Role ();
  11         2674206  
  11         398  
214 11     11   116 use Moose::Util ();
  11         22  
  11         245  
215 11     11   90 use Scalar::Util qw(blessed);
  11         28  
  11         809  
216              
217 11     11   5964 use Test::Routine::Common;
  11         39  
  11         505  
218 11     11   4875 use Test::Routine::Test;
  11         42  
  11         7501  
219              
220             Moose::Exporter->setup_import_methods(
221             as_is => [ qw(test) ],
222             also => 'Moose::Role',
223             );
224              
225             sub init_meta {
226 13     13 0 5453 my ($class, %arg) = @_;
227              
228 13         66 my $meta = Moose::Role->init_meta(%arg);
229 13         39985 my $role = $arg{for_class};
230 13         105 Moose::Util::apply_all_roles($role, 'Test::Routine::Common');
231              
232 13         22343 return $meta;
233             }
234              
235             my $i = 0;
236             sub test {
237 29     29 0 29935 my $caller = caller();
238 29         75 my $name = shift;
239 29         58 my ($arg, $body);
240              
241 29 50 33     153 if (blessed($_[0]) && $_[0]->isa('Class::MOP::Method')) {
242 0         0 $arg = {};
243 0         0 $body = shift;
244             } else {
245 29 100       122 $arg = Params::Util::_HASH0($_[0]) ? { %{shift()} } : {};
  2         10  
246 29         176 $body = shift;
247             }
248              
249             # This could really have been done with a MooseX like InitArgs or Alias in
250             # Test::Routine::Test, but since this is a test library, I'd actually like to
251             # keep prerequisites fairly limited. -- rjbs, 2010-09-28
252 29 100       99 if (exists $arg->{desc}) {
253             Carp::croak "can't supply both 'desc' and 'description'"
254 1 50       3 if exists $arg->{description};
255 1         4 $arg->{description} = delete $arg->{desc};
256             }
257              
258 29   66     169 $arg->{description} //= $name;
259 29         146 $name =~ s/(?:::|')/_/g;
260              
261 29         196 my $class = Moose::Meta::Class->initialize($caller);
262              
263 29         714 my %origin;
264 29         292 @origin{qw(file line nth)} = ((caller(0))[1,2], $i++);
265              
266 29         84 my $method;
267 29 50 33     123 if (blessed($body) && $body->isa('Class::MOP::Method')) {
268 0 0       0 my $method_metaclass = Moose::Util::with_traits(
269             blessed($body),
270             'Test::Routine::Test::Role',
271             ($caller->can('test_routine_test_traits')
272             ? $caller->test_routine_test_traits
273             : ()),
274             );
275              
276 0         0 $method = $method_metaclass->meta->rebless_instance(
277             $body,
278             %$arg,
279             name => $name,
280             package_name => $caller,
281             _origin => \%origin,
282             );
283             } else {
284 29         59 my $test_class = 'Test::Routine::Test';
285              
286 29 100       211 if ($caller->can('test_routine_test_traits')) {
287 3         12 my @traits = $caller->test_routine_test_traits;
288              
289 3         27 $test_class = Moose::Meta::Class->create_anon_class(
290             superclasses => [ $test_class ],
291             cache => 1,
292             roles => \@traits,
293             )->name;
294             }
295              
296 29         9238 $method = $test_class->wrap(
297             %$arg,
298             name => $name,
299             body => $body,
300             package_name => $caller,
301             _origin => \%origin,
302             );
303             }
304              
305 29 100       37214 Carp::croak "can't have two tests with the same name ($name)"
306             if $class->get_method($name);
307              
308 28 100       2155 Carp::croak "there's already a subroutine named $name in $caller"
309             if $caller->can($name);
310              
311 27 50       217 Carp::croak "can't name a test after a Moose::Object method ($name)"
312             if Moose::Object->can($name);
313              
314 27         148 $class->add_method($name => $method);
315             }
316              
317             1;
318              
319             __END__
320              
321             =pod
322              
323             =encoding UTF-8
324              
325             =head1 NAME
326              
327             Test::Routine - composable units of assertion
328              
329             =head1 VERSION
330              
331             version 0.031
332              
333             =head1 SYNOPSIS
334              
335             # mytest.t
336             use Test::More;
337             use Test::Routine;
338             use Test::Routine::Util;
339              
340             has fixture => (
341             is => 'ro',
342             lazy => 1,
343             clearer => 'reset_fixture',
344             default => sub { ...expensive setup... },
345             );
346              
347             test "we can use our fixture to do stuff" => sub {
348             my ($self) = @_;
349              
350             $self->reset_fixture; # this test requires a fresh one
351              
352             ok( $self->fixture->do_things, "do_things returns true");
353             ok( ! $self->fixture->no_op, "no_op returns false");
354              
355             for my $item ($self->fixture->contents) {
356             isa_ok($item, 'Fixture::Entry');
357             }
358             };
359              
360             test "fixture was recycled" => sub {
361             my ($self) = @_;
362              
363             my $fixture = $self->fixture; # we don't expect a fresh one
364              
365             is( $self->fixture->things_done, 1, "we have done one thing already");
366             };
367              
368             run_me;
369             done_testing;
370              
371             =head1 DESCRIPTION
372              
373             Test::Routine is a very simple framework for writing your tests as composable
374             units of assertion. In other words: roles.
375              
376             For a walkthrough of tests written with Test::Routine, see
377             L<Test::Routine::Manual::Demo>.
378              
379             Test::Routine is similar to L<Test::Class> in some ways. These similarities
380             are largely superficial, but the idea of "tests bound together in reusable
381             units" is a useful one to understand when coming to Test::Routine. If you are
382             already familiar with Test::Class, it is the differences rather than the
383             similarities that will be more important to understand. If you are not
384             familiar with Test::Class, there is no need to understand it prior to using
385             Test::Routine.
386              
387             On the other hand, an understanding of the basics of L<Moose> is absolutely
388             essential. Test::Routine composes tests from Moose classes, roles, and
389             attributes. Without an understanding of those, you will not be able to use
390             Test::Routine. The L<Moose::Manual> is an excellent resource for learning
391             Moose, and has links to other online tutorials and documentation.
392              
393             =head2 The Concepts
394              
395             =head2 The Basics of Using Test::Routine
396              
397             There actually isn't much to Test::Routine I<other> than the basics. It does
398             not provide many complex features, instead delegating almost everything to the
399             Moose object system.
400              
401             =head3 Writing Tests
402              
403             To write a set of tests (a test routine, which is a role), you add C<use
404             Test::Routine;> to your package. C<main> is an acceptable target for turning
405             into a test routine, meaning that you may use Test::Routine in your F<*.t>
406             files in your distribution.
407              
408             C<use>-ing Test::Routine will turn your package into a role that composes
409             L<Test::Routine::Common>, and will give you the C<test> declarator for adding
410             tests to your routine. Test::Routine::Common adds the C<run_test> method that
411             will be called to run each test.
412              
413             The C<test> declarator is very simple, and will generally be called like this:
414              
415             test $NAME_OF_TEST => sub {
416             my ($self) = @_;
417              
418             is($self->foo, 123, "we got the foo we expected");
419             ...
420             ...
421             };
422              
423             This defines a test with a given name, which will be invoked like a method on
424             the test object (described below). Tests are ordered by declaration within the
425             file, but when multiple test routines are run in a single test, the ordering of
426             the routines is B<undefined>.
427              
428             C<test> may also be given a different name for the installed method and the
429             test description. This isn't usually needed, but can make things clearer when
430             referring to tests as methods:
431              
432             test $NAME_OF_TEST_METHOD => { description => $TEST_DESCRIPTION } => sub {
433             ...
434             }
435              
436             Each test will be run by the C<run_test> method. To add setup or teardown
437             behavior, advice (method modifiers) may be attached to that method. For
438             example, to call an attribute clearer before each test, you could add:
439              
440             before run_test => sub {
441             my ($self) = @_;
442              
443             $self->clear_some_attribute;
444             };
445              
446             =head3 Running Tests
447              
448             To run tests, you will need to use L<Test::Routine::Util>, which will provide
449             two functions for running tests: C<run_tests> and C<run_me>. The former is
450             given a set of packages to compose and run as tests. The latter runs the
451             caller, assuming it to be a test routine.
452              
453             C<run_tests> can be called in several ways:
454              
455             run_tests( $desc, $object );
456              
457             run_tests( $desc, \@packages, $arg );
458              
459             run_tests( $desc, $package, $arg ); # equivalent to ($desc, [$pkg], $arg)
460              
461             In the first case, the object is assumed to be a fully formed, testable object.
462             In other words, you have already created a class that composes test routines
463             and have built an instance of it.
464              
465             In the other cases, C<run_tests> will produce an instance for you. It divides
466             the given packages into classes and roles. If more than one class was given,
467             an exception is thrown. A new class is created subclassing the given class and
468             applying the given roles. If no class was in the list, Moose::Object is used.
469             The new class's C<new> is called with the given C<$arg> (if any).
470              
471             The composition mechanism makes it easy to run a test routine without first
472             writing a class to which to apply it. This is what makes it possible to write
473             your test routine in the C<main> package and run it directly from your F<*.t>
474             file. The following is a valid, trivial use of Test::Routine:
475              
476             use Test::More;
477             use Test::Routine;
478             use Test::Routine::Util;
479              
480             test demo_test => sub { pass("everything is okay") };
481              
482             run_tests('our tests', 'main');
483             done_testing;
484              
485             In this circumstance, though, you'd probably use C<run_me>, which runs the
486             tests in the caller. You'd just replace the C<run_tests> line with
487             C<< run_me; >>. A description for the run may be supplied, if you like.
488              
489             Each call to C<run_me> or C<run_tests> generates a new instance, and you can
490             call them as many times, with as many different arguments, as you like. Since
491             Test::Routine can't know how many times you'll call different test routines,
492             you are responsible for calling C<L<done_testing|Test::More/done_testing>> when
493             you're done testing.
494              
495             =head4 Running individual tests
496              
497             If you only want to run a subset of the tests, you can set the
498             C<TEST_METHOD> environment variable to a regular expression that matches
499             the names of the tests you want to run.
500              
501             For example, to run just the test named C<customer profile> in the
502             C<MyTests> class.
503              
504             use Test::More;
505             use Test::Routine::Util;
506              
507             $ENV{TEST_METHOD} = 'customer profile';
508             run_tests('one test', 'MyTests');
509             done_testing;
510              
511             To run all tests with C<customer> in the name:
512              
513             use Test::More;
514             use Test::Routine::Util;
515              
516             $ENV{TEST_METHOD}= '.*customer.*';
517             run_tests('some tests', 'MyTests');
518             done_testing;
519              
520             If you specify an invalid regular expression, your tests will not be
521             run:
522              
523             use Test::More;
524             use Test::Routine::Util
525              
526             $ENV{TEST_METHOD} = 'C++'
527             run_tests('invalid', 'MyTests');
528             done_testing;
529              
530             When you run it:
531              
532             1..0
533             # No tests run!
534             not ok 1 - No tests run for subtest "invalid"
535              
536             =head1 PERL VERSION
537              
538             This module should work on any version of perl still receiving updates from
539             the Perl 5 Porters. This means it should work on any version of perl released
540             in the last two to three years. (That is, if the most recently released
541             version is v5.40, then this module should work on both v5.40 and v5.38.)
542              
543             Although it may work on older versions of perl, no guarantee is made that the
544             minimum required version will not be increased. The version may be increased
545             for any reason, and there is no promise that patches will be accepted to lower
546             the minimum required perl.
547              
548             =head1 AUTHOR
549              
550             Ricardo Signes <cpan@semiotic.systems>
551              
552             =head1 CONTRIBUTORS
553              
554             =for stopwords Alex White Dagfinn Ilmari Mannsåker gregor herrmann Jesse Luehrs Matthew Horsfall Ricardo Signes Yanick Champoux
555              
556             =over 4
557              
558             =item *
559              
560             Alex White <VVu@geekfarm.org>
561              
562             =item *
563              
564             Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
565              
566             =item *
567              
568             gregor herrmann <gregoa@debian.org>
569              
570             =item *
571              
572             Jesse Luehrs <doy@tozt.net>
573              
574             =item *
575              
576             Matthew Horsfall <wolfsage@gmail.com>
577              
578             =item *
579              
580             Ricardo Signes <rjbs@cpan.org>
581              
582             =item *
583              
584             Ricardo Signes <rjbs@semiotic.systems>
585              
586             =item *
587              
588             Ricardo Signes <rjbs@users.noreply.github.com>
589              
590             =item *
591              
592             Yanick Champoux <yanick@babyl.dyndns.org>
593              
594             =back
595              
596             =head1 COPYRIGHT AND LICENSE
597              
598             This software is copyright (c) 2010 by Ricardo Signes.
599              
600             This is free software; you can redistribute it and/or modify it under
601             the same terms as the Perl 5 programming language system itself.
602              
603             =cut