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

NAME

6       Test::Routine - composable units of assertion
7

VERSION

9       version 0.027
10

SYNOPSIS

12         # mytest.t
13         use Test::More;
14         use Test::Routine;
15         use Test::Routine::Util;
16
17         has fixture => (
18           is   => 'ro',
19           lazy => 1,
20           clearer => 'reset_fixture',
21           default => sub { ...expensive setup... },
22         );
23
24         test "we can use our fixture to do stuff" => sub {
25           my ($self) = @_;
26
27           $self->reset_fixture; # this test requires a fresh one
28
29           ok( $self->fixture->do_things, "do_things returns true");
30           ok( ! $self->fixture->no_op,   "no_op returns false");
31
32           for my $item ($self->fixture->contents) {
33             isa_ok($item, 'Fixture::Entry');
34           }
35         };
36
37         test "fixture was recycled" => sub {
38           my ($self) = @_;
39
40           my $fixture = $self->fixture; # we don't expect a fresh one
41
42           is( $self->fixture->things_done, 1, "we have done one thing already");
43         };
44
45         run_me;
46         done_testing;
47

DESCRIPTION

49       Test::Routine is a very simple framework for writing your tests as
50       composable units of assertion.  In other words: roles.
51
52       For a walkthrough of tests written with Test::Routine, see
53       Test::Routine::Manual::Demo.
54
55       Test::Routine is similar to Test::Class in some ways.  These
56       similarities are largely superficial, but the idea of "tests bound
57       together in reusable units" is a useful one to understand when coming
58       to Test::Routine.  If you are already familiar with Test::Class, it is
59       the differences rather than the similarities that will be more
60       important to understand.  If you are not familiar with Test::Class,
61       there is no need to understand it prior to using Test::Routine.
62
63       On the other hand, an understanding of the basics of Moose is
64       absolutely essential.  Test::Routine composes tests from Moose classes,
65       roles, and attributes.  Without an understanding of those, you will not
66       be able to use Test::Routine.  The Moose::Manual is an excellent
67       resource for learning Moose, and has links to other online tutorials
68       and documentation.
69
70   The Concepts
71   The Basics of Using Test::Routine
72       There actually isn't much to Test::Routine other than the basics.  It
73       does not provide many complex features, instead delegating almost
74       everything to the Moose object system.
75
76       Writing Tests
77
78       To write a set of tests (a test routine, which is a role), you add "use
79       Test::Routine;" to your package.  "main" is an acceptable target for
80       turning into a test routine, meaning that you may use Test::Routine in
81       your *.t files in your distribution.
82
83       "use"-ing Test::Routine will turn your package into a role that
84       composes Test::Routine::Common, and will give you the "test" declarator
85       for adding tests to your routine.  Test::Routine::Common adds the
86       "run_test" method that will be called to run each test.
87
88       The "test" declarator is very simple, and will generally be called like
89       this:
90
91         test $NAME_OF_TEST => sub {
92           my ($self) = @_;
93
94           is($self->foo, 123, "we got the foo we expected");
95           ...
96           ...
97         };
98
99       This defines a test with a given name, which will be invoked like a
100       method on the test object (described below).  Tests are ordered by
101       declaration within the file, but when multiple test routines are run in
102       a single test, the ordering of the routines is undefined.
103
104       "test" may also be given a different name for the installed method and
105       the test description.  This isn't usually needed, but can make things
106       clearer when referring to tests as methods:
107
108         test $NAME_OF_TEST_METHOD => { description => $TEST_DESCRIPTION } => sub {
109           ...
110         }
111
112       Each test will be run by the "run_test" method.  To add setup or
113       teardown behavior, advice (method modifiers) may be attached to that
114       method.  For example, to call an attribute clearer before each test,
115       you could add:
116
117         before run_test => sub {
118           my ($self) = @_;
119
120           $self->clear_some_attribute;
121         };
122
123       Running Tests
124
125       To run tests, you will need to use Test::Routine::Util, which will
126       provide two functions for running tests: "run_tests" and "run_me".  The
127       former is given a set of packages to compose and run as tests.  The
128       latter runs the caller, assuming it to be a test routine.
129
130       "run_tests" can be called in several ways:
131
132         run_tests( $desc, $object );
133
134         run_tests( $desc, \@packages, $arg );
135
136         run_tests( $desc, $package, $arg );  # equivalent to ($desc, [$pkg], $arg)
137
138       In the first case, the object is assumed to be a fully formed, testable
139       object.  In other words, you have already created a class that composes
140       test routines and have built an instance of it.
141
142       In the other cases, "run_tests" will produce an instance for you.  It
143       divides the given packages into classes and roles.  If more than one
144       class was given, an exception is thrown.  A new class is created
145       subclassing the given class and applying the given roles.  If no class
146       was in the list, Moose::Object is used.  The new class's "new" is
147       called with the given $arg (if any).
148
149       The composition mechanism makes it easy to run a test routine without
150       first writing a class to which to apply it.  This is what makes it
151       possible to write your test routine in the "main" package and run it
152       directly from your *.t file.  The following is a valid, trivial use of
153       Test::Routine:
154
155         use Test::More;
156         use Test::Routine;
157         use Test::Routine::Util;
158
159         test demo_test => sub { pass("everything is okay") };
160
161         run_tests('our tests', 'main');
162         done_testing;
163
164       In this circumstance, though, you'd probably use "run_me", which runs
165       the tests in the caller.  You'd just replace the "run_tests" line with
166       "run_me;".  A description for the run may be supplied, if you like.
167
168       Each call to "run_me" or "run_tests" generates a new instance, and you
169       can call them as many times, with as many different arguments, as you
170       like.  Since Test::Routine can't know how many times you'll call
171       different test routines, you are responsible for calling "done_testing"
172       when you're done testing.
173
174       Running individual tests
175
176       If you only want to run a subset of the tests, you can set the
177       "TEST_METHOD" environment variable to a regular expression that matches
178       the names of the tests you want to run.
179
180       For example, to run just the test named "customer profile" in the
181       "MyTests" class.
182
183         use Test::More;
184         use Test::Routine::Util;
185
186         $ENV{TEST_METHOD} = 'customer profile';
187         run_tests('one test', 'MyTests');
188         done_testing;
189
190       To run all tests with "customer" in the name:
191
192         use Test::More;
193         use Test::Routine::Util;
194
195         $ENV{TEST_METHOD}= '.*customer.*';
196         run_tests('some tests', 'MyTests');
197         done_testing;
198
199       If you specify an invalid regular expression, your tests will not be
200       run:
201
202         use Test::More;
203         use Test::Routine::Util
204
205         $ENV{TEST_METHOD} = 'C++'
206         run_tests('invalid', 'MyTests');
207         done_testing;
208
209       When you run it:
210
211             1..0
212             # No tests run!
213         not ok 1 - No tests run for subtest "invalid"
214

AUTHOR

216       Ricardo Signes <rjbs@cpan.org>
217

CONTRIBUTORS

219       •   Alex White <VVu@geekfarm.org>
220
221       •   Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
222
223       •   gregor herrmann <gregoa@debian.org>
224
225       •   Jesse Luehrs <doy@tozt.net>
226
227       •   Yanick Champoux <yanick@babyl.dyndns.org>
228
230       This software is copyright (c) 2010 by Ricardo Signes.
231
232       This is free software; you can redistribute it and/or modify it under
233       the same terms as the Perl 5 programming language system itself.
234
235
236
237perl v5.32.1                      2021-01-27                  Test::Routine(3)
Impressum