1Test::Routine(3) User Contributed Perl Documentation Test::Routine(3)
2
6 Test::Routine - composable units of assertion
7
9 version 0.027
10
12 # mytest.t
13 use Test::More;
14 use Test::Routine;
15 use Test::Routine::Util;
16 has fixture => (
18 is => 'ro',
19 lazy => 1,
20 clearer => 'reset_fixture',
21 default => sub { ...expensive setup... },
22 );
23 test "we can use our fixture to do stuff" => sub {
25 my ($self) = @_;
26 $self->reset_fixture; # this test requires a fresh one
28 ok( $self->fixture->do_things, "do_things returns true");
30 ok( ! $self->fixture->no_op, "no_op returns false");
31 for my $item ($self->fixture->contents) {
33 isa_ok($item, 'Fixture::Entry');
34 }
35 };
36 test "fixture was recycled" => sub {
38 my ($self) = @_;
39 my $fixture = $self->fixture; # we don't expect a fresh one
41 is( $self->fixture->things_done, 1, "we have done one thing already");
43 };
44 run_me;
46 done_testing;
47
49 Test::Routine is a very simple framework for writing your tests as
50 composable units of assertion. In other words: roles.
51 For a walkthrough of tests written with Test::Routine, see
53 Test::Routine::Manual::Demo.
54 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 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 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 Writing Tests
77 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 "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 The "test" declarator is very simple, and will generally be called like
89 this:
90 test $NAME_OF_TEST => sub {
92 my ($self) = @_;
93 is($self->foo, 123, "we got the foo we expected");
95 ...
96 ...
97 };
98 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 "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 test $NAME_OF_TEST_METHOD => { description => $TEST_DESCRIPTION } => sub {
109 ...
110 }
111 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 before run_test => sub {
118 my ($self) = @_;
119 $self->clear_some_attribute;
121 };
122 Running Tests
124 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 "run_tests" can be called in several ways:
131 run_tests( $desc, $object );
133 run_tests( $desc, \@packages, $arg );
135 run_tests( $desc, $package, $arg ); # equivalent to ($desc, [$pkg], $arg)
137 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 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 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 use Test::More;
156 use Test::Routine;
157 use Test::Routine::Util;
158 test demo_test => sub { pass("everything is okay") };
160 run_tests('our tests', 'main');
162 done_testing;
163 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 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 Running individual tests
175 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 For example, to run just the test named "customer profile" in the
181 "MyTests" class.
182 use Test::More;
184 use Test::Routine::Util;
185 $ENV{TEST_METHOD} = 'customer profile';
187 run_tests('one test', 'MyTests');
188 done_testing;
189 To run all tests with "customer" in the name:
191 use Test::More;
193 use Test::Routine::Util;
194 $ENV{TEST_METHOD}= '.*customer.*';
196 run_tests('some tests', 'MyTests');
197 done_testing;
198 If you specify an invalid regular expression, your tests will not be
200 run:
201 use Test::More;
203 use Test::Routine::Util
204 $ENV{TEST_METHOD} = 'C++'
206 run_tests('invalid', 'MyTests');
207 done_testing;
208 When you run it:
210 1..0
212 # No tests run!
213 not ok 1 - No tests run for subtest "invalid"
214
216 Ricardo Signes <rjbs@cpan.org>
217
219 · Alex White <VVu@geekfarm.org>
220 · Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
222 · gregor herrmann <gregoa@debian.org>
224 · Jesse Luehrs <doy@tozt.net>
226 · Yanick Champoux <yanick@babyl.dyndns.org>
228
230 This software is copyright (c) 2010 by Ricardo Signes.
231 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.
234perl v5.32.0 2020-07-28 Test::Routine(3)