1NAME
2 Fennec::Lite - Minimalist Fennec, the commonly used bits.
3
4DESCRIPTION
5 Fennec does a ton, but it may be hard to adopt it all at once. It also
6 is a large project, and has not yet been fully split into component
7 projects. Fennec::Lite takes a minimalist approach to do for Fennec what
8 Mouse does for Moose.
9
10 Fennec::Lite is a single module file with no non-core dependencies. It
11 can easily be used by any project, either directly, or by copying it
12 into your project. The file itself is less than 300 lines of code at the
13 time of this writing, that includes whitespace.
14
15 This module does not cover any of the more advanced features such as
16 result capturing or SPEC workflows. This module only covers test
17 grouping and group randomization. You can also use the FENNEC_ITEM
18 variable with a group name or line number to run a specific test group
19 only. Test::Builder is used under the hood for TAP output.
20
21SYNOPSIS
22 SIMPLE
23 #!/usr/bin/perl
24 use strict;
25 use warnings;
26
27 # Brings in Test::More for us.
28 use Fennec::Lite;
29
30 tests good => sub {
31 ok( 1, "A good test" );
32 };
33
34 # You most call run_tests() after declaring your tests.
35 run_tests();
36 done_testing();
37
38 ADVANCED
39 #!/usr/bin/perl
40 use strict;
41 use warnings;
42
43 use Fennec::Lite
44 plan => 8,
45 random => 1,
46 testing => 'My::Class',
47 alias => [
48 'My::Class::ThingA'
49 ],
50 alias_to => {
51 TB => 'My::Class::ThingB',
52 };
53
54 # Quickly create get/set accessors
55 fennec_accessors qw/ construction_string /;
56
57 # Create a constructor for our test class.
58 sub new {
59 my $class = shift;
60 my $string = @_;
61 return bless({ construction_string => $string }, $class );
62 }
63
64 tests good => sub {
65 # Get $self. Created with new()
66 my $self = shift;
67 $self->isa_ok( __PACKAGE__ );
68 is(
69 $self->construction_string,
70 "This is the construction string",
71 "Constructed properly"
72 );
73 ok( 1, "A good test" );
74 };
75
76 tests "todo group" => (
77 todo => "This will fail",
78 code => sub { ok( 0, "false value" )},
79 );
80
81 tests "skip group" => (
82 skip => "This will fail badly",
83 sub => sub { die "oops" },
84 );
85
86 run_tests( "This is the construction string" );
87
88 Pure OO Interface
89 #!/usr/bin/perl
90 use strict;
91 use warnings;
92
93 use Fennec::Lite ();
94 use Test::More;
95
96 my $fennec = Fennec::Lite->new( test_class => __PACKAGE__ );
97
98 $fennec->add_tests( "test name" => sub {
99 ok( ... );
100 });
101
102 $fennec->run_tests;
103
104 done_testing();
105
106IMPORTED FOR YOU
107 When you use Fennec::Lite, Test::More is automatically imported for you.
108 In addition Test::Warn and Test::Exception will also be loaded, but only
109 if they are installed.
110
111IMPORT ARGUMENTS
112 use Fennec::Lite %ARGS
113
114 plan => 'no_plan' || $count
115 Plan to pass into Test::More.
116
117 random => $bool
118 True by default. When true test groups will be run in random order.
119
120 testing => $CLASS_NAME
121 Declare what class you ore testing. Provides $CLASS and CLASS(),
122 both of which are simply the name of the class being tested.
123
124 alias => @PACKAGES
125 Create alias functions your the given package. An alias is a
126 function that returns the package name. The aliases will be named
127 after the last part of the package name.
128
129 alias_to => { $ALIAS => $PACKAGE, ... }
130 Define aliases, keys are alias names, values are tho package names
131 they should return.
132
133RUNNING IN RANDOM ORDER
134 By default test groups will be run in a random order. The random seed is
135 the current date (YYYYMMDD). This is used so that the order does not
136 change on the day you are editing your code. However the ardor will
137 change daily allowing for automated testing to find order dependent
138 failures.
139
140 You can manually set the random seed to reproduce a failure. The
141 FENNEC_SEED environment variable will be used as the seed when it is
142 present.
143
144 $ FENNEC_SEED="20100915" prove -I lib -v t/*.t
145
146RUNNING SPECIFIC GROUPS
147 You can use the FENNEC_ITEM variable with a group name or line number to
148 run a specific test group only.
149
150 $ FENNEC_ITEM="22" prove -I lib -v t/MyTest.t
151 $ FENNEC_ITEM="Test Group A" prove -I lib -v t/MyTest.t
152
153 This can easily be integrated into an editor such as vim or emacs.
154
155EXPORTED FUNCTIONS
156 tests $name => $coderef,
157 tests $name => ( code => $coderef, todo => $reason )
158 tests $name => ( code => $coderef, skip => $reason )
159 tests $name => ( sub => $coderef )
160 tests $name => ( method => $coderef )
161 Declare a test group. The first argument must always be the test
162 group name. In the 2 part form the second argument must be a
163 coderef. In the multi-part form you may optionally declare the group
164 as todo, or as a skip. A coderef must always be provided, in
165 multi-part form you may use the code, method, or sub params for this
166 purpose, they are all the same.
167
168 run_tests( %params )
169 Instantiate an instance of the test class, passing %params to the
170 constructor. If no constructor is present a default is used. All
171 tests that have been added will be run. All tests will be cleared,
172 you may continue to declare tests and call run_tests again to run
173 the new tests.
174
175 fennec()
176 Returns the instance of Fennec::Lite created when you imported it.
177 This is the instance that tests() and run_tests() act upon.
178
179 fennec_accessors( @NAMES )
180 Quickly generate get/set accessors for your test class. You could
181 alternatively do it manually or use Moose.
182
183PURE OO INTERFACE METHODS
184 $tests_ref = $fennec->tests()
185 Get a reference to the array of tests that have been added since the
186 last run.
187
188 $classname = $fennec->test_class( $classname )
189 Get/Set the class name that will be used to create test objects that
190 will act as the invocant on all test methods.
191
192 $seed = $fennec->seed( $newseed )
193 Get/Set the random seed that will be used to re-seed srand() before
194 randomizing tests, as well as before each test.
195
196 $bool = $fennec->random( $bool )
197 Turn random on/off.
198
199 $fennec->add_tests( $name => sub { ... })
200 $fennec->add_tests( $name, %args, method => sub { ... })
201 Add a test group.
202
203 $fennec->run_tests( %test_class_construction_args )
204 Run the test groups
205
206 $bool = $fennec->run_skip_test( \%test )
207 Run a skip test (really just returns true)
208
209 $bool = $fennec->run_todo_group( \%test )
210 Run a group as TODO
211
212 $bool = $fennec->run_test_group( \%test )
213 Run a test group.
214
215 ( $bool, $error ) = $fennec->run_test_eval( \%test )
216 Does the actual test running in an eval to capture errors.
217
218 $fennec->test_eval_error( $bool, $error, \%test )
219 Handle a test eval error.
220
221Extending Fennec::Lite
222 In the tradition of the Fennec project, Fennec::Lite is designed to be
223 extensible. You can even easily subclass/edit Fennec::Lite to work with
224 alternatives to Test::Builder.
225
226 METHODS TO OVERRIDE
227 $fennec->init()
228 Called by new prior to returning the newly constructed object. In
229 Fennec::Lite this loads Test::Builder and puts a reference to it in
230 the TB() accessor. If you do want to replace Test::Builder in your
231 subclass you may do so by overriding init().
232
233 $fennec->run_skip_test( \%test )
234 Calls Test::Builder->skip( $reason ), then returns true. Override
235 this if you replace Test::Builder in your subclass.
236
237 $fennec->run_todo_group( \%test )
238 Calls run_test_eval() in a TODO environment. Currently uses
239 Test::Builder to start/stop TODO mode around the test. Override this
240 if you wish to replace Test::Builder.
241
242 $fennec->test_eval_error( $bool, $error, \%test )
243 Handle an exception thrown in a test group method. Currently calls
244 Test::Bulder->ok( 0, GROUP_NAME ).
245
246 @list = must_load()
247 Returns a list of modules that MUST be loaded into tho calling class
248 (unless used in OO form). This is currently only Test::More.
249
250 @list = may_load()
251 Returns a list of modules that should be loaded only if they are
252 installed.
253
254 $name_to_code_ref = module_loaders()
255 Returns a hashref containing package => sub { ... }. Use this if you
256 need to load modules in a custom way, currently Test::More has a
257 special loader in here to account for plans.
258
259 $fennec->import_hook()
260 Called on the instance that was created by import(), runs at the
261 very end of the import process. Currently does nothing.
262
263FENNEC PROJECT
264 This module is part of the Fennec project. See Fennec for more details.
265 Fennec is a project to develop an extensible and powerful testing
266 framework. Together the tools that make up the Fennec framework provide
267 a potent testing environment.
268
269 The tools provided by Fennec are also useful on their own. Sometimes a
270 tool created for Fennec is useful outside the greater framework. Such
271 tools are turned into their own projects. This is one such project.
272
273 Fennec - The core framework
274 The primary Fennec project that ties them all together.
275
276AUTHORS
277 Chad Granum exodist7@gmail.com
278
279COPYRIGHT
280 Copyright (C) 2010 Chad Granum
281
282 Fennec-Lite is free software; Standard perl license.
283
284 Fennec-Lite is distributed in the hope that it will be useful, but
285 WITHOUT ANY WARRANTY; without even the implied warranty of
286 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for
287 more details.
288
289