1Fennec::Lite(3)       User Contributed Perl Documentation      Fennec::Lite(3)
2
3
4

NAME

6       Fennec::Lite - Minimalist Fennec, the commonly used bits.
7

DESCRIPTION

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
14       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
19       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

SYNOPSIS

26   SIMPLE
27           #!/usr/bin/perl
28           use strict;
29           use warnings;
30
31           # Brings in Test::More for us.
32           use Fennec::Lite;
33
34           tests good => sub {
35               ok( 1, "A good test" );
36           };
37
38           # You most call run_tests() after declaring your tests.
39           run_tests();
40           done_testing();
41
42   ADVANCED
43           #!/usr/bin/perl
44           use strict;
45           use warnings;
46
47           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
58           # Quickly create get/set accessors
59           fennec_accessors qw/ construction_string /;
60
61           # 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
68           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
80           tests "todo group" => (
81               todo => "This will fail",
82               code => sub { ok( 0, "false value" )},
83           );
84
85           tests "skip group" => (
86               skip => "This will fail badly",
87               sub => sub { die "oops" },
88           );
89
90           run_tests( "This is the construction string" );
91
92   Pure OO Interface
93           #!/usr/bin/perl
94           use strict;
95           use warnings;
96
97           use Fennec::Lite ();
98           use Test::More;
99
100           my $fennec = Fennec::Lite->new( test_class => __PACKAGE__ );
101
102           $fennec->add_tests( "test name" => sub {
103               ok( ... );
104           });
105
106           $fennec->run_tests;
107
108           done_testing();
109

IMPORTED FOR YOU

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

IMPORT ARGUMENTS

116           use Fennec::Lite %ARGS
117
118       plan => 'no_plan' || $count
119           Plan to pass into Test::More.
120
121       random => $bool
122           True by default. When true test groups will be run in random order.
123
124       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
128       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
133       alias_to => { $ALIAS => $PACKAGE, ... }
134           Define aliases, keys are alias names, values are tho package names
135           they should return.
136

RUNNING IN RANDOM ORDER

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
144       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
148           $ FENNEC_SEED="20100915" prove -I lib -v t/*.t
149

RUNNING SPECIFIC GROUPS

151       You can use the FENNEC_ITEM variable with a group name or line number
152       to run a specific test group only.
153
154           $ FENNEC_ITEM="22" prove -I lib -v t/MyTest.t
155           $ FENNEC_ITEM="Test Group A" prove -I lib -v t/MyTest.t
156
157       This can easily be integrated into an editor such as vim or emacs.
158

EXPORTED FUNCTIONS

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
172       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
179       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
183       fennec_accessors( @NAMES )
184           Quickly generate get/set accessors for your test class. You could
185           alternatively do it manually or use Moose.
186

PURE OO INTERFACE METHODS

188       $tests_ref = $fennec->tests()
189           Get a reference to the array of tests that have been added since
190           the last run.
191
192       $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
196       $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
200       $bool = $fennec->random( $bool )
201           Turn random on/off.
202
203       $fennec->add_tests( $name => sub { ... })
204       $fennec->add_tests( $name, %args, method => sub { ... })
205           Add a test group.
206
207       $fennec->run_tests( %test_class_construction_args )
208           Run the test groups
209
210       $bool = $fennec->run_skip_test( \%test )
211           Run a skip test (really just returns true)
212
213       $bool = $fennec->run_todo_group( \%test )
214           Run a group as TODO
215
216       $bool = $fennec->run_test_group( \%test )
217           Run a test group.
218
219       ( $bool, $error ) = $fennec->run_test_eval( \%test )
220           Does the actual test running in an eval to capture errors.
221
222       $fennec->test_eval_error( $bool, $error, \%test )
223           Handle a test eval error.
224

Extending Fennec::Lite

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
230   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
237       $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
241       $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
246       $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
250       @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
254       @list = may_load()
255           Returns a list of modules that should be loaded only if they are
256           installed.
257
258       $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
263       $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

FENNEC PROJECT

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
273       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
277       Fennec - The core framework
278         The primary Fennec project that ties them all together.
279

AUTHORS

281       Chad Granum exodist7@gmail.com
282
284       Copyright (C) 2010 Chad Granum
285
286       Fennec-Lite is free software; Standard perl license.
287
288       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.
292
293
294
295perl v5.34.0                      2022-01-21                   Fennec::Lite(3)
Impressum