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