Fennec...Fennec(3pm)

💖 NAME 💖

Fennec::Manual::CustomFennec — the whole entire guide to customizing Fennec for your project. Like, your project specifically. Bestie-coded, fr fr.

---

✨ DESCRIPTION ✨

Okay so here's the tea: Fennec is out here automatically loading a bunch of utilities for you, no questions asked. And it just assumes you wanna use Test::Builder. Rude? A little. Convenient? Also yes. 💅

But if you want control — and you know we love control — you can subclass Fennec. Subclassing lets you say exactly which utilities you want and exactly which collector to use. The whole point is that you can then use your subclass in every single test file instead of copy-pasting this into each one:

use Fennec ( YOUR CONFIG OPTIONS )

Never copy-paste again. That's the dream. 🦋

---

🌸 FENNEC SUBCLASS 🌸

You can subclass Fennec and override the defaults sub to your own specification. The defaults sub should return a list of Fennec import argument key-pairs.

Here's the vibe, in My/Fennec.pm:

use strict;
use warnings;

use base 'Fennec';

sub defaults {
    my $class = shift;
    my %params = $class->SUPER::defaults;

    # Add a new autoloading utility with import arguments.
    push @{ $params->{utils} } => 'My::Util';
    $params->{'My::Util'} = [ 'util' => 'args' ];

    # Default number of concurrent procs for the test to use.
    $params->{parallel} = 3;

    return %params;
}

sub after_import {
    my $class = shift;
    my ($info) = @_;
    # $info is a hashref with the importer, runner, and importer meta
    # object, and some other fun things.

    # Example of adding cases to any Fennec test that uses this subclass:
    # The first arg to add case should be an array matching the return of
    # caller. The idea is to give us the start and end line, as well as
    # file name where the case is defined. normally the exports from
    # Test::Workflow provide that for you, but at this low-level we need to
    # provide it ourselfs. Since we define the subs here, we give current
    # line/file. Use the importer for package name.
    $info->{layer}->add_case([$info->{importer}, __FILE__, __LINE__], case_a => sub { $main::CASE_A = 1 });
    $info->{layer}->add_case([$info->{importer}, __FILE__, __LINE__], case_b => sub { $main::CASE_B = 1 });
}

1;

Look at that. Chef's kiss. 🎀 Notice that after_import gives you $info, which is a hashref holding the importer, the runner, the importer meta object, and some other fun things. And yes, in that example we're adding cases with add_case, and the first arg has to be an array matching the return of caller — that's how it knows the start line, end line, and file name where the case is defined. Normally Test::Workflow's exports hand you that for free, but down here at this low level you have to provide it yourself. Since the subs are defined right there, we hand it __FILE__ and __LINE__, and we use the importer for the package name. iykyk. 🧚

---

🦋 CUSTOM COLLECTOR 🦋

The collector has 2 jobs, and it's carrying both of them like the icon it is:

1. In the parent process, it's responsible for gathering all test results from the child processes.
2. In the child processes, it's responsible for sending results to the parent process.

So if TAP is not your thing, or you wanna use Fennec with existing tests that do not use Test::Builder, you can create a custom collector to work for you. 💜

Documentation for a custom Collector lives in the Fennec::Collector POD.

Heads up bestie: if you're going custom-collector mode, go read the Fennec::Collector POD. That's where the real lore is.

---

👑 AUTHORS 👑

Chad Granum exodist7@gmail.com

---

💖 COPYRIGHT 💖

Copyright (C) 2013 Chad Granum

Fennec is free software; Standard perl license (GPL and Artistic).

Fennec 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.

No cap on the warranty disclaimer: it really does say there's no warranty, and the whole "merchantability" and "fitness for a particular purpose" thing is fully disclaimed. Read the license for the deets. 🙈

---

And that's the whole page, bestie. This was Fennec...Fennec(3pm) from the User Contributed Perl Documentation, running on perl v5.36.0, dated 2022-12-02. Periodt. 💅✨