/ 
Fennec-0.020
River stage one • 9 direct dependents • 9 total dependents
/ Fennec::Manual::TestSuite

NAME

Fennec::Manual::TestSuite - Guide to managing a test suite with Fennec

DESCRIPTION

This guide will get you started writing a Fennec based test suite for your dist. The first step is to generate the t/Fennec.t file. A suitable default can be generated using the fennec_init command within your project directory.

GETTING STARTED

~/my/project $ fennec_init

This should have created t/Fennec.t, here is an example:

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

use Fennec::Runner;
'Fennec::Runner'->init(
    collector => 'Files',
    cull_delay => .01,
    default_asserts => [qw/Core/],
    default_workflows => [qw/Spec Case Methods/],
    filetypes => [qw/ Module /],
    handlers => [qw/ TAP /],
    ignore => undef,
    parallel_files => 2,
    parallel_tests => 2,
    random => 1,
);

Runner->run_tests;

This file serves multiple purposes

Configuration file

This is where you configure the Runner than runs all the fennec tests. Other fennec tools will look for this file and use the configuration it provides. fennec_prove is one example of a tool that uses this config.

See the section CONFIGURATION DETAILS, or the docs for Fennec::Runner for more details on arguments for Fennec::Runner->init;

Works with prove

You can use prove -I lib t/Fennec.t to run your tests. Module::Build and Module::Install already know how to run Fennec tests because of this.

TEST FILES

Fennec has a plugins system that means test files can be anything, but the default is perl modules placed under t/.

NOTE If you have not already done so, please read Fennec::Manual::Quickstart for a better introduction to tests within files.

Lets say you have a file lib/MyPackage/MyThing.pm. Lets make a Fennec test for it, you can name the test file anything you want, but the recommended name is t/MyPackage/MyThing.pm. It is recommended that you mirror the layout of your lib directory in your tests.

t/MyPackage/MyThing.pm:

package TEST::MyPackage::MyThing;
use strict;
use warnings;
use Fennec;

tests hello_world_group => sub {
    my $self = shift;
    ok( 1, "Hello world" );
};

1;

NOTE Unlike the standalone tests, you should not end the test file with done_testing().

The package can be anything except main, no 2 test files should implement the same package, and it is recommended that your package be the same as the package being tested with at least 1 change such as the TEST:: prefix.

You can use the 'tests' keyword to define as many test groups as you want. Within the test groups you can use all the core asserts by default (see Fennec::Assert::Core). This list includes all functions normally exported by Test::More, Test::Warn, and Test::Exception.

You can also use the fennec_scaffold.pl command line utility to automatically generate a basic test file for every module under lib. See Fennec::Manual::CommandLine for more details.

ADVANCED USAGE

Choosing assert plugins

By default Fennec::Assert::Core is loaded, which in turn loads all Core assert modules. You can specify alternate ones as well.

The following will load Fennec::Assert::TBCore assert libraries instead of Core libraries. These are wrappers around Test::Builder based test modules.

use Fennec asserts => [ 'TBCore' ]

You can also directly use assert packages:

use Fennec asserts => [];
use Fennec::Assert::Core::More;
use Fennec::Assert::TBCore::Exception;

You can also use Test::Builder based tools*:

use Fennec asserts => [];
use Test::More;
Choosing workflow plugins
use Fennec workflows => [ 'Spec' ];

You can also directly use workflow packages:

use Fennec::Workflow::Spec;

CONFIGURATION DETAILS

random => $bool

Set to true to randomize test file order and test group order. Randomization of test groups can be overriden within test files.

cull_delay => $float

How long to wait between checking for test results. Result are generated in other processes and must be collected regularly, this sets how often that will occur. Higher numbers mean results are printed less often, but more at a time.

collector => $name

Choose which collector to use. Include only the portion fo the package name following 'Fennec::Collector'.

default_asserts => \@names

Arrayref of assert libraries to use by default. Include only the portion of the package name following Fennec::Assert.

default_workflows => \@names

Arrayref of workflow libraries to use by default. Include only the portion of the package name following Fennec::Workflow.

handlers => \@names

Arrayref of handler packages to which results should be sent. Every result will be sent to every handler. Include only the portion of the package name following Fennec::Handler.

filetypes => \@names

Arrayref of filetypes to load. Include only the portion of the name following Fennec::Fileloader.

ignore => \@patterns || undef

Arrayref of regexes or complete names of files to ignore.

Parallelization

Note, to calculate how many processes might run at a time you use this formula:

$max_processes = 1 +
                ( $parallel_files >= 2
                    ? $parallel_files
                    : 0
                ) +
                ( $parallel_tests
                    ? $parallel_files * $parallel_tests
                    : 0
                );

This is because Fennec itself is a process, then it starts a process for each test file, then it starts a process for each test group. If one of these options is set to 1 then no new processes will be created for it. If both are set to 1 then Fennec will only ever have 2 process. The second process is due to Fennec always forking before loading a test file, this is done to prevent bleed between test files.

parallel_files => $int

How many files to run in parallel, do not set this too high.

parallel_tests => $int

How many test groups to run in parallel, do not set this too high.

DOCUMENTATION

Tests

Fennec::Manual::Tests - Examples of different fennec tools.

Fennec Based Test Suite

Fennec::Manual::TestSuite - How to create a Fennec based test suite.

Standalone

Fennec::Manual::Standalone - Write fennec tests that stand on their own.

MISSION

Fennec::Manual::Mission - Why does Fennec exist?

MANUAL

Fennec::Manual - Advanced usage and extending Fennec.

AUTHORS

Chad Granum exodist7@gmail.com

COPYRIGHT

Copyright (C) 2010 Chad Granum

Fennec is free software; Standard perl licence.

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.