Fennec::Lite(3pm)

📦
version 0.4 · 6 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

🎀 NAME 🎀

Bestie, meet Fennec::Lite — it's the Minimalist Fennec, like, the commonly used bits and nothing else. This is the Fennec::Lite(3pm) page from the User Contributed Perl Documentation, and yes we are going to read the whole thing together, no skimming. 💖

✨ DESCRIPTION ✨

Okay so here's the tea: Fennec does a ton, but adopting all of it at once is a lot, even for you, and you're iconic. It's also a big ol' project that hasn't been fully split into component projects yet. So Fennec::Lite takes a minimalist approach — it does for Fennec what Mouse does for Moose. Cute, right? 🐭

Fennec::Lite is a single module file with no non-core dependencies. Any project can use it, either directly or by literally copying it into your project. The file itself is less than 300 lines of code at the time of this writing — and that count includes whitespace. Slay. 💅

Heads up though: this module does not cover any of the more advanced features, like result capturing or SPEC workflows. Nope. This module only covers test grouping and group randomization. 🎲

You can also use the FENNEC_ITEM variable with a group name or a line number to run a specific test group only. And Test::Builder is used under the hood for TAP output. 🫶

🌸 SYNOPSIS 🌸

SIMPLE

#!/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();

ADVANCED

#!/usr/bin/perl
use strict;
use warnings;

use Fennec::Lite
    plan => 8,
    random => 1,
    testing => 'My::Class',
    alias => [
        'My::Class::ThingA'
    ],
    alias_to => {
        TB => 'My::Class::ThingB',
    };

# 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" );

Pure OO Interface

#!/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();

🦋 IMPORTED FOR YOU 🦋

When you use Fennec::Lite, Test::More is automatically imported for you. No extra steps, we got you. 🫶

On top of that, Test::Warn and Test::Exception will also be loaded — but only if they're installed. If they're not there, whatever, no drama. 🌈

💜 IMPORT ARGUMENTS 💜

    use Fennec::Lite %ARGS
  • plan => 'no_plan' || $count — the plan to pass into Test::More.
  • random => $bool — true by default. When it's true, test groups get run in a random order. 🎲
  • testing => $CLASS_NAME — declare what class you are testing. Gives you $CLASS and CLASS(), and both of those are simply the name of the class being tested.
  • alias => @PACKAGES — create alias functions for 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. ✨
  • alias_to => { $ALIAS => $PACKAGE, ... } — define aliases yourself: keys are alias names, values are the package names they should return.

🔥 RUNNING IN RANDOM ORDER 🔥

By default, test groups get run in a random order. The random seed is the current date (YYYYMMDD). Why, you ask? So the order doesn't change on the day you're editing your code — but the order will change daily, which lets automated testing catch order-dependent failures. Chaos, but make it useful. 💀

You can manually set the random seed to reproduce a failure. The FENNEC_SEED environment variable will be used as the seed when it's present. 👑

$ FENNEC_SEED="20100915" prove -I lib -v t/*.t

🍓 RUNNING SPECIFIC GROUPS 🍓

You can use the FENNEC_ITEM variable with a group name or a line number to run a specific test group only. So specific. So targeted. 🎯

$ FENNEC_ITEM="22" prove -I lib -v t/MyTest.t
$ FENNEC_ITEM="Test Group A" prove -I lib -v t/MyTest.t

This can easily be integrated into an editor such as vim or emacs. iykyk. 💅

👑 EXPORTED FUNCTIONS 👑

tests $name => $coderef,
tests $name => ( code => $coderef, todo => $reason )
tests $name => ( code => $coderef, skip => $reason )
tests $name => ( sub => $coderef )
tests $name => ( method => $coderef )
  • tests — declare a test group. The first argument must always be the test group name. In the two-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. 🌸
  • run_tests( %params ) — instantiate an instance of the test class, passing %params 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, so you may continue to declare tests and call run_tests again to run the new tests. 🔁
  • fennec() — returns the instance of Fennec::Lite created when you imported it. This is the instance that tests() and run_tests() act upon.
  • fennec_accessors( @NAMES ) — quickly generate get/set accessors for your test class. You could alternatively do it manually or use Moose. Whatever vibes best for you. ✨

🧚 PURE OO INTERFACE METHODS 🧚

  • $tests_ref = $fennec->tests() — get a reference to the array of tests that have been added since the last run.
  • $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.
  • $seed = $fennec->seed( $newseed ) — get/set the random seed that will be used to re-seed srand() before randomizing tests, as well as before each test.
  • $bool = $fennec->random( $bool ) — turn random on/off.
  • $fennec->add_tests( $name => sub { ... }) $fennec->add_tests( $name, %args, method => sub { ... }) — add a test group.
  • $fennec->run_tests( %test_class_construction_args ) — run the test groups.
  • $bool = $fennec->run_skip_test( \%test ) — run a skip test (really just returns true).
  • $bool = $fennec->run_todo_group( \%test ) — run a group as TODO.
  • $bool = $fennec->run_test_group( \%test ) — run a test group.
  • ( $bool, $error ) = $fennec->run_test_eval( \%test ) — does the actual test running in an eval to capture errors.
  • $fennec->test_eval_error( $bool, $error, \%test ) — handle a test eval error.

🌈 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. Go off, honestly. 👑

METHODS TO OVERRIDE

  • $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 TB() accessor. If you do want to replace Test::Builder in your subclass you may do so by overriding init().
  • $fennec->run_skip_test( \%test ) — calls Test::Builder->skip( $reason ), then returns true. Override this if you replace Test::Builder in your subclass.
  • $fennec->run_todo_group( \%test ) — calls run_test_eval() in a TODO environment. Currently uses Test::Builder to start/stop TODO mode around the test. Override this if you wish to replace Test::Builder.
  • $fennec->test_eval_error( $bool, $error, \%test ) — handle an exception thrown in a test group method. Currently calls Test::Builder->ok( 0, GROUP_NAME ).
  • @list = must_load() — returns a list of modules that MUST be loaded into the calling class (unless used in OO form). This is currently only Test::More.
  • @list = may_load() — returns a list of modules that should be loaded only if they are installed.
  • $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.
  • $fennec->import_hook() — called on the instance that was created by import(), runs at the very end of the import process. Currently does nothing.

💖 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. 💪

The tools provided by Fennec are also useful on their own. Sometimes a tool created for Fennec is useful outside the greater framework, and such tools are turned into their own projects. This is one such project. ✨

  • Fennec — The core framework
    • The primary Fennec project that ties them all together.

🫶 AUTHORS 🫶

Chad Granum exodist7@gmail.com

Copyright (C) 2010 Chad Granum

Fennec-Lite is free software; Standard perl license.

Fennec-Lite is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for more details.

Okay bestie that's the whole page, you read every single line and I'm so proud of you. 🥹💖

And that's a wrap, my love — this was Fennec::Lite(3pm) from perl v5.36.0, dated 2022-10-13. Go write some test groups, you absolute icon. 🌟💅🦋

📦 where this page comes from