.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Fennec::Lite 3pm"
.TH Fennec::Lite 3pm "2015-06-08" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Fennec::Lite \- Minimalist Fennec, the commonly used bits.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Fennec does a ton, but it may be hard to adopt it all at once. It also is a
large project, and has not yet been fully split into component projects.
Fennec::Lite takes a minimalist approach to do for Fennec what Mouse does for
Moose.
.PP
Fennec::Lite is a single module file with no non-core dependencies. It can
easily be used by any project, either directly, or by copying it into your
project. The file itself is less than 300 lines of code at the time of this
writing, that includes whitespace.
.PP
This module does not cover any of the more advanced features such as result
capturing or \s-1SPEC\s0 workflows. This module only covers test grouping and group
randomization. You can also use the \s-1FENNEC_ITEM\s0 variable with a group name or
line number to run a specific test group only. Test::Builder is used under the
hood for \s-1TAP\s0 output.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SS "\s-1SIMPLE\s0"
.IX Subsection "SIMPLE"
.Vb 3
\&    #!/usr/bin/perl
\&    use strict;
\&    use warnings;
\&
\&    # Brings in Test::More for us.
\&    use Fennec::Lite;
\&
\&    tests good => sub {
\&        ok( 1, "A good test" );
\&    };
\&
\&    # You most call run_tests() after declaring your tests.
\&    run_tests();
\&    done_testing();
.Ve
.SS "\s-1ADVANCED\s0"
.IX Subsection "ADVANCED"
.Vb 3
\&    #!/usr/bin/perl
\&    use strict;
\&    use warnings;
\&
\&    use Fennec::Lite
\&        plan => 8,
\&        random => 1,
\&        testing => \*(AqMy::Class\*(Aq,
\&        alias => [
\&            \*(AqMy::Class::ThingA\*(Aq
\&        ],
\&        alias_to => {
\&            TB => \*(AqMy::Class::ThingB\*(Aq,
\&        };
\&
\&    # Quickly create get/set accessors
\&    fennec_accessors qw/ construction_string /;
\&
\&    # Create a constructor for our test class.
\&    sub new {
\&        my $class = shift;
\&        my $string = @_;
\&        return bless({ construction_string => $string }, $class );
\&    }
\&
\&    tests good => sub {
\&        # Get $self. Created with new()
\&        my $self = shift;
\&        $self\->isa_ok( _\|_PACKAGE_\|_ );
\&        is(
\&            $self\->construction_string,
\&            "This is the construction string",
\&            "Constructed properly"
\&        );
\&        ok( 1, "A good test" );
\&    };
\&
\&    tests "todo group" => (
\&        todo => "This will fail",
\&        code => sub { ok( 0, "false value" )},
\&    );
\&
\&    tests "skip group" => (
\&        skip => "This will fail badly",
\&        sub => sub { die "oops" },
\&    );
\&
\&    run_tests( "This is the construction string" );
.Ve
.SS "Pure \s-1OO\s0 Interface"
.IX Subsection "Pure OO Interface"
.Vb 3
\&    #!/usr/bin/perl
\&    use strict;
\&    use warnings;
\&
\&    use Fennec::Lite ();
\&    use Test::More;
\&
\&    my $fennec = Fennec::Lite\->new( test_class => _\|_PACKAGE_\|_ );
\&
\&    $fennec\->add_tests( "test name" => sub {
\&        ok( ... );
\&    });
\&
\&    $fennec\->run_tests;
\&
\&    done_testing();
.Ve
.SH "IMPORTED FOR YOU"
.IX Header "IMPORTED FOR YOU"
When you use Fennec::Lite, Test::More is automatically imported for you. In
addition Test::Warn and Test::Exception will also be loaded, but only if
they are installed.
.SH "IMPORT ARGUMENTS"
.IX Header "IMPORT ARGUMENTS"
.Vb 1
\&    use Fennec::Lite %ARGS
.Ve
.ie n .IP "plan => 'no_plan' || $count" 4
.el .IP "plan => 'no_plan' || \f(CW$count\fR" 4
.IX Item "plan => 'no_plan' || $count"
Plan to pass into Test::More.
.ie n .IP "random => $bool" 4
.el .IP "random => \f(CW$bool\fR" 4
.IX Item "random => $bool"
True by default. When true test groups will be run in random order.
.ie n .IP "testing => $CLASS_NAME" 4
.el .IP "testing => \f(CW$CLASS_NAME\fR" 4
.IX Item "testing => $CLASS_NAME"
Declare what class you ore testing. Provides \f(CW$CLASS\fR and \s-1\fICLASS\s0()\fR, both of which
are simply the name of the class being tested.
.ie n .IP "alias => @PACKAGES" 4
.el .IP "alias => \f(CW@PACKAGES\fR" 4
.IX Item "alias => @PACKAGES"
Create alias functions your the given package. An alias is a function that
returns the package name. The aliases will be named after the last part of the
package name.
.ie n .IP "alias_to => { $ALIAS => $PACKAGE, ... }" 4
.el .IP "alias_to => { \f(CW$ALIAS\fR => \f(CW$PACKAGE\fR, ... }" 4
.IX Item "alias_to => { $ALIAS => $PACKAGE, ... }"
Define aliases, keys are alias names, values are tho package names they should
return.
.SH "RUNNING IN RANDOM ORDER"
.IX Header "RUNNING IN RANDOM ORDER"
By default test groups will be run in a random order. The random seed is the
current date (\s-1YYYYMMDD\s0). This is used so that the order does not change on the
day you are editing your code. However the ardor will change daily allowing for
automated testing to find order dependent failures.
.PP
You can manually set the random seed to reproduce a failure. The \s-1FENNEC_SEED\s0
environment variable will be used as the seed when it is present.
.PP
.Vb 1
\&    $ FENNEC_SEED="20100915" prove \-I lib \-v t/*.t
.Ve
.SH "RUNNING SPECIFIC GROUPS"
.IX Header "RUNNING SPECIFIC GROUPS"
You can use the \s-1FENNEC_ITEM\s0 variable with a group name or line number to run a
specific test group only.
.PP
.Vb 2
\&    $ FENNEC_ITEM="22" prove \-I lib \-v t/MyTest.t
\&    $ FENNEC_ITEM="Test Group A" prove \-I lib \-v t/MyTest.t
.Ve
.PP
This can easily be integrated into an editor such as vim or emacs.
.SH "EXPORTED FUNCTIONS"
.IX Header "EXPORTED FUNCTIONS"
.ie n .IP "tests $name => $coderef," 4
.el .IP "tests \f(CW$name\fR => \f(CW$coderef\fR," 4
.IX Item "tests $name => $coderef,"
.PD 0
.ie n .IP "tests $name => ( code => $coderef, todo => $reason )" 4
.el .IP "tests \f(CW$name\fR => ( code => \f(CW$coderef\fR, todo => \f(CW$reason\fR )" 4
.IX Item "tests $name => ( code => $coderef, todo => $reason )"
.ie n .IP "tests $name => ( code => $coderef, skip => $reason )" 4
.el .IP "tests \f(CW$name\fR => ( code => \f(CW$coderef\fR, skip => \f(CW$reason\fR )" 4
.IX Item "tests $name => ( code => $coderef, skip => $reason )"
.ie n .IP "tests $name => ( sub => $coderef )" 4
.el .IP "tests \f(CW$name\fR => ( sub => \f(CW$coderef\fR )" 4
.IX Item "tests $name => ( sub => $coderef )"
.ie n .IP "tests $name => ( method => $coderef )" 4
.el .IP "tests \f(CW$name\fR => ( method => \f(CW$coderef\fR )" 4
.IX Item "tests $name => ( method => $coderef )"
.PD
Declare a test group. The first argument must always be the test group name. In
the 2 part form the second argument must be a coderef. In the multi-part form
you may optionally declare the group as todo, or as a skip. A coderef must
always be provided, in multi-part form you may use the code, method, or sub
params for this purpose, they are all the same.
.ie n .IP "run_tests( %params )" 4
.el .IP "run_tests( \f(CW%params\fR )" 4
.IX Item "run_tests( %params )"
Instantiate an instance of the test class, passing \f(CW%params\fR to the constructor.
If no constructor is present a default is used. All tests that have been added
will be run. All tests will be cleared, you may continue to declare tests and
call run_tests again to run the new tests.
.IP "\fIfennec()\fR" 4
.IX Item "fennec()"
Returns the instance of Fennec::Lite created when you imported it. This is the
instance that \fItests()\fR and \fIrun_tests()\fR act upon.
.ie n .IP "fennec_accessors( @NAMES )" 4
.el .IP "fennec_accessors( \f(CW@NAMES\fR )" 4
.IX Item "fennec_accessors( @NAMES )"
Quickly generate get/set accessors for your test class. You could alternatively
do it manually or use Moose.
.SH "PURE OO INTERFACE METHODS"
.IX Header "PURE OO INTERFACE METHODS"
.ie n .IP "$tests_ref = $fennec\->\fItests()\fR" 4
.el .IP "\f(CW$tests_ref\fR = \f(CW$fennec\fR\->\fItests()\fR" 4
.IX Item "$tests_ref = $fennec->tests()"
Get a reference to the array of tests that have been added since the last run.
.ie n .IP "$classname = $fennec\->test_class( $classname )" 4
.el .IP "\f(CW$classname\fR = \f(CW$fennec\fR\->test_class( \f(CW$classname\fR )" 4
.IX Item "$classname = $fennec->test_class( $classname )"
Get/Set the class name that will be used to create test objects that will act
as the invocant on all test methods.
.ie n .IP "$seed = $fennec\->seed( $newseed )" 4
.el .IP "\f(CW$seed\fR = \f(CW$fennec\fR\->seed( \f(CW$newseed\fR )" 4
.IX Item "$seed = $fennec->seed( $newseed )"
Get/Set the random seed that will be used to re-seed \fIsrand()\fR before randomizing
tests, as well as before each test.
.ie n .IP "$bool = $fennec\->random( $bool )" 4
.el .IP "\f(CW$bool\fR = \f(CW$fennec\fR\->random( \f(CW$bool\fR )" 4
.IX Item "$bool = $fennec->random( $bool )"
Turn random on/off.
.ie n .IP "$fennec\->add_tests( $name => sub { ... })" 4
.el .IP "\f(CW$fennec\fR\->add_tests( \f(CW$name\fR => sub { ... })" 4
.IX Item "$fennec->add_tests( $name => sub { ... })"
.PD 0
.ie n .IP "$fennec\->add_tests( $name, %args, method => sub { ... })" 4
.el .IP "\f(CW$fennec\fR\->add_tests( \f(CW$name\fR, \f(CW%args\fR, method => sub { ... })" 4
.IX Item "$fennec->add_tests( $name, %args, method => sub { ... })"
.PD
Add a test group.
.ie n .IP "$fennec\->run_tests( %test_class_construction_args )" 4
.el .IP "\f(CW$fennec\fR\->run_tests( \f(CW%test_class_construction_args\fR )" 4
.IX Item "$fennec->run_tests( %test_class_construction_args )"
Run the test groups
.ie n .IP "$bool = $fennec\->run_skip_test( \e%test )" 4
.el .IP "\f(CW$bool\fR = \f(CW$fennec\fR\->run_skip_test( \e%test )" 4
.IX Item "$bool = $fennec->run_skip_test( %test )"
Run a skip test (really just returns true)
.ie n .IP "$bool = $fennec\->run_todo_group( \e%test )" 4
.el .IP "\f(CW$bool\fR = \f(CW$fennec\fR\->run_todo_group( \e%test )" 4
.IX Item "$bool = $fennec->run_todo_group( %test )"
Run a group as \s-1TODO\s0
.ie n .IP "$bool = $fennec\->run_test_group( \e%test )" 4
.el .IP "\f(CW$bool\fR = \f(CW$fennec\fR\->run_test_group( \e%test )" 4
.IX Item "$bool = $fennec->run_test_group( %test )"
Run a test group.
.ie n .IP "( $bool, $error ) = $fennec\->run_test_eval( \e%test )" 4
.el .IP "( \f(CW$bool\fR, \f(CW$error\fR ) = \f(CW$fennec\fR\->run_test_eval( \e%test )" 4
.IX Item "( $bool, $error ) = $fennec->run_test_eval( %test )"
Does the actual test running in an eval to capture errors.
.ie n .IP "$fennec\->test_eval_error( $bool, $error, \e%test )" 4
.el .IP "\f(CW$fennec\fR\->test_eval_error( \f(CW$bool\fR, \f(CW$error\fR, \e%test )" 4
.IX Item "$fennec->test_eval_error( $bool, $error, %test )"
Handle a test eval error.
.SH "Extending Fennec::Lite"
.IX Header "Extending Fennec::Lite"
In the tradition of the Fennec project, Fennec::Lite is designed to be
extensible. You can even easily subclass/edit Fennec::Lite to work with
alternatives to Test::Builder.
.SS "\s-1METHODS TO OVERRIDE\s0"
.IX Subsection "METHODS TO OVERRIDE"
.ie n .IP "$fennec\->\fIinit()\fR" 4
.el .IP "\f(CW$fennec\fR\->\fIinit()\fR" 4
.IX Item "$fennec->init()"
Called by new prior to returning the newly constructed object. In Fennec::Lite
this loads Test::Builder and puts a reference to it in the \s-1\fITB\s0()\fR accessor. If
you do want to replace Test::Builder in your subclass you may do so by
overriding \fIinit()\fR.
.ie n .IP "$fennec\->run_skip_test( \e%test )" 4
.el .IP "\f(CW$fennec\fR\->run_skip_test( \e%test )" 4
.IX Item "$fennec->run_skip_test( %test )"
Calls Test::Builder\->skip( \f(CW$reason\fR ), then returns true. Override this if you
replace Test::Builder in your subclass.
.ie n .IP "$fennec\->run_todo_group( \e%test )" 4
.el .IP "\f(CW$fennec\fR\->run_todo_group( \e%test )" 4
.IX Item "$fennec->run_todo_group( %test )"
Calls \fIrun_test_eval()\fR in a \s-1TODO\s0 environment. Currently uses Test::Builder to
start/stop \s-1TODO\s0 mode around the test. Override this if you wish to replace
Test::Builder.
.ie n .IP "$fennec\->test_eval_error( $bool, $error, \e%test )" 4
.el .IP "\f(CW$fennec\fR\->test_eval_error( \f(CW$bool\fR, \f(CW$error\fR, \e%test )" 4
.IX Item "$fennec->test_eval_error( $bool, $error, %test )"
Handle an exception thrown in a test group method. Currently calls
Test::Bulder\->ok( 0, \s-1GROUP_NAME \s0).
.ie n .IP "@list = \fImust_load()\fR" 4
.el .IP "\f(CW@list\fR = \fImust_load()\fR" 4
.IX Item "@list = must_load()"
Returns a list of modules that \s-1MUST\s0 be loaded into tho calling class (unless
used in \s-1OO\s0 form). This is currently only Test::More.
.ie n .IP "@list = \fImay_load()\fR" 4
.el .IP "\f(CW@list\fR = \fImay_load()\fR" 4
.IX Item "@list = may_load()"
Returns a list of modules that should be loaded only if they are installed.
.ie n .IP "$name_to_code_ref = \fImodule_loaders()\fR" 4
.el .IP "\f(CW$name_to_code_ref\fR = \fImodule_loaders()\fR" 4
.IX Item "$name_to_code_ref = module_loaders()"
Returns a hashref containing package => sub { ... }. Use this if you need to
load modules in a custom way, currently Test::More has a special loader in here
to account for plans.
.ie n .IP "$fennec\->\fIimport_hook()\fR" 4
.el .IP "\f(CW$fennec\fR\->\fIimport_hook()\fR" 4
.IX Item "$fennec->import_hook()"
Called on the instance that was created by \fIimport()\fR, runs at the very end of
the import process. Currently does nothing.
.SH "FENNEC PROJECT"
.IX Header "FENNEC PROJECT"
This module is part of the Fennec project. See Fennec for more details.
Fennec is a project to develop an extensible and powerful testing framework.
Together the tools that make up the Fennec framework provide a potent testing
environment.
.PP
The tools provided by Fennec are also useful on their own. Sometimes a tool
created for Fennec is useful outside the greater framework. Such tools are
turned into their own projects. This is one such project.
.IP "Fennec \- The core framework" 2
.IX Item "Fennec - The core framework"
The primary Fennec project that ties them all together.
.SH "AUTHORS"
.IX Header "AUTHORS"
Chad Granum exodist7@gmail.com
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2010 Chad Granum
.PP
Fennec-Lite is free software; Standard perl license.
.PP
Fennec-Lite is distributed in the hope that it will be useful, but \s-1WITHOUT ANY
WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS
FOR A PARTICULAR PURPOSE. \s0 See the license for more details.